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

[neno-is-ooo]

Summary

This PR introduces a new AI provider (claude-code) that integrates with the official Claude Code SDK, enabling Task Master users to leverage their Claude Code subscription without needing API keys.

Motivation

Many developers already have Claude Code (formerly Claude.ai) subscriptions but need separate API keys to use Task Master. This integration bridges that gap by using the locally authenticated Claude Code SDK, making Task Master accessible to more users without additional costs.

Changes

• ✅ Added new claude-code provider in src/ai-providers/claude-code.js
• ✅ Modified API key validation to skip check for claude-code provider (similar to ollama)
• ✅ Added claude-code to supported models configuration
• ✅ Added export for ClaudeCodeProvider in the providers index
• ✅ Comprehensive unit tests with proper mocking to handle circular dependencies

Implementation Details

The provider uses the official @anthropic-ai/claude-code SDK and:

• Leverages existing Claude Code authentication (via claude auth login)
• Supports all Task Master AI operations (text generation, object generation, streaming)
• Properly handles the SDK's async iterator pattern and message formats
• Includes error handling for common SDK issues
• Uses AbortController for better control flow

Testing

• ✅ All unit tests pass with proper mocking to avoid circular dependencies
• ✅ Tested core functionality:
  • task-master parse-prd - Successfully generates tasks from PRD
  • task-master expand - Expands tasks into subtasks
  • task-master add-task - Adds new tasks with AI assistance
• ✅ Configuration works via both environment variable and config file
• ✅ Error handling tested for authentication and SDK availability

Usage

# Prerequisites: Install and authenticate Claude Code
npm install @anthropic-ai/claude-code
claude auth login

# Option 1: Set via environment variable
export TASK_MASTER_MAIN_PROVIDER=claude-code

# Option 2: Configure in .taskmaster/config.json
{
  "models": {
    "main": {
      "provider": "claude-code",
      "modelId": "claude-code",
      "maxTokens": 64000,
      "temperature": 0.2
    }
  }
}

# Use Task Master normally
task-master parse-prd requirements.txt

Benefits

• 🆓 Free for Claude Code subscribers - No additional API costs
• 🔐 No API keys needed - Uses existing Claude Code authentication
• 🚀 Full feature parity - Works with all Task Master commands
• 🧠 Context-aware - Leverages Claude's full capabilities
• ✅ Well-tested - Comprehensive unit test coverage

Breaking Changes

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

Dependencies

• Requires @anthropic-ai/claude-code SDK (peer dependency)
• Users must have Claude Code installed and authenticated

Implementation Strategy vs Previous Attempts

Previous PR #649 took a CLI-based approach that:

• Spawned the claude CLI process directly
• Managed stdin/stdout streams manually
• Required temporary file handling (which caused ENOENT errors)
• Needed platform-specific workarounds for macOS aliases
• Implemented custom readline interfaces for streaming

This implementation instead:

• Uses the official @anthropic-ai/claude-code SDK's JavaScript API
• Leverages the SDK's async iterator pattern for clean message handling
• Relies on the SDK's built-in process management and authentication
• Provides structured message types (SDKMessage) for better type safety
• Eliminates all manual stream and file handling complexity

Technical Notes

• The SDK returns structured SDKMessage types with system, assistant, and result message types
• Tests use proper mocking to avoid circular dependency issues present in the codebase
• The provider follows the same pattern as other providers while adapting to the SDK's unique async iterator interface

Fixes #[issue-number] (if applicable)

[changeset-bot]

🦋 Changeset detected

Latest commit: 9770c72

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	Patch

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

[Crunchyman-ralph]

lgtm, just want a better provider, but I think this is really close!

[ben-vargas]

No ability to specify opus vs sonnet models?

[apple-techie]

Yeah I would prefer to see it work this way too, ideally....

[ben-vargas]

Yeah, would love to see it do something like this... https://gist.github.com/ben-vargas/50c628bd8e61b4c9d971bcc226a2ae93

[neno-is-ooo]

No ability to specify opus vs sonnet models?

added it! about to push..

[Crunchyman-ralph]

nitpicks

[apple-techie]

Is this fully compatible with 0.17?

[neno-is-ooo]

Is this fully compatible with 0.17?

it regressed so now I'm fixing it again :)

[germanoeich]

There's an issue with researching using claude-code. Here is what I saw:

When running:
npx task-master research "Document ways to use the official claude-code package instead of manually spawning sub processing. Focus only on typescript. https://docs.anthropic.com/en/docs/claude-code/sdk"

With the research model set as claude-code/claude-sonnet-4-20250514, The research is mostly empty:

---
title: Research Session
query: "Document ways to use the official claude-code package instead of manually spawning sub processing. Focus only on typescript. https://docs.anthropic.com/en/docs/claude-code/sdk"
date: 6/16/2025
time: 1:44:34 PM
timestamp: 2025-06-16T16:44:34.772Z
exchanges: 1
---

# Research Session

## Initial Query

**Question:** Document ways to use the official claude-code package instead of manually spawning sub processing. Focus only on typescript. https://docs.anthropic.com/en/docs/claude-code/sdk

**Response:**

I'll research how to use the official claude-code SDK package instead of manually spawning subprocesses in TypeScript.


---

*Generated by Task Master Research Command*  
*Timestamp: 2025-06-16T16:44:34.772Z*

If I switch to anthropic/claude-sonnet-4-20250514 the research process works fine and I get a full report.

I tried adding the WebFetch tool to my settings.local.json permissions.allow array, and it behaves the same. I tried: "WebFetch(domain:docs.anthropic.com)", "WebFetch(domain:*)", "WebFetch" and "WebFetch(*)"

Simplifying the command to npx task-master research "Document ways to use the official claude-code package instead of manually spawning sub processing. Focus only on typescript." wields the same results.

Otherwise, this is working great so far! Thank you for taking the time to implement this!

[ben-vargas]

If you're feeling adventurous @germanoeich - I'd be curious if this approach passes your testing and provides better result for research command.

It takes a little different approach of implementing a Vercel AI SDK custom community provider and then uses the BaseAIProvider class like the other providers defined in Task Master. In my test, it seems to respond fine to research commands when I tested.

https://github.com/ben-vargas/ai-claude-task-master/tree/feature/claude-code-sdk

[germanoeich]

@ben-vargas I tested your branch and found no issues with research or any other features, I parsed a prd, expanded tasks, performed research, task updates, etc all using claude-code and everything is working perfectly!

[ben-vargas]

Thanks @germanoeich - I've submitted it as #805 after making a few scope changes as it was overstepping its scope modifying the config.json setup (there's an issue where maxTokens doesn't update correctly, but I pulled that fix out of the PR as it probably warrants a dedicated PR). The maxTokens and temperature parameters are not support by claude code anyway, so it doesn't really need to be in the PR implementing claude code.

[neno-is-ooo]

closing this in favour of #805