A revolutionary AI-powered Python CLI tool that automates the entire software development lifecycle using the Claude Code SDK. From specification to deployment, Claude Code Builder transforms product requirements into production-ready software with minimal human intervention.

Claude Code Builder is an intelligent software generation system that:

• Analyzes natural language specifications to understand project requirements
• Architects optimal technical solutions using multi-agent collaboration
• Builds complete applications with proper structure, testing, and documentation
• Manages context intelligently to handle large specifications (150K+ tokens)
• Orchestrates specialized MCP servers for various development tasks
• Resumes builds from checkpoints, ensuring reliability and cost efficiency

• Key Features
• System Architecture
• Installation
• Quick Start
• Usage
• Writing Specifications
• Configuration
• API Reference
• Developer Guide
• Advanced Features
• Cost Management
• Troubleshooting
• Contributing

• SpecAnalyzer: Extracts requirements, identifies ambiguities, determines scope
• TaskGenerator: Creates comprehensive, ordered task lists with dependencies
• InstructionBuilder: Generates precise, Claude-compatible instructions
• CodeGenerator: Produces high-quality code following best practices
• TestGenerator: Creates comprehensive test suites
• ReviewAgent: Validates code quality and completeness

• Filesystem Server: Secure file operations within project boundaries
• GitHub Server: Repository management and version control
• Memory Server: Persistent context across sessions
• Fetch Server: Web resource access for research
• Perplexity Server: Real-time information for technical decisions

• Handles specifications up to 150K tokens
• Intelligent chunking for optimal token usage
• Context compression without information loss
• Adaptive loading based on current phase needs

• Automatic checkpointing after each phase
• Cost tracking and budget enforcement
• Seamless resume from any interruption
• Preserves all context and progress

• Extensible architecture for custom functionality
• Hook into any phase of the build process
• Create custom agents and MCP integrations
• Share and reuse plugins across projects

The following Mermaid diagram illustrates how the CLI, orchestrator, agents, MCP servers and external services interact:

graph TD
  subgraph CLI
    build([build])
    analyze([analyze])
    resume([resume])
    validate([validate])
  end

  subgraph "Build Orchestrator"
    PhaseMgr[Phase Manager]
    CtxMgr[Context Manager]
    Checkpoint[Checkpoint System]
  end

  subgraph "Agent System"
    SpecAgent --> TaskAgent --> CodeAgent --> TestAgent
  end

  subgraph "MCP Orchestrator"
    Filesystem
    GitHub
    Memory
    Perplexity
  end

  subgraph "External Services"
    Anthropic
    ExternalAPIs["External APIs"]
  end

  build --> PhaseMgr
  analyze --> SpecAgent
  resume --> Checkpoint
  validate --> SpecAgent
  PhaseMgr --> SpecAgent
  Checkpoint --> PhaseMgr
  PhaseMgr --> CtxMgr
  CtxMgr --> Checkpoint
  SpecAgent --> TaskAgent
  TaskAgent --> CodeAgent
  CodeAgent --> TestAgent
  Filesystem -.-> Anthropic
  GitHub -.-> Anthropic
  Memory -.-> Anthropic
  Perplexity -.-> ExternalAPIs

• Python 3.11 or higher
• Poetry (for dependency management)
• Node.js 18+ (for MCP servers)
• Git

1. Clone the repository

   git clone https://github.com/yourusername/claude-code-builder.git
   cd claude-code-builder

2. Install Python dependencies

   # Install Poetry if not already installed
   curl -sSL https://install.python-poetry.org | python3 -
   
   # Install project dependencies
   poetry install

3. Install MCP servers

   # Required MCP servers
   npm install -g @modelcontextprotocol/server-filesystem
   npm install -g @modelcontextprotocol/server-memory
   
   # Optional MCP servers
   npm install -g @modelcontextprotocol/server-github
   npm install -g @modelcontextprotocol/server-fetch
   npm install -g @modelcontextprotocol/server-perplexity

