feat: Add Claude Code Provider Support with SDK Integration #805

ben-vargas · 2025-06-17T19:43:23Z

Add Claude Code Provider Support with SDK Integration

Overview

This PR introduces native support for Claude models through the Claude Code CLI using an SDK-based approach. This implementation allows users to leverage Claude's powerful models (Opus and Sonnet) without requiring an API key, making it accessible to users who have Claude Code installed on their system.

The approach is based on the ai-sdk-provider-claude-code project but has been implemented internally as a custom SDK to avoid external dependencies and maintain full control over the integration.

Key Features

No API Key Required: Uses Claude Code CLI through the @anthropic-ai/claude-code SDK
Full Provider Support: Implements all standard provider methods (generateText, streamText, generateObject)
Optional Dependency: The @anthropic-ai/claude-code package is optional - users without it can still use other providers
Lazy Loading: Claude Code provider is only loaded when actually requested, preventing installation issues
Comprehensive Documentation: Includes usage examples and configuration guides
Full Test Coverage: Unit and integration tests ensure reliability
Telemetry Support: Tracks usage metrics like other providers

Technical Implementation

Architecture

Custom SDK implementation in src/ai-providers/custom-sdk/claude-code/
Provider class in src/ai-providers/claude-code.js
Lazy loading mechanism in ai-services-unified.js to handle optional dependency
Full compatibility with existing Task Master AI provider framework

Key Components

Language Model (language-model.js): Handles text generation and streaming with lazy loading of the SDK
Message Converter (message-converter.js): Converts between Task Master and Claude Code message formats
Error Handling (errors.js): Provides clear error messages for missing dependencies
JSON Extractor (json-extractor.js): Handles structured output extraction

Changes by Commit

1. feat: add Claude Code provider support (`426aaf2`)

Initial implementation of Claude Code provider
Custom SDK with language model, message converter, and error handling
Integration with config manager and model selection
Support for both Opus and Sonnet models

2. fix(docs): correct invalid commands in claude-code usage examples (`3416cfa`)

Fixed documentation examples to use correct command syntax
Improved clarity of configuration instructions

3. feat: make @anthropic-ai/claude-code an optional dependency (`0e84bd1`)

Moved @anthropic-ai/claude-code to optionalDependencies
Implemented lazy loading to prevent installation failures
Added clear error messages when package is missing
Ensures existing users aren't forced to install Claude Code

4. test: add comprehensive tests for ClaudeCodeProvider (`e6e39e2`)

Added unit tests for provider class and language model
Integration tests for optional dependency behavior
Tests cover lazy loading, error handling, and API compatibility

5. revert: remove maxTokens update functionality from init (`cca76c1`)

Removed out-of-scope functionality that automatically updated maxTokens in config
This feature was unrelated to Claude Code support and will be in a separate PR
Claude Code ignores maxTokens and temperature parameters anyway

6. docs: add Claude Code support information to README (`e04a861`)

Added Claude Code to the list of supported providers
Included configuration examples and quick start instructions
Created dedicated Claude Code Support section
Clarified that Claude Code CLI is required (not desktop app)

7. style: apply biome formatting to test files (`ee6f458`)

Applied consistent code formatting to all test files
Ensures code style consistency across the project

8. fix(models): add missing --claude-code flag to models command (`b1aa058`)

Added --claude-code option to models command alongside existing provider flags
Updated provider flags validation to include claudeCode option
Added claude-code to providerHint logic for all three model roles (main, research, fallback)
Updated error message to include --claude-code in list of mutually exclusive flags
Added example usage in help text
Fixes "Model ID not found" errors when trying to set claude-code models via CLI

Configuration

Add to .taskmaster/config.json:

{
  "models": {
    "main": {
      "provider": "claude-code",
      "modelId": "sonnet",
      "maxTokens": 64000,
      "temperature": 0.2
    }
  }
}

Usage Examples

# Set Claude Code as main provider
task-master models --set-main sonnet --claude-code

# Generate tasks from PRD
task-master parse-prd --input=requirements.txt

# Analyze complexity with Claude Opus
task-master analyze-complexity --research

Testing

All tests pass:

