{"id":28814753,"url":"https://github.com/krzemienski/claude-code-builder","last_synced_at":"2026-04-24T20:34:28.096Z","repository":{"id":298878108,"uuid":"1001163791","full_name":"krzemienski/claude-code-builder","owner":"krzemienski","description":"AI-powered Python CLI tool that automates the entire software development lifecycle using the Claude Code SDK. From specification to deployment, Claude Code Builder","archived":false,"fork":false,"pushed_at":"2025-11-15T20:54:22.000Z","size":183,"stargazers_count":16,"open_issues_count":0,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-11-15T22:20:44.818Z","etag":null,"topics":["ai-code-generation","anthropic","claude","claude-code","claude-code-sdk","opus4"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/krzemienski.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-06-12T23:40:06.000Z","updated_at":"2025-11-02T14:17:47.000Z","dependencies_parsed_at":"2025-06-13T11:51:20.527Z","dependency_job_id":null,"html_url":"https://github.com/krzemienski/claude-code-builder","commit_stats":null,"previous_names":["krzemienski/claude-code-builder"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/krzemienski/claude-code-builder","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/krzemienski%2Fclaude-code-builder","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/krzemienski%2Fclaude-code-builder/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/krzemienski%2Fclaude-code-builder/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/krzemienski%2Fclaude-code-builder/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/krzemienski","download_url":"https://codeload.github.com/krzemienski/claude-code-builder/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/krzemienski%2Fclaude-code-builder/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32239864,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-24T13:21:15.438Z","status":"ssl_error","status_checked_at":"2026-04-24T13:21:15.005Z","response_time":64,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-code-generation","anthropic","claude","claude-code","claude-code-sdk","opus4"],"created_at":"2025-06-18T16:01:54.967Z","updated_at":"2026-04-24T20:34:28.089Z","avatar_url":"https://github.com/krzemienski.png","language":"Python","readme":"# Claude Code Builder\n\n\u003e **📢 Now using v2 with Real Claude Agent SDK!**\n\u003e\n\u003e This project has been upgraded to use the official **Claude Agent SDK** (not mocks).\n\u003e - All functionality uses real SDK implementations\n\u003e - Complete async support throughout\n\u003e - Full MCP integration via `create_sdk_mcp_server`\n\u003e - Production-ready CLI with all commands\n\u003e\n\u003e The v1 implementation remains for reference but is **deprecated**.\n\nA 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.\n\n## Overview\n\nClaude Code Builder is an intelligent software generation system that:\n- **Analyzes** natural language specifications to understand project requirements\n- **Architects** optimal technical solutions using multi-agent collaboration\n- **Builds** complete applications with proper structure, testing, and documentation\n- **Manages** context intelligently to handle large specifications (150K+ tokens)\n- **Orchestrates** specialized MCP servers for various development tasks\n- **Resumes** builds from checkpoints, ensuring reliability and cost efficiency\n\n## Table of Contents\n\n- [Key Features](#key-features)\n- [System Architecture](#system-architecture)\n- [Installation](#installation)\n- [Quick Start](#quick-start)\n- [Usage](#usage)\n- [Writing Specifications](#writing-specifications)\n- [Configuration](#configuration)\n- [API Reference](#api-reference)\n- [Developer Guide](#developer-guide)\n- [Advanced Features](#advanced-features)\n- [Cost Management](#cost-management)\n- [Troubleshooting](#troubleshooting)\n- [Contributing](#contributing)\n\n## Key Features\n\n### 🤖 Multi-Agent Architecture\n- **SpecAnalyzer**: Extracts requirements, identifies ambiguities, determines scope\n- **TaskGenerator**: Creates comprehensive, ordered task lists with dependencies\n- **InstructionBuilder**: Generates precise, Claude-compatible instructions\n- **CodeGenerator**: Produces high-quality code following best practices\n- **TestGenerator**: Creates comprehensive test suites\n- **ReviewAgent**: Validates code quality and completeness\n\n### 🔄 MCP Server Integration\n- **Filesystem Server**: Secure file operations within project boundaries\n- **GitHub Server**: Repository management and version control\n- **Memory Server**: Persistent context across sessions\n- **Fetch Server**: Web resource access for research\n- **Perplexity Server**: Real-time information for technical decisions\n\n### 💾 Advanced Context Management\n- Handles specifications up to 150K tokens\n- Intelligent chunking for optimal token usage\n- Context compression without information loss\n- Adaptive loading based on current phase needs\n\n### 🔁 Checkpoint \u0026 Resume\n- Automatic checkpointing after each phase\n- Cost tracking and budget enforcement\n- Seamless resume from any interruption\n- Preserves all context and progress\n\n### 🔌 Plugin System\n- Extensible architecture for custom functionality\n- Hook into any phase of the build process\n- Create custom agents and MCP integrations\n- Share and reuse plugins across projects\n\n## System Architecture\n\nThe following Mermaid diagram illustrates how the CLI, orchestrator, agents, MCP\nservers and external services interact:\n\n```mermaid\ngraph TD\n  subgraph CLI\n    build([build])\n    analyze([analyze])\n    resume([resume])\n    validate([validate])\n  end\n\n  subgraph \"Build Orchestrator\"\n    PhaseMgr[Phase Manager]\n    CtxMgr[Context Manager]\n    Checkpoint[Checkpoint System]\n  end\n\n  subgraph \"Agent System\"\n    SpecAgent --\u003e TaskAgent --\u003e CodeAgent --\u003e TestAgent\n  end\n\n  subgraph \"MCP Orchestrator\"\n    Filesystem\n    GitHub\n    Memory\n    Perplexity\n  end\n\n  subgraph \"External Services\"\n    Anthropic\n    ExternalAPIs[\"External APIs\"]\n  end\n\n  build --\u003e PhaseMgr\n  analyze --\u003e SpecAgent\n  resume --\u003e Checkpoint\n  validate --\u003e SpecAgent\n  PhaseMgr --\u003e SpecAgent\n  Checkpoint --\u003e PhaseMgr\n  PhaseMgr --\u003e CtxMgr\n  CtxMgr --\u003e Checkpoint\n  SpecAgent --\u003e TaskAgent\n  TaskAgent --\u003e CodeAgent\n  CodeAgent --\u003e TestAgent\n  Filesystem -.-\u003e Anthropic\n  GitHub -.-\u003e Anthropic\n  Memory -.-\u003e Anthropic\n  Perplexity -.-\u003e ExternalAPIs\n```\n\n## Installation\n\n### Prerequisites\n- Python 3.11 or higher\n- Poetry (for dependency management)\n- Node.js 18+ (for MCP servers)\n- Git\n\n### Detailed Installation Steps\n\n1. **Clone the repository**\n   ```bash\n   git clone https://github.com/yourusername/claude-code-builder.git\n   cd claude-code-builder\n   ```\n\n2. **Install Python dependencies**\n   ```bash\n   # Install Poetry if not already installed\n   curl -sSL https://install.python-poetry.org | python3 -\n   \n   # Install project dependencies\n   poetry install\n   ```\n\n3. **Install MCP servers**\n   ```bash\n   # Required MCP servers\n   npm install -g @modelcontextprotocol/server-filesystem\n   npm install -g @modelcontextprotocol/server-memory\n   \n   # Optional MCP servers\n   npm install -g @modelcontextprotocol/server-github\n   npm install -g @modelcontextprotocol/server-fetch\n   npm install -g @modelcontextprotocol/server-perplexity\n   ```\n\n4. **Set up environment variables**\n   ```bash\n   # Create .env file\n   cp .env.example .env\n   \n   # Add your API keys\n   echo \"ANTHROPIC_API_KEY=your-api-key\" \u003e\u003e .env\n   echo \"GITHUB_TOKEN=your-github-token\" \u003e\u003e .env  # Optional\n   echo \"PERPLEXITY_API_KEY=your-perplexity-key\" \u003e\u003e .env  # Optional\n   ```\n\n5. **Verify installation**\n   ```bash\n   poetry run claude-code-builder --version\n   poetry run claude-code-builder doctor  # Check system configuration\n   ```\n\n## Quick Start\n\n### Your First Build\n\n1. **Create a specification file** (`my-app-spec.md`):\n   ```markdown\n   # Todo List API\n   \n   ## Overview\n   A simple REST API for managing todo items.\n   \n   ## Requirements\n   - CRUD operations for todo items\n   - SQLite database\n   - Input validation\n   - Unit tests\n   \n   ## Technology Stack\n   - Python 3.11\n   - FastAPI\n   - SQLAlchemy\n   - pytest\n   ```\n\n2. **Run the build**:\n   ```bash\n   poetry run claude-code-builder build my-app-spec.md --output ./todo-api\n   ```\n\n3. **Monitor progress**:\n   The CLI will show real-time progress with Rich formatting, including:\n   - Current phase and task\n   - Token usage and costs\n   - Estimated time remaining\n\n4. **Review the output**:\n   ```bash\n   cd todo-api\n   ls -la\n   # Your complete application with tests and documentation!\n   ```\n\n## Usage\n\n### Basic Commands\n\n```bash\n# Build from specification\nclaude-code-builder build \u003cspec-file\u003e [options]\n\n# Analyze specification without building\nclaude-code-builder analyze \u003cspec-file\u003e [options]\n\n# Resume a failed or interrupted build\nclaude-code-builder resume \u003cproject-dir\u003e [options]\n\n# Validate a specification\nclaude-code-builder validate \u003cspec-file\u003e [options]\n\n# Initialize a new project\nclaude-code-builder init \u003cproject-name\u003e [options]\n\n# Show configuration\nclaude-code-builder config show\n\n# Check system status\nclaude-code-builder doctor\n```\n\n### Build Options\n\n```bash\nclaude-code-builder build spec.md \\\n  --output ./my-project \\           # Output directory (default: auto-generated)\n  --model claude-3-opus-20240229 \\  # Model to use\n  --max-cost 50.00 \\                # Maximum build cost in USD\n  --max-tokens 5000000 \\            # Maximum tokens to use\n  --phases \"design,core,test\" \\     # Specific phases to run\n  --continue-on-error \\             # Continue even if a phase fails\n  --dry-run \\                       # Simulate without making changes\n  --no-checkpoint \\                 # Disable checkpointing\n  --parallel \\                      # Enable parallel agent execution\n  --template advanced \\             # Use advanced project template\n  -vv                              # Verbose output\n```\n\n### Advanced Commands\n\n```bash\n# Analyze with cost estimation\nclaude-code-builder analyze spec.md --estimate-cost --detailed\n\n# Validate and auto-fix issues\nclaude-code-builder validate spec.md --fix --output fixed-spec.md\n\n# Resume from specific phase\nclaude-code-builder resume ./project --from-phase testing --reset-costs\n\n# Generate specification template\nclaude-code-builder init my-project --template fullstack --output spec.md\n\n# Export build metrics\nclaude-code-builder status ./project --export metrics.json\n\n# List available plugins\nclaude-code-builder plugins list\n\n# Run with specific plugin\nclaude-code-builder build spec.md --plugins \"github-integration,docker-setup\"\n```\n\n## Writing Specifications\n\n### Basic Specification Template\n\n```markdown\n# Project Name\n\n## Overview\nBrief description of what the application does and its primary purpose.\n\n## Objectives\n1. Primary objective\n2. Secondary objectives\n\n## Requirements\n\n### Functional Requirements\n- User authentication\n- Core feature 1\n- Core feature 2\n\n### Non-Functional Requirements\n- Performance: \u003c 200ms response time\n- Security: OAuth2 authentication\n- Scalability: 10K concurrent users\n\n## Technology Stack\n- Language: Python 3.11+\n- Framework: FastAPI\n- Database: PostgreSQL\n- Testing: pytest\n\n## Success Criteria\n1. All tests passing\n2. 90% code coverage\n3. API documentation complete\n```\n\n### Advanced Specification Template\n\n```markdown\n# Enterprise Application Name\n\n## Executive Summary\nComprehensive overview including business value and strategic alignment.\n\n## Detailed Requirements\n\n### User Stories\nAs a [user type], I want to [action] so that [benefit].\n\n### API Specifications\n```yaml\nendpoints:\n  - path: /api/v1/users\n    method: POST\n    request:\n      type: object\n      properties:\n        email: string\n        password: string\n    response:\n      type: object\n      properties:\n        id: string\n        token: string\n```\n\n### Data Models\n```python\nclass User:\n    id: UUID\n    email: str\n    created_at: datetime\n    profile: UserProfile\n```\n\n### Integration Requirements\n- External API: PaymentProvider\n- Authentication: Auth0\n- Monitoring: DataDog\n\n### Performance Requirements\n- API Response: p95 \u003c 100ms\n- Database queries: \u003c 50ms\n- Concurrent users: 50K\n\n### Security Requirements\n- OWASP Top 10 compliance\n- PCI DSS for payment handling\n- GDPR compliance for EU users\n\n### Deployment\n- Container: Docker\n- Orchestration: Kubernetes\n- CI/CD: GitHub Actions\n\n## Constraints\n- Budget: $50K\n- Timeline: 3 months\n- Team: 2 developers\n\n## Acceptance Criteria\n1. All functional requirements implemented\n2. Performance benchmarks met\n3. Security audit passed\n4. Documentation complete\n```\n\n### Best Practices for Specifications\n\n1. **Be Specific**: Avoid vague requirements like \"user-friendly UI\"\n2. **Include Examples**: Provide sample data, API calls, or UI mockups\n3. **Define Success**: Clear, measurable acceptance criteria\n4. **Specify Constraints**: Budget, timeline, technology limitations\n5. **Prioritize Features**: Mark must-have vs nice-to-have features\n\n## Configuration\n\n### Project Configuration (`.claude-code-builder.json`)\n\n```json\n{\n  \"version\": \"0.1.0\",\n  \"project_name\": \"My Project\",\n  \"model\": \"claude-3-opus-20240229\",\n  \"mcp_servers\": {\n    \"filesystem\": {\n      \"enabled\": true,\n      \"allowed_directories\": [\"./src\", \"./tests\"]\n    },\n    \"github\": {\n      \"enabled\": true,\n      \"auto_commit\": false,\n      \"branch\": \"feature/ai-generated\"\n    },\n    \"memory\": {\n      \"enabled\": true,\n      \"max_entities\": 1000\n    }\n  },\n  \"build_config\": {\n    \"max_cost\": 100.0,\n    \"max_tokens\": 10000000,\n    \"checkpoint_frequency\": \"phase\",\n    \"parallel_agents\": true,\n    \"continue_on_error\": false\n  },\n  \"phases\": {\n    \"skip\": [\"deployment\"],\n    \"custom_order\": [\"design\", \"core\", \"api\", \"test\", \"docs\"]\n  },\n  \"plugins\": [\"github-integration\", \"docker-setup\"]\n}\n```\n\n### Global Configuration (`~/.claude-code-builder/config.yaml`)\n\n```yaml\napi_key: ${ANTHROPIC_API_KEY}\ndefault_model: claude-3-opus-20240229\nmcp_servers:\n  filesystem:\n    command: npx\n    args: [\"-y\", \"@modelcontextprotocol/server-filesystem\"]\n  github:\n    command: npx\n    args: [\"-y\", \"@modelcontextprotocol/server-github\"]\n    env:\n      GITHUB_TOKEN: ${GITHUB_TOKEN}\n  memory:\n    command: npx\n    args: [\"-y\", \"@modelcontextprotocol/server-memory\"]\ndefaults:\n  max_cost: 100.0\n  max_tokens: 10000000\n  verbose: 1\n  checkpoint_enabled: true\n  parallel_agents: false\nlogging:\n  level: INFO\n  file: ~/.claude-code-builder/claude-code-builder.log\n  max_size: 10MB\n  backup_count: 5\n```\n\n## API Reference\n\n### Core Classes\n\n#### BaseAgent\nBase class for all agents in the system.\n\n```python\nfrom claude_code_builder.agents import BaseAgent\n\nclass CustomAgent(BaseAgent):\n    async def execute(self, context: ExecutionContext) -\u003e AgentResponse:\n        # Implementation\n        pass\n```\n\n#### BuildOrchestrator\nManages the entire build process.\n\n```python\nfrom claude_code_builder.core import BuildOrchestrator\n\norchestrator = BuildOrchestrator(config)\nawait orchestrator.build(specification)\n```\n\n#### ExecutionContext\nProvides context and utilities to agents.\n\n```python\nclass ExecutionContext:\n    project: Project\n    mcp_clients: Dict[str, MCPClient]\n    logger: Logger\n    metrics: BuildMetrics\n    checkpoint: CheckpointManager\n```\n\n### CLI Commands\n\nAll commands support `--help` for detailed information:\n\n```bash\nclaude-code-builder build --help\nclaude-code-builder analyze --help\nclaude-code-builder resume --help\n```\n\n### Plugin System\n\nCreate custom plugins to extend functionality:\n\n```python\nfrom claude_code_builder.plugins import BasePlugin\n\nclass MyPlugin(BasePlugin):\n    def on_phase_start(self, phase: str, context: ExecutionContext):\n        print(f\"Starting phase: {phase}\")\n    \n    def on_phase_complete(self, phase: str, context: ExecutionContext):\n        print(f\"Completed phase: {phase}\")\n```\n\n## Developer Guide\n\n### Creating Custom Agents\n\n1. **Define your agent**:\n   ```python\n   from claude_code_builder.agents import BaseAgent\n   from claude_code_builder.core import AgentResponse, ExecutionContext\n   \n   class DatabaseMigrationAgent(BaseAgent):\n       \"\"\"Agent for handling database migrations.\"\"\"\n       \n       async def execute(self, context: ExecutionContext) -\u003e AgentResponse:\n           # Access MCP clients\n           filesystem = context.mcp_clients['filesystem']\n           \n           # Generate migration files\n           migrations = await self.generate_migrations(context)\n           \n           # Write files\n           for migration in migrations:\n               await filesystem.write_file(\n                   f\"migrations/{migration.name}.py\",\n                   migration.content\n               )\n           \n           return AgentResponse(\n               success=True,\n               summary=\"Generated database migrations\",\n               artifacts={\"migrations\": len(migrations)}\n           )\n   ```\n\n2. **Register your agent**:\n   ```python\n   from claude_code_builder.agents import register_agent\n   \n   register_agent(\"database_migration\", DatabaseMigrationAgent)\n   ```\n\n3. **Use in build configuration**:\n   ```json\n   {\n     \"phases\": {\n       \"custom\": {\n         \"database\": {\n           \"agent\": \"database_migration\",\n           \"config\": {\n             \"migration_style\": \"alembic\"\n           }\n         }\n       }\n     }\n   }\n   ```\n\n### MCP Server Integration\n\nCreate custom MCP clients:\n\n```python\nfrom claude_code_builder.mcp import BaseMCPClient\n\nclass CustomMCPClient(BaseMCPClient):\n    async def connect(self):\n        # Connect to your MCP server\n        pass\n    \n    async def custom_operation(self, data):\n        # Implement custom operations\n        pass\n```\n\n### Testing Your Extensions\n\n```python\nimport pytest\nfrom claude_code_builder.testing import AgentTestCase\n\nclass TestDatabaseMigrationAgent(AgentTestCase):\n    async def test_migration_generation(self):\n        context = self.create_test_context()\n        agent = DatabaseMigrationAgent()\n        \n        response = await agent.execute(context)\n        \n        assert response.success\n        assert response.artifacts[\"migrations\"] \u003e 0\n```\n\n## Advanced Features\n\n### Specification Analysis\n\nGet detailed analysis before building:\n\n```bash\nclaude-code-builder analyze spec.md --detailed\n\n# Output includes:\n# - Complexity score\n# - Estimated tokens\n# - Estimated cost\n# - Identified risks\n# - Missing requirements\n# - Suggested improvements\n```\n\n### Specification Validation\n\nValidate and fix common issues:\n\n```bash\n# Validate only\nclaude-code-builder validate spec.md\n\n# Validate and fix\nclaude-code-builder validate spec.md --fix\n\n# Common fixes:\n# - Missing required sections\n# - Ambiguous requirements\n# - Incomplete technology stack\n# - Missing success criteria\n```\n\n### Template System\n\nUse and create project templates:\n\n```bash\n# List available templates\nclaude-code-builder templates list\n\n# Use a template\nclaude-code-builder init my-project --template microservice\n\n# Create custom template\nclaude-code-builder templates create my-template --from ./existing-project\n```\n\n### Build Metrics and Analytics\n\nTrack and analyze build performance:\n\n```bash\n# View build metrics\nclaude-code-builder status ./project --metrics\n\n# Export detailed analytics\nclaude-code-builder status ./project --export analytics.json\n\n# Metrics include:\n# - Token usage by phase\n# - Cost breakdown\n# - Time per phase\n# - Error frequency\n# - Agent performance\n```\n\n### Parallel Execution\n\nEnable parallel agent execution for faster builds:\n\n```bash\nclaude-code-builder build spec.md --parallel --max-workers 4\n```\n\n### Custom Build Phases\n\nDefine custom phases in your specification:\n\n```yaml\nphases:\n  custom:\n    data_pipeline:\n      agent: \"code_generator\"\n      dependencies: [\"core\"]\n      config:\n        templates: [\"etl_pipeline.j2\"]\n    ml_training:\n      agent: \"ml_trainer\"\n      dependencies: [\"data_pipeline\"]\n```\n\n## Cost Management\n\n### Understanding Costs\n\nClaude Code Builder provides detailed cost tracking:\n\n- **Token Costs**: Based on model pricing\n- **Phase Breakdown**: Cost per build phase\n- **Cumulative Tracking**: Total project cost\n- **Budget Enforcement**: Stops when limit reached\n\n### Cost Optimization Strategies\n\n1. **Use Checkpoints**: Resume interrupted builds without re-running completed phases\n2. **Phase Selection**: Run only necessary phases\n3. **Model Selection**: Use smaller models for simpler tasks\n4. **Context Optimization**: Enable aggressive context compression\n5. **Specification Quality**: Clear specs reduce iteration\n\n### Typical Project Costs\n\n| Project Type | Complexity | Typical Cost | Token Usage |\n|--------------|------------|--------------|-------------|\n| CLI Tool | Simple | $5-15 | 50K-150K |\n| REST API | Medium | $20-50 | 200K-500K |\n| Full-Stack App | Complex | $50-150 | 500K-1.5M |\n| Enterprise System | Very Complex | $150-500 | 1.5M-5M |\n\n### Budget Management\n\n```bash\n# Set strict budget limit\nclaude-code-builder build spec.md --max-cost 25.00 --stop-on-limit\n\n# Get cost estimate first\nclaude-code-builder analyze spec.md --estimate-cost\n\n# Monitor costs in real-time\nclaude-code-builder build spec.md -vv  # Shows cost after each phase\n\n# Resume with budget reset\nclaude-code-builder resume ./project --reset-costs --max-cost 50.00\n```\n\n## Troubleshooting\n\n### Common Issues and Solutions\n\n#### Build Fails with \"Context too large\"\n**Problem**: Specification exceeds token limits\n**Solutions**:\n```bash\n# Enable context optimization\nclaude-code-builder build spec.md --optimize-context\n\n# Split into multiple files\nclaude-code-builder build main-spec.md \\\n  --include requirements.md \\\n  --include api-spec.md\n\n# Use references instead of inline content\n# In your spec:\n# See API documentation: @file:api-docs.yaml\n```\n\n#### MCP Server Connection Failed\n**Problem**: Cannot connect to MCP servers\n**Solutions**:\n```bash\n# Check server installation\nnpm list -g | grep \"@modelcontextprotocol\"\n\n# Test individual server\nnpx @modelcontextprotocol/server-filesystem --test\n\n# Check permissions\nclaude-code-builder doctor --check-permissions\n\n# View server logs\ntail -f ~/.claude-code-builder/logs/mcp-*.log\n```\n\n#### Resume Not Working\n**Problem**: Cannot resume from checkpoint\n**Solutions**:\n```bash\n# Verify checkpoint integrity\nclaude-code-builder checkpoints verify ./project\n\n# List available checkpoints\nclaude-code-builder checkpoints list ./project\n\n# Resume from specific checkpoint\nclaude-code-builder resume ./project --checkpoint phase-3\n\n# Force rebuild from phase\nclaude-code-builder resume ./project --from-phase core --force\n```\n\n#### High Token Usage\n**Problem**: Build using more tokens than expected\n**Solutions**:\n```bash\n# Analyze token usage\nclaude-code-builder analyze spec.md --token-breakdown\n\n# Enable aggressive optimization\nclaude-code-builder build spec.md \\\n  --optimize-context \\\n  --compression-level high\n\n# Exclude unnecessary phases\nclaude-code-builder build spec.md \\\n  --skip-phases \"optimization,deployment\"\n```\n\n#### Build Quality Issues\n**Problem**: Generated code doesn't meet expectations\n**Solutions**:\n```bash\n# Enable review phase\nclaude-code-builder build spec.md --enable-review\n\n# Use stricter quality settings\nclaude-code-builder build spec.md \\\n  --quality high \\\n  --test-coverage 90\n\n# Provide examples in specification\n# Include code examples, API samples, UI mockups\n```\n\n### Debug Mode\n\nEnable detailed debugging information:\n\n```bash\n# Maximum verbosity\nclaude-code-builder build spec.md -vvv\n\n# Debug specific component\nexport CLAUDE_CODE_BUILDER_DEBUG=mcp,agents\nclaude-code-builder build spec.md\n\n# Trace all API calls\nexport CLAUDE_CODE_BUILDER_TRACE=1\nclaude-code-builder build spec.md\n\n# Save debug logs\nclaude-code-builder build spec.md \\\n  --debug \\\n  --log-file debug.log \\\n  --log-level DEBUG\n```\n\n### Performance Profiling\n\n```bash\n# Profile build performance\nclaude-code-builder build spec.md --profile\n\n# Generate performance report\nclaude-code-builder status ./project --performance-report\n\n# Identify bottlenecks\nclaude-code-builder analyze spec.md --bottlenecks\n```\n\n## Security Considerations\n\n### API Key Management\n- Never commit API keys to version control\n- Use environment variables or secure key stores\n- Rotate keys regularly\n- Use separate keys for development/production\n\n### File System Security\n- MCP filesystem server runs with restricted permissions\n- Only specified directories are accessible\n- No access to system files or parent directories\n- Automatic path sanitization\n\n### Generated Code Security\n- Code is scanned for common vulnerabilities\n- Dependencies are checked against security databases\n- Secrets are never hardcoded\n- Security best practices are enforced\n\n## Performance Optimization\n\n### Async Operations\nAll operations are async by default for optimal performance:\n- Parallel agent execution\n- Concurrent MCP operations\n- Non-blocking file I/O\n- Efficient token streaming\n\n### Context Optimization\n- Intelligent context windowing\n- Automatic summarization\n- Relevant content extraction\n- Token usage minimization\n\n### Caching Strategy\n- MCP response caching\n- Template caching\n- Partial build caching\n- Dependency caching\n\n## Contributing\n\nWe welcome contributions! Please follow these steps:\n\n1. **Fork the repository**\n2. **Create a feature branch**: `git checkout -b feature/amazing-feature`\n3. **Make your changes**\n4. **Run tests**: `poetry run pytest`\n5. **Run linting**: `poetry run ruff check . \u0026\u0026 poetry run mypy .`\n6. **Commit changes**: `git commit -m 'Add amazing feature'`\n7. **Push to branch**: `git push origin feature/amazing-feature`\n8. **Open a Pull Request**\n\n### Development Setup\n\n```bash\n# Clone repository\ngit clone https://github.com/yourusername/claude-code-builder.git\ncd claude-code-builder\n\n# Install in development mode\npoetry install --with dev\n\n# Install pre-commit hooks\npre-commit install\n\n# Run tests\npoetry run pytest\n\n# Run linting\npoetry run ruff check .\npoetry run mypy .\n\n# Run formatter\npoetry run black .\n\n# Build documentation\npoetry run mkdocs serve\n```\n\n### Code Style Guidelines\n\n- Follow PEP 8 with 100 character line limit\n- Use type hints for all functions\n- Write descriptive docstrings\n- Add unit tests for new features\n- Update documentation\n\n## License\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n## Acknowledgments\n\n- Built on [Claude Code SDK](https://github.com/anthropics/claude-code-sdk)\n- Powered by [Model Context Protocol](https://modelcontextprotocol.io)\n- Uses [Anthropic's Claude](https://www.anthropic.com) models\n- UI components from [Rich](https://github.com/Textualize/rich)\n\n## Support\n\n- **Documentation**: [https://docs.claude-code-builder.ai](https://docs.claude-code-builder.ai)\n- **Issues**: [GitHub Issues](https://github.com/yourusername/claude-code-builder/issues)\n- **Discussions**: [GitHub Discussions](https://github.com/yourusername/claude-code-builder/discussions)\n- **Discord**: [Join our Discord](https://discord.gg/claude-code-builder)\n- **Email**: support@claude-code-builder.ai\n\n---\n\n**Claude Code Builder v0.1.0** - Built with ❤️ by the Claude Code Builder Team","funding_links":[],"categories":["HarmonyOS"],"sub_categories":["Windows Manager"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkrzemienski%2Fclaude-code-builder","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkrzemienski%2Fclaude-code-builder","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkrzemienski%2Fclaude-code-builder/lists"}