4. Set up environment variables

   # Create .env file
   cp .env.example .env
   
   # Add your API keys
   echo "ANTHROPIC_API_KEY=your-api-key" >> .env
   echo "GITHUB_TOKEN=your-github-token" >> .env  # Optional
   echo "PERPLEXITY_API_KEY=your-perplexity-key" >> .env  # Optional

5. Verify installation

   poetry run claude-code-builder --version
   poetry run claude-code-builder doctor  # Check system configuration

1. Create a specification file (my-app-spec.md):

   # Todo List API
   
   ## Overview
   A simple REST API for managing todo items.
   
   ## Requirements
   - CRUD operations for todo items
   - SQLite database
   - Input validation
   - Unit tests
   
   ## Technology Stack
   - Python 3.11
   - FastAPI
   - SQLAlchemy
   - pytest

2. Run the build:

   poetry run claude-code-builder build my-app-spec.md --output ./todo-api

3. Monitor progress: The CLI will show real-time progress with Rich formatting, including:

   • Current phase and task
   • Token usage and costs
   • Estimated time remaining

4. Review the output:

   cd todo-api
   ls -la
   # Your complete application with tests and documentation!

# Build from specification
claude-code-builder build <spec-file> [options]

# Analyze specification without building
claude-code-builder analyze <spec-file> [options]

# Resume a failed or interrupted build
claude-code-builder resume <project-dir> [options]

# Validate a specification
claude-code-builder validate <spec-file> [options]

# Initialize a new project
claude-code-builder init <project-name> [options]

# Show configuration
claude-code-builder config show

# Check system status
claude-code-builder doctor

claude-code-builder build spec.md \
  --output ./my-project \           # Output directory (default: auto-generated)
  --model claude-3-opus-20240229 \  # Model to use
  --max-cost 50.00 \                # Maximum build cost in USD
  --max-tokens 5000000 \            # Maximum tokens to use
  --phases "design,core,test" \     # Specific phases to run
  --continue-on-error \             # Continue even if a phase fails
  --dry-run \                       # Simulate without making changes
  --no-checkpoint \                 # Disable checkpointing
  --parallel \                      # Enable parallel agent execution
  --template advanced \             # Use advanced project template
  -vv                              # Verbose output

# Analyze with cost estimation
claude-code-builder analyze spec.md --estimate-cost --detailed

# Validate and auto-fix issues
claude-code-builder validate spec.md --fix --output fixed-spec.md

# Resume from specific phase
claude-code-builder resume ./project --from-phase testing --reset-costs

# Generate specification template
claude-code-builder init my-project --template fullstack --output spec.md

# Export build metrics
claude-code-builder status ./project --export metrics.json

# List available plugins
claude-code-builder plugins list

# Run with specific plugin
claude-code-builder build spec.md --plugins "github-integration,docker-setup"

# Project Name

## Overview
Brief description of what the application does and its primary purpose.

## Objectives
1. Primary objective
2. Secondary objectives

## Requirements

### Functional Requirements
- User authentication
- Core feature 1
- Core feature 2

### Non-Functional Requirements
- Performance: < 200ms response time
- Security: OAuth2 authentication
- Scalability: 10K concurrent users

## Technology Stack
- Language: Python 3.11+
- Framework: FastAPI
- Database: PostgreSQL
- Testing: pytest

## Success Criteria
1. All tests passing
2. 90% code coverage
3. API documentation complete

# Enterprise Application Name

## Executive Summary
Comprehensive overview including business value and strategic alignment.

## Detailed Requirements

### User Stories
As a [user type], I want to [action] so that [benefit].

