TODO: Move to apps/docs inside our documentation website

Claude Code Integration Guide

This guide covers how to use Task Master with Claude Code AI SDK integration for enhanced AI-powered development workflows.

Overview

Claude Code integration allows Task Master to leverage the Claude Code CLI for AI operations without requiring direct API keys. The integration uses OAuth tokens managed by the Claude Code CLI itself.

Authentication Setup

The Claude Code provider uses token authentication managed by the Claude Code CLI.

Prerequisites

1. Install Claude Code CLI (if not already installed):

   bashCopy

   # Installation method depends on your system
   # Follow Claude Code documentation for installation
   

2. Set up OAuth token using Claude Code CLI:

   bashCopy

   claude setup-token
   

   This command will:

   • Guide you through OAuth authentication
   • Store the token securely for CLI usage
   • Enable Task Master to use Claude Code without manual API key configuration

Authentication Priority

Task Master will attempt authentication in this order:

1. Environment Variable (optional): CLAUDE_CODE_OAUTH_TOKEN

   • Useful for CI/CD environments or when you want to override the default token
   • Not required if you've set up the CLI token

2. Claude Code CLI Token (recommended): Token managed by claude setup-token

   • Automatically used when available
   • Most convenient for local development

3. Fallback: Error if neither is available

Configuration

Basic Configuration

Add Claude Code to your Task Master configuration:

// In your .taskmaster/config.json or via task-master models command
{
  "models": {
    "main": "claude-code:sonnet",      // Use Claude Code with Sonnet
    "research": "perplexity-llama-3.1-sonar-large-128k-online",
    "fallback": "claude-code:opus"     // Use Claude Code with Opus as fallback
  }
}

Supported Models

• claude-code:sonnet - Claude 3.5 Sonnet via Claude Code CLI
• claude-code:opus - Claude 3 Opus via Claude Code CLI

Environment Variables (Optional)

While not required, you can optionally set:

export CLAUDE_CODE_OAUTH_TOKEN="your_oauth_token_here"

This is only needed in specific scenarios like:

• CI/CD pipelines
• Docker containers
• When you want to use a different token than the CLI default

Usage Examples

Basic Task Operations

# Use Claude Code for task operations
task-master add-task --prompt="Implement user authentication system" --research
task-master expand --id=1 --research
task-master update-task --id=1.1 --prompt="Add JWT token validation"

Model Configuration Commands

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

# Use interactive setup
task-master models --setup
# Then select "claude-code" from the provider list

Troubleshooting

Common Issues

1. "Claude Code CLI not available" Error

Problem: Task Master cannot connect to Claude Code CLI.

Solutions:

• Ensure Claude Code CLI is installed and in your PATH
• Run claude setup-token to configure authentication
• Verify Claude Code CLI works: claude --help

2. Authentication Failures

Problem: Token authentication is failing.

Solutions:

• Re-run claude setup-token to refresh your OAuth token
• Check if your token has expired
• Verify Claude Code CLI can authenticate: try a simple claude command

3. Model Not Available

Problem: Specified Claude Code model is not supported.

Solutions:

• Use supported models: sonnet or opus
• Check model availability: task-master models --list
• Verify your Claude Code CLI has access to the requested model

Debug Steps

1. Test Claude Code CLI directly:

   bashCopy

   claude --help
   # Should show help without errors
   

2. Test authentication:

   bashCopy

   claude setup-token --verify
   # Should confirm token is valid
   

3. Test Task Master integration:

   bashCopy

   task-master models --test claude-code:sonnet
   # Should successfully connect and test the model
   

4. Check logs:

   • Task Master logs will show detailed error messages
   • Use --verbose flag for more detailed output

Environment-Specific Configuration

Docker/Containers

When running in Docker, you'll need to:

1. Install Claude Code CLI in your container

2. Set up authentication via environment variable:

   dockerfileCopy

   ENV CLAUDE_CODE_OAUTH_TOKEN="your_token_here"
   

CI/CD Pipelines

For automated environments:

1. Set up a service account token or use environment variables
2. Ensure Claude Code CLI is available in the pipeline environment
3. Configure authentication before running Task Master commands

Integration with AI SDK

Task Master's Claude Code integration uses the official ai-sdk-provider-claude-code package, providing:

• Streaming Support: Real-time token streaming for interactive experiences
• Full AI SDK Compatibility: Works with generateText, streamText, and other AI SDK functions
• Automatic Error Handling: Graceful degradation when Claude Code is unavailable
• Type Safety: Full TypeScript support with proper type definitions
• Native Structured Outputs (v2.2.0+): Guaranteed schema-compliant JSON responses

Native Structured Outputs (v2.2.0+)

As of ai-sdk-provider-claude-code v2.2.0, Claude Code supports native structured outputs via the Claude Agent SDK's outputFormat option. This provides significant benefits for Task Master's structured data generation:

Key Benefits

• Guaranteed Schema Compliance: The SDK uses constrained decoding to ensure responses always match your Zod schema
• No JSON Parsing Errors: Schema validation is handled internally by the SDK
• No Prompt Engineering Required: No need for "output valid JSON" instructions - the SDK enforces schema natively
• Better Performance: No retry/extraction logic needed for valid JSON output

How It Works

When Task Master calls generateObject() or streamObject() with a Zod schema, the Claude Code provider:

1. Sets mode: 'json' (via needsExplicitJsonSchema = true)
2. Passes the schema to the SDK
3. The SDK converts the Zod schema to JSON Schema and uses outputFormat: { type: 'json_schema', schema: ... }
4. Claude Agent SDK returns structured_output with guaranteed schema compliance

Example

import { z } from 'zod';
import { generateObjectService } from './scripts/modules/ai-services-unified.js';

// Define your schema
const taskSchema = z.object({
  title: z.string().min(1),
  description: z.string().min(1),
  priority: z.enum(['high', 'medium', 'low']),
  dependencies: z.array(z.number().int())
});

// Generate structured output - guaranteed to match schema
const result = await generateObjectService({
  role: 'main',  // Uses Claude Code if configured as main provider
  schema: taskSchema,
  objectName: 'task',
  prompt: 'Create a task for implementing user authentication',
  systemPrompt: 'You are a task planning assistant.',
  commandName: 'add-task',
  outputType: 'cli'
});

// result.mainResult is guaranteed to match taskSchema
console.log(result.mainResult);
// { title: "...", description: "...", priority: "high", dependencies: [] }

Supported Commands

All Task Master commands that generate structured data benefit from native schema support:

• parse-prd - Parsing PRD documents into tasks
• add-task - Creating new tasks
• expand-task - Expanding tasks into subtasks
• update-tasks - Batch updating tasks
• update-task-by-id - Updating individual tasks
• analyze-complexity - Analyzing task complexity

Example AI SDK Usage

import { generateText } from 'ai';
import { ClaudeCodeProvider } from './src/ai-providers/claude-code.js';

const provider = new ClaudeCodeProvider();
const client = provider.getClient();

const result = await generateText({
  model: client('sonnet'),
  messages: [
    { role: 'user', content: 'Hello Claude!' }
  ]
});

console.log(result.text);

Security Notes

• OAuth tokens are managed securely by Claude Code CLI
• No API keys need to be stored in your project files
• Tokens are automatically refreshed by the Claude Code CLI
• Environment variables should only be used in secure environments

Getting Help

If you encounter issues:

1. Check the Claude Code CLI documentation
2. Verify your authentication setup with claude setup-token --verify
3. Review Task Master logs for detailed error messages
4. Open an issue with both Task Master and Claude Code version information