A TypeScript-based multi-agent system for automatically fixing build failures using Claude AI. The system spawns multiple specialized agents that work in parallel to analyze and fix different aspects of build failures while coordinating through an oversight agent.

• Multi-Agent Architecture: Spawns multiple agents that work on different parts of the codebase simultaneously
• Intelligent Task Distribution: Analyzes build failures and creates non-overlapping tasks for parallel execution
• Oversight System: All actions go through an approval system to prevent harmful changes
• File Locking: Prevents conflicts when multiple agents work on the same repository
• Docker-based Isolation: Each agent runs in an isolated container environment
• Flexible Environment Configuration: Support for multiple environment files with variable expansion

# Clone the repository
git clone https://github.com/rundoc/build-fixer.git
cd build-fixer

# Install dependencies
npm install

# Build TypeScript
npm run build

# Build Docker images
npm run docker:build

The build-fixer supports loading multiple environment files in order, with later files overriding earlier ones:

1. Global API Keys (~/.build-fixer/api-keys.env)

   • Store API keys that are reused across all projects
   • Example: ANTHROPIC_API_KEY, OPENAI_API_KEY

2. Project Settings (project-settings.env)

   • Project-specific configuration
   • Can be committed to the repository
   • Example: GITHUB_ORG, MAX_AGENTS, BUILD_COMMAND

3. Local Overrides (.env.local)

   • Developer-specific overrides
   • Should be added to .gitignore
   • Example: Personal GitHub tokens, debug settings

# Create template files
npm run start init -- --template api-keys
npm run start init -- --template project
npm run start init -- --template local

# Copy and edit templates
cp ~/.build-fixer/api-keys.env.template ~/.build-fixer/api-keys.env
# Edit the file with your API keys

• ANTHROPIC_API_KEY: Your Anthropic API key for Claude
• GITHUB_TOKEN: GitHub personal access token with repo permissions

• OPENAI_API_KEY: OpenAI API key (for fallback or additional analysis)
• SLACK_TOKEN: Slack bot token for notifications
• GITHUB_ORG: Default GitHub organization
• MAX_AGENTS: Maximum number of parallel agents (default: 3)
• AUTO_COMMIT: Automatically commit fixes (default: true)
• RUN_TESTS: Run tests after fixes (default: true)
• TEST_COMMAND: Command to run tests (default: npm test)
• BUILD_COMMAND: Command to build project (default: npm run build)

npm run fix -- \
  -e ~/.build-fixer/api-keys.env \
  -e ./project-settings.env \
  -r https://github.com/myorg/myrepo \
  -b main

npm run fix -- \
  -e ~/.build-fixer/api-keys.env \
  -r https://github.com/myorg/myrepo \
  -l ./build-failure.log \
  -v  # Verbose output

Options:

• -e, --env-file <paths...>: Environment files (can specify multiple)
• -r, --repo <url>: Repository URL to fix
• -b, --branch <branch>: Branch to work on (default: main)
• -l, --build-logs <path>: Path to build failure logs
• -u, --build-url <url>: URL to CI build failure
• -m, --monitor: Monitor progress after starting (default: true)
• -v, --verbose: Verbose output

npm run start validate -- -e ~/.build-fixer/api-keys.env -e ./project.env

npm run start list

npm run start stop -- --run-id build_fix_2024_12_05

1. CLI (src/cli.ts)

   • Command-line interface for interacting with the system
   • Handles environment file loading and validation

2. BuildFixer (src/BuildFixer.ts)

   • Main orchestrator that manages Docker containers
   • Starts and monitors build fix processes

3. WorkspaceCoordinator (src/coordinator.ts)

   • Analyzes build failures and creates tasks
   • Spawns and manages sub-agents
   • Handles file locking and coordination

4. SubAgent (src/subAgent.ts)

   • Individual agents that work on specific tasks
   • Requests approval for actions from oversight
   • Applies fixes and verifies results

5. OversightAgent (src/oversight.ts)

   • Reviews and approves/denies agent actions
   • Maintains audit log of all actions
   • Prevents harmful or dangerous operations

1. User provides repository URL and build failure logs
2. System clones repository and analyzes failure
3. Coordinator creates parallel tasks based on the failure
4. Multiple agents are spawned to work on different tasks
5. Each agent analyzes their assigned files and generates fixes
6. All changes go through oversight approval
7. Approved changes are applied and tested
8. Successful fixes are committed and pushed

# Run in development mode with hot reload
npm run dev

# Type checking
npm run typecheck

# Build for production
npm run build

# Build Docker images
npm run docker:build

The system uses Docker Compose to manage containers:

• Oversight Container: Runs the approval service
• Agent Workspace: Contains the coordinator and sub-agents

# Build containers
docker-compose build

# Start services
docker-compose up

# View logs
docker-compose logs -f

• Action Approval: All file modifications and command executions require approval
• Dangerous Command Blocking: Prevents execution of destructive commands
• File Locking: Prevents race conditions when multiple agents modify files
• Isolated Environments: Each agent runs in a Docker container
• Audit Logging: All actions are logged for review

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

MIT

For issues and questions, please open an issue on GitHub: https://github.com/rundoc/build-fixer/issues