### API Specifications
```yaml
endpoints:
  - path: /api/v1/users
    method: POST
    request:
      type: object
      properties:
        email: string
        password: string
    response:
      type: object
      properties:
        id: string
        token: string

class User:
    id: UUID
    email: str
    created_at: datetime
    profile: UserProfile

• External API: PaymentProvider
• Authentication: Auth0
• Monitoring: DataDog

• API Response: p95 < 100ms
• Database queries: < 50ms
• Concurrent users: 50K

• OWASP Top 10 compliance
• PCI DSS for payment handling
• GDPR compliance for EU users

• Container: Docker
• Orchestration: Kubernetes
• CI/CD: GitHub Actions

• Budget: $50K
• Timeline: 3 months
• Team: 2 developers

1. All functional requirements implemented
2. Performance benchmarks met
3. Security audit passed
4. Documentation complete

### Best Practices for Specifications

1. **Be Specific**: Avoid vague requirements like "user-friendly UI"
2. **Include Examples**: Provide sample data, API calls, or UI mockups
3. **Define Success**: Clear, measurable acceptance criteria
4. **Specify Constraints**: Budget, timeline, technology limitations
5. **Prioritize Features**: Mark must-have vs nice-to-have features

## Configuration

### Project Configuration (`.claude-code-builder.json`)

```json
{
  "version": "0.1.0",
  "project_name": "My Project",
  "model": "claude-3-opus-20240229",
  "mcp_servers": {
    "filesystem": {
      "enabled": true,
      "allowed_directories": ["./src", "./tests"]
    },
    "github": {
      "enabled": true,
      "auto_commit": false,
      "branch": "feature/ai-generated"
    },
    "memory": {
      "enabled": true,
      "max_entities": 1000
    }
  },
  "build_config": {
    "max_cost": 100.0,
    "max_tokens": 10000000,
    "checkpoint_frequency": "phase",
    "parallel_agents": true,
    "continue_on_error": false
  },
  "phases": {
    "skip": ["deployment"],
    "custom_order": ["design", "core", "api", "test", "docs"]
  },
  "plugins": ["github-integration", "docker-setup"]
}

api_key: ${ANTHROPIC_API_KEY}
default_model: claude-3-opus-20240229
mcp_servers:
  filesystem:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-filesystem"]
  github:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_TOKEN: ${GITHUB_TOKEN}
  memory:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-memory"]
defaults:
  max_cost: 100.0
  max_tokens: 10000000
  verbose: 1
  checkpoint_enabled: true
  parallel_agents: false
logging:
  level: INFO
  file: ~/.claude-code-builder/claude-code-builder.log
  max_size: 10MB
  backup_count: 5

Base class for all agents in the system.

from claude_code_builder.agents import BaseAgent

class CustomAgent(BaseAgent):
    async def execute(self, context: ExecutionContext) -> AgentResponse:
        # Implementation
        pass

Manages the entire build process.

from claude_code_builder.core import BuildOrchestrator

orchestrator = BuildOrchestrator(config)
await orchestrator.build(specification)

Provides context and utilities to agents.

class ExecutionContext:
    project: Project
    mcp_clients: Dict[str, MCPClient]
    logger: Logger
    metrics: BuildMetrics
    checkpoint: CheckpointManager

All commands support --help for detailed information:

claude-code-builder build --help
claude-code-builder analyze --help
claude-code-builder resume --help

Create custom plugins to extend functionality:

from claude_code_builder.plugins import BasePlugin

class MyPlugin(BasePlugin):
    def on_phase_start(self, phase: str, context: ExecutionContext):
        print(f"Starting phase: {phase}")
    
    def on_phase_complete(self, phase: str, context: ExecutionContext):
        print(f"Completed phase: {phase}")

1. Define your agent:

   from claude_code_builder.agents import BaseAgent
   from claude_code_builder.core import AgentResponse, ExecutionContext
   
   class DatabaseMigrationAgent(BaseAgent):
       """Agent for handling database migrations."""
       
       async def execute(self, context: ExecutionContext) -> AgentResponse:
           # Access MCP clients
           filesystem = context.mcp_clients['filesystem']
           
           # Generate migration files
           migrations = await self.generate_migrations(context)
           
           # Write files
           for migration in migrations:
               await filesystem.write_file(
                   f"migrations/{migration.name}.py",
                   migration.content
               )
           
           return AgentResponse(
               success=True,
               summary="Generated database migrations",
               artifacts={"migrations": len(migrations)}
           )

