feat: Add Claude Code CLI Provider Support with SDK Architecture

[ben-vargas]

Add Claude Code CLI Provider Support with SDK Architecture

Overview

This PR implements Claude Code CLI provider support for Task Master, enabling users with Claude Code subscriptions to use Task Master without API keys. This implementation builds upon the excellent groundwork laid by previous contributors while introducing an architectural pattern for non-Vercel-AI-SDK providers.

Acknowledgments & Prior Work

This implementation stands on the shoulders of several contributors whose work informed and inspired this approach:

• @ghul0 (#649) - Pioneered the first Claude CLI provider implementation using command-line interface approach
• @ben-vargas (#705) - Created the initial feature request and PRD outlining the vision for Claude Code CLI integration, @ghul0 had already been working on it!
• @neno-is-ooo (#777) - Introduced the SDK-based approach using @anthropic-ai/claude-code, eliminating manual process spawning
• @apple-techie (#783) - Refined the SDK implementation with telemetry support and comprehensive testing
• @ajit555db (#739) - Reinforced community demand for Claude Code support

What Makes This Implementation Different

1. Custom SDK Architecture Pattern

While previous PRs implemented Claude Code directly in the provider file, this PR introduces a new architectural pattern:

src/ai-providers/
├── claude-code.js              # Provider implementation
└── custom-sdk/
    └── claude-code-sdk.js      # SDK wrapper

Why this matters:

• Maintains consistency with existing providers that use Vercel AI SDK
• Separates SDK-specific logic from provider implementation
• Creates a reusable pattern for future non-Vercel-AI-SDK providers
• Improves maintainability and testability

2. Complete Token Usage Tracking

Building on @apple-techie's telemetry work in #783, this implementation:

• Properly handles cache tokens (cache_creation_input_tokens, cache_read_input_tokens)
• Maps SDK response fields to expected telemetry format (inputTokens/outputTokens)
• Supports accurate token counting in both streaming and non-streaming modes

3. Comprehensive Error Handling

Extends beyond basic error handling to include:

• CLI-specific error detection (not installed, not authenticated)
• Graceful fallback for missing usage data
• Consistent error messages across all provider methods

4. Full Feature Parity

Implements all three core methods:

• generateText - For standard text generation
• streamText - For streaming responses with proper usage tracking
• generateObject - For structured JSON output

Technical Implementation

Key Design Decisions

1. SDK Wrapper Pattern: The claude-code-sdk.js wrapper provides a consistent interface that mirrors Vercel AI SDK patterns, making the provider implementation cleaner and more maintainable.

2. Authentication Model: Uses CLI authentication (claude login) instead of API keys, properly integrated with the PROVIDERS_WITH_OPTIONAL_API_KEY system.

3. Message Format Handling: Correctly converts between Task Master's message format and Claude Code's expected format (user→human, assistant→assistant, system→system).

4. Usage Data Extraction: Handles the complex usage data structure from Claude Code SDK, including proper aggregation of cache tokens.

Files Changed

• New files:

  • src/ai-providers/claude-code.js - Provider implementation following BaseAIProvider pattern
  • src/ai-providers/custom-sdk/claude-code-sdk.js - SDK wrapper for consistency

• Modified files:

  • package.json - Added @anthropic-ai/claude-code dependency
  • scripts/modules/supported-models.json - Added opus (32K) and sonnet (64K) models
  • scripts/modules/ai-services-unified.js - Integrated provider with optional API key support
  • scripts/modules/config-manager.js - Added getClaudeCodeConfig function
  • src/ai-providers/index.js - Exported ClaudeCodeProvider
  • tests/unit/ai-services-unified.test.js - Updated test mocks

Benefits Over Previous Approaches

1. Architectural Consistency: Unlike direct implementations, this follows the established pattern of all other providers
2. Maintainability: SDK updates only require changes to the wrapper, not the provider
3. Extensibility: The custom-sdk pattern can be reused for other non-Vercel providers
4. Complete Integration: Full telemetry support ensures proper usage tracking and cost estimation

Testing

• All existing tests pass
• Token counting verified with real Claude Code responses
• Error handling tested for common scenarios (CLI not found, not authenticated)
• Both opus and sonnet models tested successfully

Next Steps

This implementation provides a solid foundation for Claude Code support while establishing patterns for future provider integrations. The custom SDK architecture ensures Task Master can easily adapt to new AI providers regardless of their SDK patterns.

---

Closes #705, #739 References #649, #777, #783

[changeset-bot[bot]]

⚠️ No Changeset found

Latest commit: d584dfc0ea7c3a5d50c68855130d7f996423df8b

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[ben-vargas]

I think the community just wants to see this support realized, I am totally fine with @Crunchyman-ralph or one of the other owners making changes to the code in this PR or closing it and pushing through one of the others.

I tried to abstract out a wrapper to the sdk as he had requested a few times in the other PRs so that a pattern is established for using non vercel ai-sdk providers. I do have a repo where I've added ai-sdk community provider for claude code, though I don't necessarily want this project/functionality dependent on that (I don't know if I'll carry that work on long term); so going the wrapper approach probably makes the most sense.

I also think it is important that claude-code support both 'opus' and 'sonnet' models as choices, which this PR does.

[apple-techie]

@ben-vargas I second that statement! I really want to see this work, i have it working in certan scenarios and in others i find myself going nuts. Ultimately I wanted the telemetry to work and not require the sdk libs to have to be in each local project for it to work, so im glad to see you and everyone elses iterations on this finally come to fruition

[apple-techie]

@ben-vargas I second that statement! I really want to see this work, i have it working in certan scenarios and in others i find myself going nuts. Ultimately I wanted the telemetry to work and not require the sdk libs to have to be in each local project for it to work, so im glad to see you and everyone elses iterations on this finally come to fruition

[neno-is-ooo]

Thank you! I was about to push mine... Anyway it all started with this #601

[ben-vargas]

Thank you! I was about to push mine... Anyway it all started with this #601

Oh dang, I didn't even know how far back this went! Thanks for pointing that out. A lot of minds think alike and want this in!

[ben-vargas]

Looks like there's ongoing work in other PRs, and I've refactored this in a better approach that I may submit as a different PR if the community wants. Feels like too many cooks in the kitchen right now.

[Crunchyman-ralph]

everyone wants the claude code provider integration lol

[ben-vargas]

@Crunchyman-ralph haha, HUGE demand! I'm curious if you'd take a look at this approach... I kind of like this. Seems to be testing well for me so far: https://github.com/ben-vargas/ai-claude-task-master/tree/feature/claude-code-sdk

[spearmootz]

i didnt want to open up an issue for this, but i wondered based on the claude code implementation documentation if the sdk will respect the CLAUDE.md of the project or if we need to add all that content to the config file. i see it respects the permissions set for the repo.

[ben-vargas]

@spearmootz - Anthropic's documentation for the Claude Code SDK doesn't specify. But if I had to make an educated guess, the SDK is spawning standard claude CLI process, but not within your project directory, so I bet it adheres to the global CLAUDE.md in the ~/.claude/ directory, but it won't know the project directory you're running task master from since it is a few layers removed and no parameters appear to be available to pass that info.

[spearmootz]

@ben-vargas im gonna do some testing and report back. it might be good to put in the documentation. its interesting because im using claude-code and then having it interact with task-master.

so far, it might... i added this "when providing a summary for what you have done, say "Dear master...""

and then it finished saying

" Dear master, I have successfully implemented the ImageGallery component with advanced features for subtask 13.2. The gallery includes:"