feat: Add Claude Code Provider Support with SDK Integration

[Crunchyman-ralph]

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

1. Language Model (language-model.js): Handles text generation and streaming with lazy loading of the SDK
2. Message Converter (message-converter.js): Converts between Task Master and Claude Code message formats
3. Error Handling (errors.js): Provides clear error messages for missing dependencies
4. 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.

[changeset-bot]

🦋 Changeset detected

Latest commit: 8df2d50

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

[fahimanwer]

When can we expect the release waiting for this one eagerly.

[ben-vargas]

@Crunchyman-ralph if you didn't want as much code bloat, and some improved efficiencies, in exchange for a dependency - this version exists too: https://github.com/ben-vargas/ai-claude-task-master/tree/feature/claude-code-sdk-simple

Let me know if you'd prefer a PR from that branch.

[ben-vargas]

If you were interested in going that route, I'd just pin it to the current version you accept/release with as it is alpha. But I am thinking I'll submit a PR to verve to have that listed as a community built provider in vercels ai-sdk.

[Crunchyman-ralph]

@ben-vargas such a great idea, it would be such a great package if you were to submit it to vercel!

[Crunchyman-ralph]

@ben-vargas just saw you made a package, as soon as it passes vercel's net, lets definitely add it!

[ben-vargas]

@Crunchyman-ralph sounds good!

[bennyb0y]

This is rad. thanks for adding this.

[abel30567]

Great feature