BugBuster Code

Model-agnostic AI coding agent for your terminal

Connect any LLM — OpenAI, Anthropic, Ollama, Cavibora, or OpenAI-compatible — and give it 33 tools to read, write, edit, search, and execute code. Plus multimodal: screenshots, voice, vision. Plus Agent Hub: coordinate multiple agents in a shared workspace.

⚡ 30-Second Setup

# macOS / Linux
curl -sL https://github.com/Cavibora/bugbuster-code/releases/latest/download/bugbuster_$(uname -s)_$(uname -m).tar.gz | tar xz
mv bugbuster /usr/local/bin/

# Or build from source
go install github.com/Cavibora/bugbuster-code/cmd/bugbuster@latest

# Configure (one-time)
bugbuster config init

# Run
bugbuster                    # interactive CLI
bugbuster --tui              # terminal UI
bugbuster "Fix the bug"     # one-shot

🆚 Why BugBuster Code?

🛠️ 33 Built-in Tools

✨ Highlights

• 🪞 Speed Mirror — model sees its own performance and self-optimizes context usage
• 💥 Aggressive Compaction — /compact! for emergency context reduction; auto-triggers on 3x slowdown
• 🧠 Self-Awareness — self_info tool lets the model know its provider, context usage, and environment
• 🔐 Granular Permissions — per-tool permission overrides (bash: ask, web_fetch: deny, etc.)
• 🔄 Fallback Providers — automatic switch to backup provider when primary fails
• 🏠 Agent Hub — coordinate multiple agents in a shared workspace: message, broadcast, request help, share tasks. Per-provider roles (coder, reviewer, tester).
• 🖥️ Screenshots & Vision — capture desktop, window, or region; send images to vision models
• 🎤🔊 Voice — speech-to-text (Whisper) and text-to-speech (OpenAI TTS or system)
• 🌍 8 Languages — English, Russian, Spanish, French, German, Japanese, Chinese, Portuguese
• 🤝 Sub-agents — isolated context, parallelism semaphore, timeouts
• 📡 MCP — both client and server (stdio, SSE, streamable HTTP)
• 🎯 Skills — reusable step-by-step procedures (debug, refactor, review, deploy, analyze + custom)

📦 Configuration

Create bugbuster.yaml in your project root or ~/.bugbuster/config.yaml:

default_provider: openai

providers:
  openai:
    type: openai
    api_key: ${OPENAI_API_KEY}
    model: gpt-4o
    max_tokens: 8192
    context_window: 128000

  anthropic:
    type: anthropic
    api_key: ${ANTHROPIC_API_KEY}
    model: claude-sonnet-4-20250514
    max_tokens: 8192
    context_window: 200000

  ollama:
    type: ollama
    base_url: http://localhost:11434
    model: llama3

agent:
  permission_mode: auto-approve
  language: en

  # Per-tool permission overrides
  permissions:
    bash: ask          # always ask before running commands
    web_fetch: deny     # block HTTP requests
    kill: deny          # block process killing

  # Fallback provider — switch when primary fails
  fallback:
    provider: ollama
    max_retries: 2
    retry_delay_ms: 1000
    auto_switch_back: true

  # Auto-switch provider by task type
  agent_providers:
    thinking: anthropic    # complex reasoning → Claude
    coding: openai        # code generation → GPT-4o
    fast: ollama           # quick tasks → local model

tools:
  screenshot:
    enabled: true
  tts:
    enabled: true
    model: tts-1
    voice: alloy
  stt:
    enabled: true
    model: whisper-1

Full config reference: docs/CONFIGURATION.md

🏠 Agent Hub

Run multiple BugBuster Code agents in separate terminals — they discover each other automatically and coordinate via a shared workspace:

hub:
  enabled: false                   # Disabled by default
  name: "bugbuster-coder"          # Agent display name
  role: "coder"                    # Role: coder, reviewer, tester, architect
  intelligence: "expert"           # low, medium, high, expert, superior (or 1-5)
  heartbeat_seconds: 30            # Heartbeat interval

Per-provider override — different models can have different roles:

providers:
  openai:
    model: gpt-4o
    hub:
      role: "coder"                # GPT-4o writes code

  anthropic:
    model: claude-sonnet-4-20250514
    hub:
      role: "reviewer"             # Claude reviews code

Hub tools available to the model:

Example workflow: Open 3 terminals, each running BugBuster with a different role. The coder writes code, the reviewer reviews it, the tester runs tests — all coordinated through the hub.

🔒 Security

• Path traversal protection — blocks .. outside working directory
• Secret files — blocks access to .env, *.pem, credentials.*, .ssh/*
• System paths — blocks writes to /etc, /usr, /System, /Library
• Command blocking — configurable blocked commands list
• Network control — allow_network: false blocks all HTTP
• Sandbox mode — restrict all file writes to a directory
• Per-tool permissions — granular auto-approve/ask/deny per tool

🌍 Languages

BugBuster Code speaks your language:

bugbuster --lang ru    # Русский
bugbuster --lang es    # Español
bugbuster --lang fr    # Français
bugbuster --lang de    # Deutsch
bugbuster --lang ja    # 日本語
bugbuster --lang zh    # 中文
bugbuster --lang pt    # Português

📖 Documentation

• Architecture — how it works internally
• Tools Reference — all 22 tools in detail
• Configuration — full config reference
• Contributing — how to contribute
• Security Policy — reporting vulnerabilities
• README (Русский) — документация на русском

🤝 Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing)
5. Open a Pull Request

📄 License

MIT License — see LICENSE for details.

Made with ❤️ by Cavibora