2. Register your agent:

   from claude_code_builder.agents import register_agent
   
   register_agent("database_migration", DatabaseMigrationAgent)

3. Use in build configuration:

   {
     "phases": {
       "custom": {
         "database": {
           "agent": "database_migration",
           "config": {
             "migration_style": "alembic"
           }
         }
       }
     }
   }

Create custom MCP clients:

from claude_code_builder.mcp import BaseMCPClient

class CustomMCPClient(BaseMCPClient):
    async def connect(self):
        # Connect to your MCP server
        pass
    
    async def custom_operation(self, data):
        # Implement custom operations
        pass

import pytest
from claude_code_builder.testing import AgentTestCase

class TestDatabaseMigrationAgent(AgentTestCase):
    async def test_migration_generation(self):
        context = self.create_test_context()
        agent = DatabaseMigrationAgent()
        
        response = await agent.execute(context)
        
        assert response.success
        assert response.artifacts["migrations"] > 0

Get detailed analysis before building:

claude-code-builder analyze spec.md --detailed

# Output includes:
# - Complexity score
# - Estimated tokens
# - Estimated cost
# - Identified risks
# - Missing requirements
# - Suggested improvements

Validate and fix common issues:

# Validate only
claude-code-builder validate spec.md

# Validate and fix
claude-code-builder validate spec.md --fix

# Common fixes:
# - Missing required sections
# - Ambiguous requirements
# - Incomplete technology stack
# - Missing success criteria

Use and create project templates:

# List available templates
claude-code-builder templates list

# Use a template
claude-code-builder init my-project --template microservice

# Create custom template
claude-code-builder templates create my-template --from ./existing-project

Track and analyze build performance:

# View build metrics
claude-code-builder status ./project --metrics

# Export detailed analytics
claude-code-builder status ./project --export analytics.json

# Metrics include:
# - Token usage by phase
# - Cost breakdown
# - Time per phase
# - Error frequency
# - Agent performance

Enable parallel agent execution for faster builds:

claude-code-builder build spec.md --parallel --max-workers 4

Define custom phases in your specification:

phases:
  custom:
    data_pipeline:
      agent: "code_generator"
      dependencies: ["core"]
      config:
        templates: ["etl_pipeline.j2"]
    ml_training:
      agent: "ml_trainer"
      dependencies: ["data_pipeline"]

Claude Code Builder provides detailed cost tracking:

• Token Costs: Based on model pricing
• Phase Breakdown: Cost per build phase
• Cumulative Tracking: Total project cost
• Budget Enforcement: Stops when limit reached

1. Use Checkpoints: Resume interrupted builds without re-running completed phases
2. Phase Selection: Run only necessary phases
3. Model Selection: Use smaller models for simpler tasks
4. Context Optimization: Enable aggressive context compression
5. Specification Quality: Clear specs reduce iteration

# Set strict budget limit
claude-code-builder build spec.md --max-cost 25.00 --stop-on-limit

# Get cost estimate first
claude-code-builder analyze spec.md --estimate-cost

# Monitor costs in real-time
claude-code-builder build spec.md -vv  # Shows cost after each phase

# Resume with budget reset
claude-code-builder resume ./project --reset-costs --max-cost 50.00

Problem: Specification exceeds token limits Solutions:

# Enable context optimization
claude-code-builder build spec.md --optimize-context

# Split into multiple files
claude-code-builder build main-spec.md \
  --include requirements.md \
  --include api-spec.md

# Use references instead of inline content
# In your spec:
# See API documentation: @file:api-docs.yaml

Problem: Cannot connect to MCP servers Solutions:

