Claude Code Builder

📢 Now using v2 with Real Claude Agent SDK!

This project has been upgraded to use the official Claude Agent SDK (not mocks).

All functionality uses real SDK implementations

Complete async support throughout

Full MCP integration via create_sdk_mcp_server

Production-ready CLI with all commands

The v1 implementation remains for reference but is deprecated.

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

Overview

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

Key Features

🤖 Multi-Agent Architecture

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

🔄 MCP Server Integration

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

💾 Advanced Context Management

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

🔁 Checkpoint & Resume

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

🔌 Plugin System

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

System Architecture

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

Installation

Prerequisites

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

Detailed Installation Steps

Clone the repository

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

Install Python dependencies

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

# Install project dependencies
poetry install

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

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

Verify installation

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

Quick Start

Your First Build

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

Run the build:

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

Monitor progress: The CLI will show real-time progress with Rich formatting, including:
- Current phase and task
- Token usage and costs
- Estimated time remaining

Review the output:

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

Usage

Basic Commands

# 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

Build Options

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

Advanced Commands

# 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"

Writing Specifications

Basic Specification Template

# 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

Advanced Specification Template

# 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

Data Models

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

Integration Requirements

External API: PaymentProvider
Authentication: Auth0
Monitoring: DataDog

Performance Requirements

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

Security Requirements

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

Deployment

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

Constraints

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

Acceptance Criteria

All functional requirements implemented
Performance benchmarks met
Security audit passed
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"]
}

Global Configuration (`~/.claude-code-builder/config.yaml`)

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

API Reference

Core Classes

BaseAgent

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

BuildOrchestrator

Manages the entire build process.

from claude_code_builder.core import BuildOrchestrator

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

ExecutionContext

Provides context and utilities to agents.

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

CLI Commands

All commands support --help for detailed information:

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

Plugin System

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}")

Developer Guide

Creating Custom Agents

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)}
        )

Register your agent:

from claude_code_builder.agents import register_agent

register_agent("database_migration", DatabaseMigrationAgent)

Use in build configuration:

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

MCP Server Integration

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

Testing Your Extensions

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

Advanced Features

Specification Analysis

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

Specification Validation

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

Template System

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

Build Metrics and Analytics

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

Parallel Execution

Enable parallel agent execution for faster builds:

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

Custom Build Phases

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"]

Cost Management

Understanding Costs

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

Cost Optimization Strategies

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

Typical Project Costs

Project Type	Complexity	Typical Cost	Token Usage
CLI Tool	Simple	$5-15	50K-150K
REST API	Medium	$20-50	200K-500K
Full-Stack App	Complex	$50-150	500K-1.5M
Enterprise System	Very Complex	$150-500	1.5M-5M

Budget Management

# 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

Troubleshooting

Common Issues and Solutions

Build Fails with "Context too large"

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

MCP Server Connection Failed

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

Resume Not Working

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

High Token Usage

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"

Build Quality Issues

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

Debug Mode

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

Performance Profiling

# 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

Security Considerations

API Key Management

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

File System Security

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

Generated Code Security

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

Performance Optimization

Async Operations

All operations are async by default for optimal performance:

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

Context Optimization

Intelligent context windowing
Automatic summarization
Relevant content extraction
Token usage minimization

Caching Strategy

MCP response caching
Template caching
Partial build caching
Dependency caching

Contributing

We welcome contributions! Please follow these steps:

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

Development Setup

# 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

Code Style Guidelines

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

License

MIT License - see LICENSE for details.

Acknowledgments

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

Support

Documentation: https://docs.claude-code-builder.ai
Issues: GitHub Issues
Discussions: GitHub Discussions
Discord: Join our Discord
Email: support@claude-code-builder.ai

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

FilesExpand file tree

README.md

Latest commit

History