claude-task-master/docs/examples/claude-code-usage.md

Claude Code Provider Usage Example

The Claude Code provider allows you to use Claude models through the Claude Code CLI without requiring an API key.

Configuration

To use the Claude Code provider, update your .taskmaster/config.json:

{
  "models": {
    "main": {
      "provider": "claude-code",
      "modelId": "sonnet",
      "maxTokens": 64000,
      "temperature": 0.2
    },
    "research": {
      "provider": "claude-code",
      "modelId": "opus",
      "maxTokens": 32000,
      "temperature": 0.1
    },
    "fallback": {
      "provider": "claude-code",
      "modelId": "sonnet",
      "maxTokens": 64000,
      "temperature": 0.2
    }
  }
}

Available Models

• opus - Claude Opus model (SWE score: 0.725)
• sonnet - Claude Sonnet model (SWE score: 0.727)

Usage

Once configured, you can use Claude Code with all Task Master commands:

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

# Analyze project complexity
task-master analyze-complexity

# Show the next task to work on
task-master next

# View a specific task
task-master show task-001

# Update task status
task-master set-status --id=task-001 --status=in-progress

Requirements

1. Claude Code CLI must be installed and authenticated on your system
2. Install the optional @anthropic-ai/claude-code package if you enable this provider:

   npm install @anthropic-ai/claude-code
   

3. Run Claude Code for the first time and authenticate with your Anthropic account:

   claude
   

4. No API key is required in your environment variables or MCP configuration

Advanced Settings

The Claude Code SDK supports additional settings that provide fine-grained control over Claude's behavior. These settings are implemented in the underlying SDK (src/ai-providers/custom-sdk/claude-code/), and can be managed through Task Master's configuration file.

Advanced Settings Usage

To update settings for Claude Code, update your .taskmaster/config.json:

The Claude Code settings can be specified globally in the claudeCode section of the config, or on a per-command basis in the commandSpecific section:

{
  // "models" and "global" config...

  "claudeCode": {
    // Maximum conversation turns Claude can make in a single request
    "maxTurns": 5,
    
    // Custom system prompt to override Claude Code's default behavior
    "customSystemPrompt": "You are a helpful assistant focused on code quality",

    // Append additional content to the system prompt
    "appendSystemPrompt": "Always follow coding best practices",
    
    // Permission mode for file system operations
    "permissionMode": "default", // Options: "default", "acceptEdits", "plan", "bypassPermissions"
    
    // Explicitly allow only certain tools
    "allowedTools": ["Read", "LS"], // Claude can only read files and list directories
    
    // Explicitly disallow certain tools
    "disallowedTools": ["Write", "Edit"], // Prevent Claude from modifying files
    
    // MCP servers for additional tool integrations
    "mcpServers": {
      "mcp-server-name": {
        "command": "npx",
        "args": ["-y", "mcp-serve"],
        "env": {
          // ...
        }
      }
    }
  },

  // Command-specific settings override global settings
  "commandSpecific": {
    "parse-prd": {
      // Settings specific to the 'parse-prd' command
      "maxTurns": 10,
      "customSystemPrompt": "You are a task breakdown specialist"
    },
    "analyze-complexity": {
      // Settings specific to the 'analyze-complexity' command
      "maxTurns": 3,
      "appendSystemPrompt": "Focus on identifying bottlenecks"
    }
  }
}

• For a full list of Cluaude Code settings, see the Claude Code Settings documentation.
• For a full list of AI powered command names, see this file: src/constants/commands.js

Why These Settings Matter

• maxTurns: Useful for complex refactoring tasks that require multiple iterations
• customSystemPrompt: Allows specializing Claude for specific domains or coding standards
• appendSystemPrompt: Useful for enforcing coding standards or providing additional context
• permissionMode: Critical for security in production environments
• allowedTools/disallowedTools: Enable read-only analysis modes or restrict access to sensitive operations
• mcpServers: Future extensibility for custom tool integrations

Notes

• The Claude Code provider doesn't track usage costs (shown as 0 in telemetry)
• Session management is handled automatically for conversation continuity
• Some AI SDK parameters (temperature, maxTokens) are not supported by Claude Code CLI and will be ignored