# Check server installation
npm list -g | grep "@modelcontextprotocol"

# Test individual server
npx @modelcontextprotocol/server-filesystem --test

# Check permissions
claude-code-builder doctor --check-permissions

# View server logs
tail -f ~/.claude-code-builder/logs/mcp-*.log

Problem: Cannot resume from checkpoint Solutions:

# Verify checkpoint integrity
claude-code-builder checkpoints verify ./project

# List available checkpoints
claude-code-builder checkpoints list ./project

# Resume from specific checkpoint
claude-code-builder resume ./project --checkpoint phase-3

# Force rebuild from phase
claude-code-builder resume ./project --from-phase core --force

Problem: Build using more tokens than expected Solutions:

# Analyze token usage
claude-code-builder analyze spec.md --token-breakdown

# Enable aggressive optimization
claude-code-builder build spec.md \
  --optimize-context \
  --compression-level high

# Exclude unnecessary phases
claude-code-builder build spec.md \
  --skip-phases "optimization,deployment"

Problem: Generated code doesn't meet expectations Solutions:

# Enable review phase
claude-code-builder build spec.md --enable-review

# Use stricter quality settings
claude-code-builder build spec.md \
  --quality high \
  --test-coverage 90

# Provide examples in specification
# Include code examples, API samples, UI mockups

Enable detailed debugging information:

# Maximum verbosity
claude-code-builder build spec.md -vvv

# Debug specific component
export CLAUDE_CODE_BUILDER_DEBUG=mcp,agents
claude-code-builder build spec.md

# Trace all API calls
export CLAUDE_CODE_BUILDER_TRACE=1
claude-code-builder build spec.md

# Save debug logs
claude-code-builder build spec.md \
  --debug \
  --log-file debug.log \
  --log-level DEBUG

# Profile build performance
claude-code-builder build spec.md --profile

# Generate performance report
claude-code-builder status ./project --performance-report

# Identify bottlenecks
claude-code-builder analyze spec.md --bottlenecks

• Never commit API keys to version control
• Use environment variables or secure key stores
• Rotate keys regularly
• Use separate keys for development/production

• MCP filesystem server runs with restricted permissions
• Only specified directories are accessible
• No access to system files or parent directories
• Automatic path sanitization

• Code is scanned for common vulnerabilities
• Dependencies are checked against security databases
• Secrets are never hardcoded
• Security best practices are enforced

All operations are async by default for optimal performance:

• Parallel agent execution
• Concurrent MCP operations
• Non-blocking file I/O
• Efficient token streaming

• Intelligent context windowing
• Automatic summarization
• Relevant content extraction
• Token usage minimization

• MCP response caching
• Template caching
• Partial build caching
• Dependency caching

We welcome contributions! Please follow these steps:

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes
4. Run tests: poetry run pytest
5. Run linting: poetry run ruff check . && poetry run mypy .
6. Commit changes: git commit -m 'Add amazing feature'
7. Push to branch: git push origin feature/amazing-feature
8. Open a Pull Request

# Clone repository
git clone https://github.com/yourusername/claude-code-builder.git
cd claude-code-builder

# Install in development mode
poetry install --with dev

# Install pre-commit hooks
pre-commit install

# Run tests
poetry run pytest

# Run linting
poetry run ruff check .
poetry run mypy .

# Run formatter
poetry run black .

# Build documentation
poetry run mkdocs serve

• Follow PEP 8 with 100 character line limit
• Use type hints for all functions
• Write descriptive docstrings
• Add unit tests for new features
• Update documentation

MIT License - see LICENSE for details.

• Built on Claude Code SDK
• Powered by Model Context Protocol
• Uses Anthropic's Claude models
• UI components from Rich

• Documentation: https://docs.claude-code-builder.ai
• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Discord: Join our Discord
• Email: [email protected]

Claude Code Builder v0.1.0 - Built with ❤️ by the Claude Code Builder Team