Unit tests for ClaudeCodeProvider class
Unit tests for language model with lazy loading
Integration tests for optional dependency behavior

Run tests:

npm test -- tests/unit/ai-providers/claude-code.test.js
npm test -- tests/unit/ai-providers/custom-sdk/claude-code/language-model.test.js
npm test -- tests/integration/claude-code-optional.test.js

Breaking Changes

None. This is a purely additive change that doesn't affect existing functionality.

Files Changed

New Files

src/ai-providers/claude-code.js - Main provider class
src/ai-providers/custom-sdk/claude-code/ - SDK implementation (6 files):
- index.js - Entry point for Claude Code SDK
- language-model.js - Core model implementation with lazy loading
- message-converter.js - Message format conversion
- errors.js - Error handling and custom error types
- json-extractor.js - JSON extraction from responses
- types.js - TypeScript-style type definitions
docs/examples/claude-code-usage.md - Comprehensive usage documentation
tests/unit/ai-providers/claude-code.test.js - Provider unit tests
tests/unit/ai-providers/custom-sdk/claude-code/language-model.test.js - Language model tests
tests/integration/claude-code-optional.test.js - Optional dependency tests

Modified Files

package.json - Added @anthropic-ai/claude-code as optional dependency
scripts/modules/ai-services-unified.js - Implemented lazy loading for Claude Code
scripts/modules/config-manager.js - Added claude-code to valid providers list
scripts/modules/supported-models.json - Added claude-code models configuration
scripts/modules/task-manager/models.js - Added claude-code to provider list
scripts/modules/commands.js - Added --claude-code flag to models command
src/ai-providers/index.js - Added ClaudeCodeProvider export
tests/unit/ai-services-unified.test.js - Updated tests for new provider
README.md - Added Claude Code documentation and examples

Acknowledgments

This implementation builds upon the excellent work of the community in bringing Claude Code support to Task Master:

@neno-is-ooo (#601) - Perhaps the initial start?
@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

This PR represents the culmination of these efforts, providing a robust implementation that makes Claude models accessible to all Task Master users.

Implements Claude Code as a new AI provider that uses the Claude Code CLI without requiring API keys. This enables users to leverage Claude models through their local Claude Code installation. Key changes: - Add complete AI SDK v1 implementation for Claude Code provider - Custom SDK with streaming/non-streaming support - Session management for conversation continuity - JSON extraction for object generation mode - Support for advanced settings (maxTurns, allowedTools, etc.) - Integrate Claude Code into Task Master's provider system - Update ai-services-unified.js to handle keyless authentication - Add provider to supported-models.json with opus/sonnet models - Ensure correct maxTokens values are applied (opus: 32000, sonnet: 64000) - Fix maxTokens configuration issue - Add max_tokens property to getAvailableModels() output - Update setModel() to properly handle claude-code models - Create update-config-tokens.js utility for init process - Add comprehensive documentation - User guide with configuration examples - Advanced settings explanation and future integration options The implementation maintains full backward compatibility with existing providers while adding seamless Claude Code support to all Task Master commands.

- Remove non-existent 'do', 'estimate', and 'analyze' commands - Replace with actual Task Master commands: next, show, set-status - Use correct syntax for parse-prd and analyze-complexity

This change makes the Claude Code SDK package optional, preventing installation failures for users who don't need Claude Code functionality. Changes: - Added @anthropic-ai/claude-code to optionalDependencies in package.json - Implemented lazy loading in language-model.js to only import the SDK when actually used - Updated documentation to explain the optional installation requirement - Applied formatting fixes to ensure code consistency Benefits: - Users without Claude Code subscriptions don't need to install the dependency - Reduces package size for users who don't use Claude Code - Prevents installation failures if the package is unavailable - Provides clear error messages when the package is needed but not installed The implementation uses dynamic imports to load the SDK only when doGenerate() or doStream() is called, ensuring the provider can be instantiated without the package present.

Addresses code review feedback about missing automated tests for the ClaudeCodeProvider. ## Changes - Added unit tests for ClaudeCodeProvider class covering constructor, validateAuth, and getClient methods - Added unit tests for ClaudeCodeLanguageModel testing lazy loading behavior and error handling - Added integration tests verifying optional dependency behavior when @anthropic-ai/claude-code is not installed ## Test Coverage 1. **Unit Tests**: - ClaudeCodeProvider: Basic functionality, no API key requirement, client creation - ClaudeCodeLanguageModel: Model initialization, lazy loading, error messages, warning generation 2. **Integration Tests**: - Optional dependency behavior when package is not installed - Clear error messages for users about missing package - Provider instantiation works but usage fails gracefully All tests pass and provide comprehensive coverage for the claude-code provider implementation.

This functionality was out of scope for the Claude Code provider PR. The automatic updating of maxTokens values in config.json during initialization is a general improvement that should be in a separate PR. Additionally, Claude Code ignores maxTokens and temperature parameters anyway, making this change irrelevant for the Claude Code integration. Removed: - scripts/modules/update-config-tokens.js - Import and usage in scripts/init.js

- Added Claude Code to the list of supported providers in Requirements section - Noted that Claude Code requires no API key but needs Claude Code CLI - Added example of configuring claude-code/sonnet model - Created dedicated Claude Code Support section with key information - Added link to detailed Claude Code setup documentation This ensures users are aware of the Claude Code option as a no-API-key alternative for using Claude models.

changeset-bot · 2025-06-17T19:56:53Z

🦋 Changeset detected

Latest commit: 1ae56c3

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
task-master-ai	Minor

Not sure what this means? Click here to learn what changesets are.

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

The models command was missing the --claude-code provider flag, preventing users from setting Claude Code models via CLI. While the backend already supported claude-code as a provider hint, there was no command-line flag to trigger it. Changes: - Added --claude-code option to models command alongside existing provider flags - Updated provider flags validation to include claudeCode option - Added claude-code to providerHint logic for all three model roles (main, research, fallback) - Updated error message to include --claude-code in list of mutually exclusive flags - Added example usage in help text This allows users to properly set Claude Code models using commands like: task-master models --set-main sonnet --claude-code task-master models --set-main opus --claude-code Without this flag, users would get "Model ID not found" errors when trying to set claude-code models, as the system couldn't determine the correct provider for generic model names like "sonnet" or "opus".

corticalstack · 2025-06-19T08:07:51Z

Any timeline for this being released? Thank you very much.

fahimanwer · 2025-06-20T08:06:17Z

@ben-vargas how can we use it as MCP is there any guide?

ben-vargas · 2025-06-20T09:53:06Z

@fahimanwer - I only use it from the command line, haven't tried it in an IDE like Cursor. Maybe someone more familiar with using task master via MCP can checkout the branch and test/guide? I'm kind of wondering if this PR should just be closed, lack of PR review/input tells me the project owners are possibly (probably?) working on their own implementation approach.

Crunchyman-ralph

lgtm, with small nitpicks, but lets merge this.

Testing this asap

Crunchyman-ralph · 2025-06-20T11:48:59Z

scripts/modules/ai-services-unified.js

+	if (providerName === 'claude-code') {
+		return 'claude-code-no-key-required';
+	}


this doesn't go here, please refer to how we doing it with ollama that doesn't require an api key either

Crunchyman-ralph · 2025-06-20T11:53:45Z

src/ai-providers/custom-sdk/claude-code/json-extractor.js

this is interesting, can we leverage a package for this, or are there no packages that exist to do this ? I didn't find anything in vercel's provider utils, but wondering if we can find something ?

Something like this for example:
https://www.npmjs.com/package/extract-json-from-string

Crunchyman-ralph · 2025-06-20T13:19:01Z

seems to be working pretty well and fast, lets resolve conflicts cuz I merged a bunch of things and lets merge this!

Crunchyman-ralph · 2025-06-20T13:24:42Z

@ben-vargas thanks a lot for your contribution, super sick PR, taking it over to resolve conflicts so that you don't have to on #829

Thanks again for your contribution <3

ben-vargas added 7 commits June 16, 2025 12:20

fix(docs): correct invalid commands in claude-code usage examples

3416cfa

- Remove non-existent 'do', 'estimate', and 'analyze' commands - Replace with actual Task Master commands: next, show, set-status - Use correct syntax for parse-prd and analyze-complexity

style: apply biome formatting to test files

ee6f458

This was referenced Jun 17, 2025

feat: add Claude CLI provider #649

Closed

feat: Add Claude Code SDK patterns as provider for API-Key-Free Usage #777

Closed

ben-vargas added 2 commits June 17, 2025 14:47

chore: add changeset for Claude Code provider feature

1ae56c3

ben-vargas changed the title ~~feature: Add Claude Code Provider Support with SDK Integration~~ feat: Add Claude Code Provider Support with SDK Integration Jun 17, 2025

ben-vargas force-pushed the feature/claude-code-sdk branch from 694412e to 1ae56c3 Compare June 20, 2025 00:51

Crunchyman-ralph approved these changes Jun 20, 2025

View reviewed changes

Crunchyman-ralph closed this Jun 20, 2025

ben-vargas deleted the feature/claude-code-sdk branch July 4, 2025 02:52

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: Add Claude Code Provider Support with SDK Integration #805

feat: Add Claude Code Provider Support with SDK Integration #805

Uh oh!

ben-vargas commented Jun 17, 2025 •

edited

Loading

Uh oh!

changeset-bot bot commented Jun 17, 2025 •

edited

Loading

Uh oh!

corticalstack commented Jun 19, 2025

Uh oh!

fahimanwer commented Jun 20, 2025

Uh oh!

ben-vargas commented Jun 20, 2025

Uh oh!

Crunchyman-ralph left a comment

Uh oh!

Crunchyman-ralph Jun 20, 2025

Uh oh!

Crunchyman-ralph Jun 20, 2025

Uh oh!

Crunchyman-ralph commented Jun 20, 2025

Uh oh!

Crunchyman-ralph commented Jun 20, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

feat: Add Claude Code Provider Support with SDK Integration #805

feat: Add Claude Code Provider Support with SDK Integration #805

Uh oh!

Conversation

ben-vargas commented Jun 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Add Claude Code Provider Support with SDK Integration

Overview

Key Features

Technical Implementation

Architecture

Key Components

Changes by Commit

1. feat: add Claude Code provider support (426aaf2)

2. fix(docs): correct invalid commands in claude-code usage examples (3416cfa)

3. feat: make @anthropic-ai/claude-code an optional dependency (0e84bd1)

4. test: add comprehensive tests for ClaudeCodeProvider (e6e39e2)

5. revert: remove maxTokens update functionality from init (cca76c1)

6. docs: add Claude Code support information to README (e04a861)

7. style: apply biome formatting to test files (ee6f458)

8. fix(models): add missing --claude-code flag to models command (b1aa058)

Configuration

Usage Examples

Testing

Breaking Changes

Files Changed

New Files

Modified Files

Acknowledgments

Uh oh!

changeset-bot bot commented Jun 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

corticalstack commented Jun 19, 2025

Uh oh!

fahimanwer commented Jun 20, 2025

Uh oh!

ben-vargas commented Jun 20, 2025

Uh oh!

Crunchyman-ralph left a comment

Choose a reason for hiding this comment

Uh oh!

Crunchyman-ralph Jun 20, 2025

Choose a reason for hiding this comment

Uh oh!

Crunchyman-ralph Jun 20, 2025

Choose a reason for hiding this comment

Uh oh!

Crunchyman-ralph commented Jun 20, 2025

Uh oh!

Crunchyman-ralph commented Jun 20, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

ben-vargas commented Jun 17, 2025 •

edited

Loading

1. feat: add Claude Code provider support (`426aaf2`)

2. fix(docs): correct invalid commands in claude-code usage examples (`3416cfa`)

3. feat: make @anthropic-ai/claude-code an optional dependency (`0e84bd1`)

4. test: add comprehensive tests for ClaudeCodeProvider (`e6e39e2`)

5. revert: remove maxTokens update functionality from init (`cca76c1`)

6. docs: add Claude Code support information to README (`e04a861`)

7. style: apply biome formatting to test files (`ee6f458`)

8. fix(models): add missing --claude-code flag to models command (`b1aa058`)

changeset-bot bot commented Jun 17, 2025 •

edited

Loading