Product Requirements Document: Claude Code CLI Integration for Task Master

1. Executive Summary

This PRD outlines the implementation of Claude Code CLI as an AI provider option for Task Master, enabling users to leverage Claude's capabilities without requiring API keys. Instead, users can authenticate through their existing Claude Code installation and use their Claude Pro/Team subscriptions.

2. Problem Statement

Current Challenges

Users must obtain and manage API keys for AI providers
API costs can be unpredictable and expensive for heavy usage
Security concerns around storing API keys in configuration files
Users with Claude Pro subscriptions cannot leverage their existing access

Opportunity

Claude Code now provides CLI access with authentication handled through the browser, offering a secure, cost-effective alternative for users who already have Claude subscriptions.

3. Goals and Objectives

Primary Goals

Enable Task Master to use Claude Code CLI as an AI provider
Eliminate the need for API keys when using Claude
Maintain full compatibility with existing Task Master features
Provide seamless switching between API and CLI modes

Success Criteria

Users can configure Claude Code CLI as their AI provider
All task management operations work identically with CLI provider
Performance remains acceptable (< 2x latency vs API)
Clear documentation and error messages guide users

4. User Stories

As a Task Master user with Claude Pro

I want to use my Claude subscription instead of API keys
So that I can avoid additional costs and API key management

As a developer concerned about security

I want to avoid storing API keys in my project
So that I reduce the risk of credential exposure

As a team using Task Master

I want team members to use their own Claude accounts
So that usage is tracked individually and securely

5. Functional Requirements

5.1 Provider Implementation

Create ClaudeCodeCLIProvider class extending BaseAIProvider
Implement all required methods: generateText(), streamText(), generateObject()
Handle CLI process spawning with proper error handling
Parse CLI JSON output to match provider interface

5.2 Authentication

Check Claude Code CLI installation on provider initialization
Verify authentication status using claude auth status
Provide clear error messages for authentication issues
Support re-authentication flow guidance

5.3 Configuration

Add claude-code-cli as a provider option in configuration
Support model selection (opus, sonnet) via --model flag
Allow CLI-specific parameters:
- --max-turns: Limit agentic turns (default: 3 for thorough processing)
- --output-format: json/text output format
- Process timeout for Node.js execution
Enable role-based provider selection (main, research, fallback)
Note: Claude Code CLI does not support temperature, maxTokens, or other inference parameters

5.4 Command Execution

Use Node.js child process APIs for CLI interaction
Handle stdin/stdout communication for prompts and responses
Implement proper timeout and buffer size limits
Support both interactive and non-interactive modes

5.5 Error Handling

Detect and report CLI installation issues
Handle authentication failures gracefully
Parse CLI error outputs into user-friendly messages
Implement retry logic for transient failures

6. Technical Architecture

6.1 Component Structure

src/ai-providers/
├── claude-code-cli.js      # New CLI provider implementation
├── base-provider.js        # Existing base class (no changes)
└── index.js               # Export new provider

scripts/modules/
├── ai-services-unified.js  # Register new provider
└── config-manager.js       # Update provider configurations

6.2 Integration Points

Provider Registry: Add to PROVIDERS object
Model Mapping: Define available models for CLI
Authentication: Override validateAuth() for CLI checks
API Key Logic: Bypass API key requirements for CLI provider

6.3 CLI Communication Flow

sequenceDiagram
    participant TM as Task Master
    participant CCP as ClaudeCodeCLI Provider
    participant CC as Claude CLI
    participant API as Claude API

    TM->>CCP: generateText(messages)
    CCP->>CC: Check authentication
    CC-->>CCP: Auth status
    CCP->>CC: Execute with prompt
    CC->>API: API request (handled by CLI)
    API-->>CC: Response
    CC-->>CCP: JSON output
    CCP-->>TM: Formatted response

7. Non-Functional Requirements

7.1 Performance

CLI invocation overhead < 500ms
Total response time < 2x API direct calls
Support concurrent requests without blocking

7.2 Reliability

Graceful degradation to fallback providers
Clear error messages for troubleshooting
Automatic retry for transient failures

7.3 Security

No API keys stored or transmitted
Leverage Claude Code's secure authentication
Process isolation for CLI execution

7.4 Usability

Zero-config option for Claude Code users
Clear setup instructions in documentation
Helpful error messages with resolution steps

8. Implementation Plan

Phase 1: Core Provider (Week 1)

Create ClaudeCodeCLIProvider class
Implement generateText() method
Add basic error handling
Write unit tests

Phase 2: Integration (Week 2)

Register provider in ai-services-unified.js
Update configuration system
Implement authentication validation
Add integration tests

Phase 3: Advanced Features (Week 3)

Implement streamText() if possible
Add generateObject() with schema support
Optimize performance
Handle edge cases

Phase 4: Documentation & Testing (Week 4)

Write user documentation
Create setup guide
Add example configurations
Conduct end-to-end testing

9. Testing Strategy

Unit Tests

Mock CLI execution for isolated testing
Test error handling scenarios
Validate output parsing

Integration Tests

Test with actual Claude Code CLI (when available)
Verify all Task Master features work
Test provider switching

Performance Tests

Measure latency vs API providers
Test concurrent request handling
Monitor resource usage

10. Documentation Requirements

User Guide

Installation prerequisites
Authentication setup steps
Configuration examples
Troubleshooting guide

Developer Documentation

Provider implementation details
CLI communication protocol
Extension points for customization

11. Success Metrics

Adoption rate among Claude Pro users
Reduction in API key-related support issues
Performance metrics vs API providers
User satisfaction scores

12. Future Enhancements

Streaming support for real-time responses
Context caching for conversation continuity
Support for Claude Code's special features
Integration with Claude Code's memory system

13. Risks and Mitigation

Risk: CLI API changes

Mitigation: Version detection and compatibility layer

Risk: Performance degradation

Mitigation: Configurable fallback to API providers

Risk: Platform compatibility

Mitigation: Extensive testing on Windows, Mac, Linux

14. Approval and Sign-off

This PRD requires approval from:

Project Maintainer
Technical Lead
Documentation Team

Appendix A: Example Configuration

{
  "models": {
    "main": {
      "model": "opus",
      "provider": "claude-code-cli"
    },
    "fallback": {
      "model": "gpt-4-turbo",
      "provider": "openai",
      "temperature": 0.7,
      "maxTokens": 4096
    }
  },
  "claudeCodeCLI": {
    "maxTurns": 3,
    "outputFormat": "json",
    "processTimeout": 120000
  }
}

Appendix B: Example Usage

# User configures Claude Code CLI
task-master config --provider claude-code-cli

# Authentication check
task-master auth status

# Normal usage - no API keys needed!
task-master parse-prd "Build a todo app"

ben-vargas/claude-task-master - feature: claude-code-cli-prd.md