What is Code Buddy?
Code Buddy is an open-source multi-provider AI coding agent that runs in your terminal. It supports Grok, Claude, ChatGPT, Gemini, LM Studio, and Ollama via OpenAI-compatible APIs and provider-specific SDKs.
It works as two things at once:
- A development tool β reads files, writes code, runs commands, creates PRs, plans complex tasks, and fixes its own mistakes across 5-50 tool calls per task.
- A personal assistant β talks to you by voice, remembers your preferences, monitors your screen, sends notifications to your phone via Telegram/Discord/Slack, and runs scheduled tasks 24/7 in the background.
Key highlights:
- 6 AI providers with automatic failover
- 40 bundled skills (PR workflow, DevOps, creative tools, smart home, media)
- 11 messaging channels (Terminal, Telegram, Discord, Slack, WhatsApp, Signal, Teams, Matrix, Google Chat, WebChat, HTTP API)
- Daemon mode for 24/7 background operation
- Multi-agent orchestration with self-healing
- Voice conversation with wake word detection
- OS sandbox with workspace-write mode (read-only / workspace-write / danger-full-access tiers)
- Docker sandbox for untrusted code execution
- Knowledge base injection (Knowledge.md files loaded into agent system prompt)
- Wide Research mode (parallel sub-agents decompose and research topics concurrently)
- Todo.md attention bias (task list appended to end of every LLM context turn β Manus AI pattern)
- Lessons.md self-improvement loop (PATTERN/RULE/CONTEXT/INSIGHT lessons injected before every turn β persists corrections across sessions)
- Workflow orchestration rules in system prompt (concrete plan triggers, auto-correction protocol, verification contract)
- Restorable context compression (identifiers preserved, full content recoverable on demand)
- Pre-compaction memory flush (facts saved to MEMORY.md before context is compacted β OpenClaw pattern)
- Anthropic prompt cache breakpoints (stable/dynamic split β 10Γ token cost savings)
- Per-channel streaming policies (Telegram, Discord, Slack, WhatsApp each get their own chunking/format rules)
- SSRF guard on all outbound fetches (IPv4 + IPv6 bypass vector blocking)
- Tool prefix naming convention (
shell_exec, file_read, browser_search, β¦ β Codex-style canonical aliases)
Quick Start
Prerequisites
- Node.js 18.0.0 or higher
- ripgrep (recommended for faster search)
- Docker (required for CodeAct / Open Manus mode)
brew install ripgrep
sudo apt-get install ripgrep
choco install ripgrep
Install
npm install -g @phuetz/code-buddy
npx @phuetz/code-buddy@latest
First Run
export GROK_API_KEY=your_api_key
buddy
buddy --prompt "analyze the codebase structure"
buddy --base-url http://localhost:1234/v1 --api-key lm-studio
YOLO_MODE=true buddy
Headless Mode (CI / Scripting)
buddy -p "create a hello world Express app" --output-format json > result.json
buddy -p "explain this code" --output-format json 2>/dev/null | jq '.content'
buddy -p "run tests and fix failures" \
--dangerously-skip-permissions \
--output-format json \
--max-tool-rounds 30
buddy -p "fix lint errors" --auto-approve --output-format text
Headless mode exits cleanly after completion β safe for timeout, shell scripts, and CI pipelines.
Session Management
buddy --continue
buddy --resume abc123
buddy --max-price 5.00
Typical Project Workflow
buddy --setup
buddy onboard
buddy doctor
buddy
buddy --vim
> "Create a Node.js project with Express and Prisma"
> "Add Google OAuth authentication"
> "Write tests for the auth module"
> "Fix the typecheck errors"
> "Commit everything"
buddy --model gemini-2.5-flash
buddy --system-prompt architect
buddy --agent my-custom-agent
buddy speak
buddy daemon start
buddy server --port 3000
Code Buddy autonomously reads files, writes code, runs commands, and fixes errors β typically 5-15 tool calls per task (up to 50, or 400 in YOLO mode).
Development Tool
Agentic Coding
Code Buddy operates as an autonomous coding agent. It reads your codebase, makes changes, runs commands, and iterates until the task is done.
Built-in tools:
| File Operations | view_file, create_file, str_replace_editor, edit_file, multi_edit |
| Search | search, codebase_map |
| System | bash, docker, kubernetes |
| CodeAct | run_script (Python/JS/TS in Docker), plan (Persistent Planner) |
| Web | web_search, web_fetch, browser |
| Patching | apply_patch (unified diff with fuzz factor, Codex-inspired) |
| Planning | create_todo_list, get_todo_list, update_todo_list |
| Media | screenshot, audio, video, ocr, clipboard |
| Documents | pdf, document, archive |
| Knowledge | knowledge_search, knowledge_add β search/add knowledge base entries |
| Human Input | ask_human β pause execution for mid-task user clarification (120s timeout) |
| Self-Extension | create_skill β write new SKILL.md files at runtime (self-authoring) |
| Self-Improvement | lessons_add, lessons_search, lessons_list β persist and recall learned patterns across sessions |
| Verification | task_verify β run tsc/tests/lint before marking tasks complete (Verification Contract) |
RAG-based tool selection filters tools per query to reduce prompt tokens β only relevant tools are included in each API call.
Code Intelligence
Web Search (5-Provider Fallback Chain):
| 1 | Brave MCP | BRAVE_API_KEY + MCP enabled | Full MCP integration, richest results |
| 2 | Brave API | BRAVE_API_KEY | Country, language, freshness filters |
| 3 | Perplexity | PERPLEXITY_API_KEY or OPENROUTER_API_KEY | AI-synthesized answers with citations |
| 4 | Serper | SERPER_API_KEY | Google Search results |
| 5 | DuckDuckGo | None | Free fallback (no API key needed) |
Search parameters: country (ISO 3166), search_lang, ui_lang, freshness (pd/pw/pm/py or date range), provider (force specific).
Context management uses smart multi-stage compaction (remove stale tool results, summarize older messages, aggressive truncation) to keep conversations within token limits across long sessions.
Hybrid search combines keyword + semantic search with configurable weights for memory retrieval.
π Open Manus Features (CodeAct)
Code Buddy implements the Open Manus / CodeAct architecture in a structured, phased approach, allowing it to write and execute code (Python, TypeScript, Node.js) in a secure Docker sandbox instead of relying solely on pre-defined tools.
Phase 1: Sandboxed Execution (Hybrid Agent)
- RunScriptTool: Writes and runs scripts in ephemeral Docker containers (
ubuntu:latest, node:22-slim, python:3.11-slim).
- Browser Automation: Uses
Playwright in Docker to scrape websites, interact with SPAs, and take screenshots programmatically.
- Safety First: Timeout (120s), Memory Limit (1GB), and ephemeral containers prevent runaway processes.
Phase 2: Persistent State & Planning
- Persistent Workspace: Files created in
.codebuddy/workspace persist between script executions, allowing multi-step workflows (e.g., scrape β save CSV β analyze CSV β plot chart).
- PlanTool: The agent maintains a
PLAN.md file in your project root to track complex, multi-step objectives statefully.
- Structured Loop: The system prompt enforces a strict PLAN β THINK β CODE β OBSERVE β UPDATE cognitive cycle to prevent chaotic behavior.
Phase 3: Wide Research (Parallel Agents)
- WideResearchOrchestrator: Decomposes a topic into N independent subtopics via LLM, spawns N parallel CodeBuddyAgent workers (default: 5, max: 20), then aggregates results into a single comprehensive report.
- Progress streaming: Emits real-time events as each worker completes.
- CLI:
buddy research "quantum computing breakthroughs" --workers 8 --output report.md
Phase 4: Context Engineering (Manus AI + OpenClaw patterns)
- Todo.md Attention Bias β The agent maintains a
todo.md task list that is automatically appended at the end of the LLM context on every turn. Because transformers attend more strongly to recent tokens, this keeps objectives in focus across long sessions without modifying the system prompt. Use buddy todo add/done/list or the todo_update tool.
- Restorable Compression β When the context window is compressed, file paths and URLs are extracted as identifiers and the original content is stored. The agent can call
restore_context("src/agent/types.ts") to retrieve the full content on demand, making compression lossless for structured identifiers.
- Pre-compaction Memory Flush (NO_REPLY) β Before compaction triggers, a silent background LLM turn extracts durable facts and saves them to
MEMORY.md. If the model returns the NO_REPLY sentinel with no meaningful content, the output is suppressed entirely (no notification spam).
- Inline Citations β Web search results now include
[1] [2] citation markers inline and a Sources block listing all referenced URLs.
- Lessons.md Self-Improvement Loop β After any user correction, the agent calls
lessons_add to persist the lesson (category: PATTERN, RULE, CONTEXT, or INSIGHT) to .codebuddy/lessons.md. On every turn, active lessons are injected as a <lessons_context> block BEFORE the todo suffix so learned patterns are always visible. Use buddy lessons add/search/list or the lessons_add/lessons_search tools. The task_verify tool runs the Verification Contract (tsc + tests + lint) before any task completion.
Example Prompts:
> "Go to Google News, scrape the top headlines about AI, save them to a CSV, and then use Python to analyze the sentiment."
> "Write a script to check broken links on my documentation site."
> "Calculate the Fibonacci sequence up to 1000 and plot the growth rate."
𧬠Roots & Comparison
Code Buddy is an evolution of the OpenClaw architecture, modernized for the TypeScript ecosystem and enhanced with Open Manus (CodeAct) autonomy.
| Language | Python | TypeScript / Node.js | Python |
| Philosophy | Tool-Based | Hybrid (Tool + CodeAct) | Pure CodeAct |
| Messaging | Multi-channel | 11+ Channels (Telegram focus) | Web Interface |
| Task State | Heartbeat | Persistent PLAN.md + Workspace | Transient Session |
| Concurrency | Lane Queue | Advanced Lane Queue + DAG | Sequential |
| Extensibility | SKILL.md | Skills Hub + Plugins + MCP | Custom Scripts |
Why Code Buddy?
It combines the industrial-grade reliability of OpenClaw (concurrency control, security policies, multi-channel messaging) with the infinite flexibility of Open Manus (dynamic script generation and execution).
Manus AI influence: Wide Research (parallel sub-agent research workers), Knowledge Base injection, todo.md attention bias (task list at end of context each turn), and restorable context compression (identifier-based content recovery) are all inspired by Manus AI's context engineering research. The pre-compaction NO_REPLY flush pattern is from OpenClaw's compaction documentation.
Code Safety
Code Buddy validates everything before it touches your files:
| Generated Code Validator | Pre-write scan for eval, XSS, SQL injection, hardcoded secrets, prototype pollution |
| Pre-Write Syntax Validator | Balanced delimiters, template literals, indentation (JS/TS/Python/YAML/HTML/CSS/JSON) |
| Atomic Rollback (apply-patch) | All-or-nothing patch application with full file state backup |
| Atomic Transactions (multi-edit) | Multi-file edits rolled back on first failure |
| AST Bash Validation | tree-sitter-based command parsing with centralized dangerous pattern checks |
| Bash Checkpoints | Pre-snapshot of files targeted by destructive commands (rm, mv, truncate) |
| Diff Preview | Shows actual diffs before approval, magnitude-based re-confirmation for large changes |
| Semantic Truncation | Error-preserving output truncation (keeps error lines and stack traces) |
| Security Audit Logging | JSONL audit trail for all code generation security decisions |
Task Planning
For complex multi-step requests, Code Buddy decomposes work into a DAG (directed acyclic graph) and executes steps in parallel where possible.
- TaskPlanner β
needsPlanning() heuristic detects complex requests, createPlan() produces a TaskGraph
- Topological sort β determines execution order with dependency tracking
- Parallel execution β independent steps run concurrently via dependency waves
- Architect mode β
--system-prompt architect enables plan-first coding with per-step checkpoints
CI/CD Integration
| CI Watcher | GitHub Actions / GitLab CI / Jenkins alerts with "Fix it" auto-agent |
| Webhook Triggers | HMAC-SHA256 verified HTTP triggers β connect CI, monitoring, or any service |
| Headless Mode | buddy -p "run tests and fix failures" --dangerously-skip-permissions for CI pipelines |
Git Workflow
Code Buddy handles the full Git lifecycle through natural language:
> "Create a PR for the auth changes"
> "Review the open PRs"
> "Fix the merge conflicts on feature-branch"
> "Commit everything with a good message"
Telegram enhanced commands for remote Git operations:
/repo | Repository info, recent commits, open PRs |
/branch [name] | Branch diff stats vs main |
/pr [number] | List or view PRs with merge/review buttons |
Personal Assistant
Voice Conversation
Full hands-free voice interaction with wake word detection:
buddy speak "Hello, I am Code Buddy"
buddy speak --voice af_bella "Hello world"
buddy speak --list-voices
buddy speak --speed 1.5 "Fast speech"
buddy speak --format mp3 "Hello"
buddy speak --url http://host:8000 "Hello"
7 TTS providers: Edge TTS, espeak, macOS say, Piper, OpenAI, ElevenLabs, AudioReader (Kokoro-82M local)
In-chat voice commands:
/speak <text> | Speak text with current TTS provider |
/tts on|off | Enable/disable TTS |
/tts auto | Auto-speak all agent responses |
/tts provider audioreader | Switch to AudioReader (Kokoro-82M, local, free) |
/tts voice ff_siwis | Set voice (e.g., ff_siwis FR, af_bella EN) |
Wake word detection via Porcupine (Picovoice) with text-match fallback. Set PICOVOICE_ACCESS_KEY for hardware-accelerated detection, or use the built-in text matcher for free.
Infinite voice conversation: Enable continuousListening + autoSpeak with AudioReader for a hands-free loop: listen β STT β agent β TTS β listen.
Memory System
| Persistent Memory | Markdown files | Project/user notes |
| Enhanced Memory | SQLite + embeddings | Semantic search |
| Prospective Memory | SQLite | Tasks, goals, reminders |
| ICM (optional) | ICM MCP server | Persistent cross-session memory via episodic + semantic dual architecture |
Auto-capture detects and stores important information from conversations:
"Remember that..." β Stored as instruction
"I prefer..." β Stored as preference
"This project uses..." β Stored as project fact
"My email is..." β Stored as contact info
"We decided to..." β Stored as decision
Memory lifecycle hooks inject relevant memories before execution, capture important info after responses, and summarize conversations at session end. Deduplication via Jaccard similarity (0.95 threshold) prevents duplicates.
Knowledge Base
Domain knowledge injected into the agent system prompt at startup (src/knowledge/knowledge-manager.ts):
- Sources:
Knowledge.md (project root), .codebuddy/knowledge/*.md (project-level), ~/.codebuddy/knowledge/*.md (global)
- YAML frontmatter:
title, tags, scope (restrict to specific agent modes), priority (injection order)
- Agent tools:
knowledge_search (keyword search across all entries), knowledge_add (persist new knowledge to disk)
- Injection: Loaded entries are wrapped in a
<knowledge> block and included in the system prompt automatically.
buddy knowledge list
buddy knowledge show <title>
buddy knowledge search "TypeScript conventions"
buddy knowledge add
buddy knowledge remove <title>
buddy knowledge context
Skills Library (40 Bundled Skills)
Code Buddy includes 40 built-in SKILL.md files that provide domain-specific knowledge, best practices, and MCP server integration. Skills are loaded contextually when relevant to your project.
| PR Workflow | review-pr | Code review checklist, inline comments, approval criteria |
| prepare-pr | Branch naming, commit cleanup, PR description template |
| merge-pr | Merge strategies, conflict resolution, post-merge cleanup |
| Dev Tools | github | Issues, releases, Actions workflows, gh CLI |
| gitlab | GitLab API, glab CLI, CI/CD pipelines, merge requests |
| session-logs | Export/search conversation history and session metadata |
| model-usage | Token tracking, cost analysis, provider comparison |
| tmux-sessions | Terminal multiplexing, pane layouts, session management |
| healthcheck | Service monitoring, endpoint checks, alerting |
| Project | project-best-practices | Project scaffolding, structure, linting, testing conventions |
| csharp-avalonia | Cross-platform desktop/mobile with C# and Avalonia UI |
| coding-agent | Autonomous multi-step coding with planning and validation |
| skill-creator | Author new SKILL.md files with YAML frontmatter |
| Creative & 3D | blender | Python bpy scripting, CLI rendering, Geometry Nodes |
| unreal-engine | Remote Control API, Python editor scripting, Movie Render Queue |
| davinci-resolve | DaVinciResolveScript Python API, color grading, render queue |
| ableton-live | OSC protocol, MIDI Remote Scripts, Max for Live |
| Design | figma | REST API, Plugin API, design tokens extraction |
| gimp | Python-Fu / Script-Fu scripting, batch image processing |
| inkscape | Extensions API, CLI export, SVG manipulation |
| DevOps & Infra | kubernetes | kubectl, Helm, ArgoCD GitOps |
| terraform-ansible | Terraform IaC + Ansible configuration management |
| grafana-prometheus | Grafana HTTP API, PromQL, alerting pipelines |
| jenkins-ci | Jenkins API, Groovy pipelines, shared libraries |
| Workflow & Data | n8n | REST API, webhook triggers, workflow automation |
| databases | PostgreSQL, MongoDB, Redis CLI and automation |
| game-engines | Unity C# + Godot GDScript, builds, scene management |
| Utilities | summarize | Text/file/URL summarization with configurable length |
| weather | Weather lookups via wttr.in and OpenWeatherMap |
| Media | image-gen | Image generation via DALL-E, Stable Diffusion, Midjourney |
| whisper-transcribe | Audio/video transcription with OpenAI Whisper |
| pdf-tools | PDF creation, merging, text extraction, conversion |
| screenshot | Screen capture, annotation, OCR text extraction |
| video-tools | FFmpeg video editing, conversion, thumbnails, GIFs |
| gif-search | GIF search via Giphy and Tenor APIs |
| Communication | email-tools | Email send/read via himalaya CLI and SMTP |
| notion | Notion API for pages, databases, search, content blocks |
| blog-watcher | RSS/Atom feed monitoring, web page change detection |
| Smart Home | spotify | Spotify playback control via spotify_player and Web API |
| smart-home | Philips Hue and Home Assistant control |
Each skill includes Direct Control (CLI/API/scripting commands), MCP Server Integration (config for .codebuddy/mcp.json), and Common Workflows (step-by-step recipes). Skills are stored in .codebuddy/skills/bundled/ and can be extended with managed or workspace skills via the Skills Registry and Hub.
Self-authoring skills: The agent can extend its own skill set at runtime using the create_skill tool, writing new SKILL.md files to .codebuddy/skills/workspace/. The SkillRegistry hot-reloads them within ~250ms, so newly created skills are immediately available without restarting.
Proactive Notifications
The agent can reach out to you β not just respond:
- Push notifications with priority levels (info, warning, critical)
- Rate limiting prevents notification spam
- Quiet hours β suppress non-critical notifications during configured periods
- Multi-channel delivery β notifications route to Telegram, Discord, Slack, or any connected channel
Screen Observer
Monitor your screen and environment for events:
- Periodic screenshots with perceptual diff detection
- Event triggers β
file_change, screen_change, time, webhook
- Trigger registry β add/remove triggers dynamically
buddy trigger list
buddy trigger add <spec>
buddy trigger remove <id>
Multi-Channel Messaging
Code Buddy supports 11 messaging channels:
| Terminal | Native CLI interface (Ink/React) |
| HTTP API | REST + WebSocket |
| WebChat | Built-in HTTP + WebSocket with browser UI |
| Discord | Bot integration, slash commands |
| Telegram | Bot API, pro features, scoped auth, CI watcher |
| Slack | Bolt framework, events |
| WhatsApp | Baileys (QR pairing, media, reconnect) |
| Signal | signal-cli REST API (polling, groups) |
| Google Chat | Workspace API (JWT auth, webhook events) |
| Microsoft Teams | Bot Framework (OAuth2, adaptive cards) |
| Matrix | matrix-js-sdk (E2EE, threads, media) |
Telegram (Deep Dive)
Telegram is the most feature-rich channel, giving you full agent capabilities from your phone.
Setup:
- Create a bot with @BotFather on Telegram (
/newbot)
- Configure the token:
export TELEGRAM_BOT_TOKEN=123456:ABC-DEF...
Or in .codebuddy/settings.json:
{
"channels": {
"telegram": {
"type": "telegram",
"token": "123456:ABC-DEF...",
"adminUsers": ["your_telegram_user_id"],
"defaultParseMode": "Markdown"
}
}
}
- Start Code Buddy with Telegram:
buddy --channel telegram
buddy daemon start
Deployment modes:
| Polling (default) | No extra config | Development, behind NAT |
| Webhook | "webhookUrl": "https://your-domain.com/telegram" | Production, lower latency |
Supported message types: text, images, audio, video, documents, stickers, locations, contacts, inline buttons, reply threads, typing indicators.
What you can do via Telegram:
| Remote Coding | Code modifications, bug fixes, refactoring, file analysis, create commits & PRs |
| Bash Execution | Run build, test, deploy commands β with confirmation for destructive ops |
| Rich Media | Send images β Gemini Vision analysis, send files (code, logs) β processed by agent |
| Voice Messages | Send voice notes β STT transcription β agent response |
| Daemon Mode | 24/7 background operation (buddy daemon start), cron jobs, proactive alerts |
| Notifications | Build failures, test results, heartbeat alerts pushed to your Telegram |
| Interactive | Inline buttons for confirmations, Markdown-formatted responses |
Pro features:
| Scoped Authorization | Tiered permissions: read-only β write-patch β run-tests β deploy |
| Diff-First Mode | Preview all code changes before applying β Apply / Full Diff / Cancel buttons |
| Run Tracker | Step-by-step timeline of agent runs with cost, duration, artifacts |
| CI Watcher | GitHub Actions / GitLab CI / Jenkins alerts with "Fix it" auto-agent |
| Secret Handles | Map friendly names to env vars β secrets never enter LLM context |
| Context Pins | Pin important decisions or facts for the agent to remember |
Enhanced commands:
/repo | Repository info, recent commits, open PRs |
/branch [name] | Branch diff stats vs main |
/pr [number] | List or view PRs with merge/review buttons |
/task <desc> | Create an agent task with objective |
/runs | List recent agent runs with timeline |
/run <id> | View run details with Re-run/Tests/Rollback buttons |
/yolo [minutes] | Timed full access (1-60 min, auto-revokes) |
/pins | View pinned context |
Example workflows:
Fix CI failure:
CI alert arrives β cause analysis β "Fix it" button
β agent creates fix β diff preview β Apply/Cancel
β changes applied β tests re-run
Add feature + tests + PR:
/task "add user search with tests"
β plan-first preview β approve plan
β diff-first preview β apply changes
β agent creates PR β link in chat
DM Pairing (Access Control)
Prevents unauthorized users from consuming API credits:
- Unknown user messages the bot β receives a 6-character pairing code (expires in 15 min)
- Bot owner approves via CLI:
buddy pairing approve --channel telegram ABC123
- User is added to the persistent allowlist (
~/.codebuddy/credentials/telegram-allowFrom.json)
Security features: rate limiting (5 failed attempts β 1h block), per-channel allowlists, admin bypass.
Pairing CLI commands:
buddy pairing status
buddy pairing list
buddy pairing pending
buddy pairing approve <code>
buddy pairing add <id>
buddy pairing revoke <id>
Other Channels
const discord = new DiscordChannel({
token: process.env.DISCORD_TOKEN,
allowedGuilds: ['guild-id'],
});
await discord.connect();
const whatsapp = new WhatsAppChannel({ dataPath: '~/.codebuddy/whatsapp' });
await whatsapp.connect();
const signal = new SignalChannel({ apiUrl: 'http://localhost:8080', phoneNumber: '+1234567890' });
await signal.connect();
const matrix = new MatrixChannel({ homeserverUrl: 'https://matrix.org', accessToken: '...' });
await matrix.connect();
Autonomous Agent
Daemon Mode
Run Code Buddy 24/7 in the background:
buddy daemon start [--detach]
buddy daemon stop
buddy daemon restart
buddy daemon status
buddy daemon logs [--lines N]
Features:
- PID file management with stale detection
- Auto-restart on crash (max 3 retries)
- Service registry and health monitoring (CPU, memory)
- Heartbeat engine β periodic agent wake with HEARTBEAT.md checklist, smart suppression, active hours
buddy heartbeat start
buddy heartbeat stop
buddy heartbeat status
buddy heartbeat tick
Multi-Agent Orchestration
The SupervisorAgent coordinates multiple agent instances:
- Strategies β sequential, parallel, race, all
- Shared context β thread-safe key-value store with optimistic locking
- Self-healing β error pattern recognition (6 built-in patterns), auto-recovery with exponential backoff
- Checkpoint rollback β auto-checkpoint before risky ops, rollback to last good state
YOLO Mode (Autonomous Execution)
Full autonomy with built-in guardrails for safe unattended operation:
/yolo on
/yolo safe
/yolo off
/yolo status
YOLO_MODE=true buddy
What changes in YOLO mode:
| Tool rounds | 50 | 400 |
| Cost limit | $10 | $100 (cap $1,000) |
| File edits | Confirm each | Auto-approve (up to limit) |
| Bash commands | Confirm each | Auto-execute safe commands |
Autonomy levels (fine-grained control):
/autonomy suggest
/autonomy confirm
/autonomy auto
/autonomy full
/autonomy yolo
Customize allow/deny lists:
/yolo allow "npm run dev"
/yolo deny "docker rm -f"
Built-in guardrails (always active, even in YOLO):
- Blocked paths:
.env, .git, node_modules, *.pem, *.key, credentials
- Blocked commands:
rm -rf /, sudo, git push --force origin main, DROP DATABASE
- Per-session limits on edits and commands
- Hard cost cap ($1,000 max even with
MAX_COST override)
Cron & Scheduling
The Cron-Agent Bridge connects the scheduler to CodeBuddyAgent instances for recurring tasks:
buddy trigger add time:*/30 action:run-tests
buddy trigger add webhook:deploy action:notify
Webhook triggers use HMAC-SHA256 verification with template placeholders for flexible integration.
AI Providers
Code Buddy supports multiple AI providers with automatic failover:
| Grok (xAI) | grok-4, grok-code-fast-1 | 128K | GROK_API_KEY |
| Claude (Anthropic) | claude-sonnet-4, opus | 200K | ANTHROPIC_API_KEY |
| ChatGPT (OpenAI) | gpt-4o, gpt-4-turbo | 128K | OPENAI_API_KEY |
| Gemini (Google) | gemini-2.0-flash (+ vision) | 2M | GOOGLE_API_KEY |
| LM Studio | Any local model | Varies | --base-url http://localhost:1234/v1 |
| Ollama | llama3, codellama, etc. | Varies | --base-url http://localhost:11434/v1 |
Model failover chain β cascading provider fallback with health tracking and cooldown periods.
Connection Profiles
buddy --base-url http://localhost:1234/v1 --api-key lm-studio
buddy --base-url http://localhost:11434/v1 --model llama3
buddy --model grok-code-fast-1
Profile configuration in ~/.codebuddy/user-settings.json:
{
"connection": {
"activeProfileId": "grok",
"profiles": [
{
"id": "grok",
"name": "Grok API (xAI)",
"provider": "grok",
"baseURL": "https://api.x.ai/v1",
"model": "grok-4-latest"
},
{
"id": "lmstudio",
"name": "LM Studio Local",
"provider": "lmstudio",
"baseURL": "http://localhost:1234/v1",
"apiKey": "lm-studio"
}
]
}
}
Auth profile manager β API key rotation (round-robin/priority/random strategies), session stickiness, exponential backoff on failures.
buddy auth-profile list
buddy auth-profile add <id> <provider>
buddy auth-profile remove <id>
buddy auth-profile reset
Security & Trust
Tool Policy & Bash Allowlist
Fine-grained control over what tools the agent can use:
const policy = new ToolPolicy({
allowlist: ['read_file', 'search', 'web_fetch'],
denylist: ['bash', 'write_file'],
requireConfirmation: ['delete_file'],
});
const bashPolicy = new BashAllowlist({
patterns: [/^npm (install|test|run)/, /^git (status|diff|log)/],
blocked: [/rm -rf/, /sudo/, /curl.*\|.*sh/],
});
Security Modes
suggest | Confirm all operations |
auto-edit | Auto-approve safe ops |
full-auto | Full autonomy (YOLO) |
/mode suggest
/mode full-auto
Trust Folders & Agent Profiles
- Trust folders β directory-level tool permissions via
.codebuddy-trust.json
- Agent profiles β predefined configs:
secure (read-only), minimal, power-user
- Per-model tool config β capabilities, context window, and patch format per model family
OS Sandbox β Workspace-Write Mode
Three sandbox tiers for native OS-level isolation (Codex-inspired):
read-only | None | Untrusted analysis tasks |
workspace-write | Git workspace root only | Normal development (default) |
danger-full-access | Unrestricted | Deployment/release scripts |
.git, .codebuddy, .ssh, .gnupg, .aws are always read-only regardless of mode.
const sandbox = await createSandboxForMode('workspace-write', '/my/project');
await sandbox.exec('npm', ['test']);
Exec Policy β Prefix Rules
Codex-inspired command authorization with token-array prefix matching (safer than regex β bypasses quoting/encoding tricks):
buddy execpolicy check "git push --force"
buddy execpolicy check-argv git push --force
buddy execpolicy add-prefix git push --action deny
buddy execpolicy dashboard
SSRF Guard
Comprehensive Server-Side Request Forgery protection on all outbound HTTP calls:
- Blocks RFC-1918 private ranges + loopback + link-local
- Blocks IPv4 bypass vectors: octal (
0177.0.0.1), hex (0x7f000001), short form (127.1)
- Blocks IPv6 transition addresses: NAT64 (
64:ff9b::/96), 6to4, Teredo, IPv4-mapped (::ffff:127.0.0.1)
- Async DNS resolution check before every fetch
Docker Sandbox
Containerized command execution for untrusted operations:
const sandbox = new DockerSandbox({
image: 'codebuddy/sandbox:latest',
memoryLimit: '512m',
networkMode: 'none',
timeout: 30000,
});
Auto-sandbox router automatically routes dangerous commands (npm, pip, cargo, make) to Docker when available.
Safety Rails
| Diff-First Mode | All code changes are previewed before applying. Users see file summaries, line counts, and can view the full unified diff. |
| Plan-First Mode | Multi-step tasks show the execution plan for approval before any changes are made. |
| Scoped Permissions | Users get only the access they need: read-only β write-patch β run-tests β deploy. |
| Audit Trail | Every tool execution, confirmation, and security decision is logged. |
| Secret Handles | API tokens and credentials are referenced by handle name only β actual values are resolved from env vars at runtime, never exposed to the LLM context. |
| 2-Step Confirmation | Risky operations (rollback, deploy) require double confirmation with a 2-minute timeout window. |
| Timed YOLO | /yolo grants temporary full access that auto-revokes after the specified duration. |
| DM Pairing | Unknown users must be approved before they can interact with the bot. |
Architecture
Facade Architecture
CodeBuddyAgent
β
βββ AgentContextFacade # Context window and memory management
β - Token counting, compression, memory retrieval
β
βββ SessionFacade # Session persistence and checkpoints
β - Save/load, checkpoint creation, rewind
β
βββ ModelRoutingFacade # Model routing and cost tracking
β - Provider selection, cost calculation
β
βββ InfrastructureFacade # MCP, sandbox, hooks, plugins
β - Hook execution, plugin loading
β
βββ MessageHistoryManager # Chat and LLM message history
Autonomy Layer
CodeBuddyAgent
β
βββ TaskPlanner # DAG decomposition of complex requests
β - needsPlanning() heuristic
β - createPlan() β TaskGraph β parallel execution
β
βββ SupervisorAgent # Multi-agent orchestration
β - Sequential, parallel, race, all strategies
β - SharedContext with optimistic locking
β
βββ SelfHealing # Automatic error recovery
β - Pattern recognition (6 built-in patterns)
β - Retry with exponential backoff
β
βββ ScreenObserver # Environment monitoring
β - Periodic screenshots with perceptual diff
β - Event triggers (file_change, screen_change, time, webhook)
β
βββ ProactiveAgent # Agent-initiated communication
β - Push notifications with priority levels
β - Rate limiting and quiet hours
β
βββ DaemonManager # Background process lifecycle
- PID file management, auto-restart
- Service registry, health monitoring
Core Flow
User Input β ChatInterface (Ink/React) β CodeBuddyAgent β AI Provider
β
Tool Calls (max 50/400 rounds)
β
Tool Execution + Confirmation
β
Results back to API (loop)
API Server & Integrations
REST API
buddy server --port 3000
/api/health | GET | Health check |
/api/metrics | GET | Prometheus metrics |
/api/chat | POST | Chat completion |
/api/chat/completions | POST | OpenAI-compatible |
/api/tools | GET | List tools |
/api/tools/{name}/execute | POST | Execute tool |
/api/sessions | GET/POST | Session management |
/api/memory | GET/POST | Memory entries |
/api/daemon/status | GET | Daemon status |
/api/daemon/health | GET | Health metrics (CPU, memory) |
/api/cron/jobs | GET | List cron jobs |
/api/cron/jobs/{id}/trigger | POST | Trigger a cron job |
/api/notifications/preferences | GET/POST | Notification settings |
/api/heartbeat/status | GET | Heartbeat engine status |
/api/heartbeat/start|stop|tick | POST | Heartbeat control |
/api/hub/search?q=... | GET | Search skills marketplace |
/api/hub/installed | GET | List installed hub skills |
/api/hub/install | POST | Install a skill |
/api/hub/{name} | DELETE | Uninstall a skill |
/api/identity | GET | List loaded identity files |
/api/identity/prompt | GET | Combined identity prompt |
/api/identity/{name} | PUT | Update an identity file |
/api/groups/status|list | GET | Group security status/config |
/api/groups/block | POST | Block a user globally |
/api/groups/block/{userId} | DELETE | Unblock a user |
/api/auth-profiles | GET/POST/DELETE | Auth profile CRUD |
/api/auth-profiles/reset | POST | Reset all cooldowns |
WebSocket Events
const ws = new WebSocket('ws://localhost:3000/ws');
ws.send(JSON.stringify({
type: 'authenticate',
payload: { token: 'jwt-token' }
}));
ws.send(JSON.stringify({
type: 'chat_stream',
payload: { messages: [{ role: 'user', content: 'Hello' }] }
}));
MCP Servers
Four MCP servers are pre-configured (disabled by default):
buddy mcp add brave-search
buddy mcp add playwright
buddy mcp add exa-search
buddy mcp add icm
buddy mcp list
Plugin System
Plugins extend Code Buddy with custom tools, commands, and providers:
~/.codebuddy/plugins/
my-plugin/
manifest.json
index.js
Plugin types: Tool, Provider (LLM/embedding/search), Command, Hook
const plugin: Plugin = {
async activate(context: PluginContext) {
context.registerTool({
name: 'my_tool',
description: 'Custom tool',
execute: async (args) => {
return { success: true, output: 'Done!' };
}
});
context.registerProvider({
id: 'my-llm',
type: 'llm',
async chat(messages) { return 'response'; }
});
}
};
Extensions
Manifest-based extension system with lifecycle hooks and config schema. Extensions live in .codebuddy/extensions/.
Copilot Proxy
IDE-compatible completions backend β serves /v1/completions with bearer auth, per-IP rate limiting, and token clamping.
External Tools (RTK & ICM)
| RTK | cargo install --git https://github.com/rtk-ai/rtk | CLI proxy that wraps commands to reduce LLM token usage 60-90% |
| ICM | cargo install --git https://github.com/rtk-ai/icm | MCP server for persistent cross-session memory |
RTK is automatically integrated via a before-hook β supported bash commands are prefixed with rtk transparently. Configure in .codebuddy/config.toml under [integrations].
CLI Reference
Global Options
--version | -V | Show version number | - |
--directory <dir> | -d | Set working directory | . |
--api-key <key> | -k | API key (or GROK_API_KEY env) | - |
--base-url <url> | -u | API base URL (or GROK_BASE_URL env) | - |
--model <model> | -m | AI model to use (or GROK_MODEL env) | auto-detect |
--prompt <prompt> | -p | Single prompt, headless mode | - |
--browser | -b | Launch browser UI instead of terminal | false |
--max-tool-rounds <n> | | Max tool execution rounds | 400 |
--security-mode <mode> | -s | suggest, auto-edit, or full-auto | suggest |
--output-format <fmt> | -o | Headless output: json, stream-json, text, markdown | json |
--context <patterns> | -c | Glob patterns to load into context | - |
Session & Cost
--continue | Resume the most recent saved session | - |
--resume <id> | Resume a specific session (supports partial ID matching) | - |
--max-price <dollars> | Maximum cost in dollars before stopping | 10.0 |
--no-cache | Disable response caching | - |
Autonomy & Permissions
--auto-approve | Automatically approve all tool executions | false |
--dangerously-skip-permissions | Bypass all permission checks (trusted containers only) | false |
--no-self-heal | Disable self-healing auto-correction | - |
--allow-outside | Allow file operations outside workspace directory | false |
Tool Control
--force-tools | Force-enable function calling for local models | - |
--probe-tools | Auto-detect tool support at startup | - |
--enabled-tools <patterns> | Only enable matching tools (glob, comma-separated) | bash,*file*,search |
--disabled-tools <patterns> | Disable matching tools (glob, comma-separated) | bash,web_* |
--allowed-tools <patterns> | Alias for --enabled-tools (Claude Code compat) | - |
Agent & Prompt Configuration
--system-prompt <id> | System prompt: default, minimal, secure, code-reviewer, architect (or custom from ~/.codebuddy/prompts/) | default |
--list-prompts | List available system prompts and exit | - |
--agent <name> | Use a custom agent from ~/.codebuddy/agents/ | - |
--list-agents | List available custom agents and exit | - |
Display & Debugging
--plain | Minimal formatting (plain text output) |
--no-color | Disable colored output |
--no-emoji | Disable emoji in output |
--vim | Enable Vim keybindings for input |
--mcp-debug | Enable MCP protocol debugging output |
Setup & Init
--init | Initialize .codebuddy/ directory with templates |
--dry-run | Preview changes without applying (simulation mode) |
--setup | Run interactive API key setup wizard |
--list-models | List available models from the API and exit |
Commands
Slash Commands (In-Chat)
/help | Show help |
/model [name] | Change model |
/mode [mode] | Change security mode |
/profile [id] | Switch connection profile |
/think | Enable reasoning (4K tokens) |
/megathink | Deep reasoning (10K tokens) |
/ultrathink | Exhaustive reasoning (32K tokens) |
/cost | Show cost dashboard |
/memory | Memory management |
/hooks list | List lifecycle hooks |
/plugin list | List plugins |
/speak <text> | Speak text with current TTS provider |
/tts on|off|auto | TTS control |
/yolo on|off|safe|status | YOLO mode control |
/autonomy suggest|confirm|auto|full|yolo | Autonomy level |
CLI Subcommands
buddy daemon start|stop|restart|status|logs
buddy trigger list|add|remove
buddy webhook list|add|remove
buddy hub search|install|uninstall|update|list|info|publish|sync
buddy heartbeat start|stop|status|tick
buddy identity show|get|set|prompt
buddy groups status|list|block|unblock
buddy auth-profile list|add|remove|reset
buddy device list|pair|remove|snap|screenshot|record|run
buddy config show|validate|get
buddy security-audit [--deep] [--fix] [--json]
buddy speak [text] [--voice <name>] [--list-voices] [--speed <n>] [--format <fmt>]
buddy knowledge list|show|search|add|remove|context
buddy pairing status|list|pending|approve <code>|add <id>|revoke <id>
buddy research "<topic>" [--workers N] [--rounds N] [--output file.md]
buddy todo list
buddy todo add "task description" [-p high|medium|low]
buddy todo done <id>
buddy todo update <id> [-s in_progress] [-t "new text"]
buddy todo remove <id>
buddy todo clear-done
buddy todo context
buddy lessons list [--category PATTERN|RULE|CONTEXT|INSIGHT]
buddy lessons add "what went wrong β correct approach" --category PATTERN
buddy lessons search "tsc"
buddy lessons clear [--category RULE] --yes
buddy lessons context
buddy onboard
buddy doctor
Configuration
Environment Variables
GROK_API_KEY | xAI API key | Required |
ANTHROPIC_API_KEY | Anthropic API key | - |
OPENAI_API_KEY | OpenAI API key | - |
GOOGLE_API_KEY | Google AI API key | - |
SERPER_API_KEY | Web search API key | - |
GROK_BASE_URL | Custom API endpoint | - |
GROK_MODEL | Default model | - |
BRAVE_API_KEY | Brave Search API key | - |
EXA_API_KEY | Exa neural search API key | - |
PERPLEXITY_API_KEY | Perplexity AI search key (pplx-...) | - |
OPENROUTER_API_KEY | OpenRouter key for Perplexity (sk-or-...) | - |
PERPLEXITY_MODEL | Perplexity model | perplexity/sonar-pro |
PICOVOICE_ACCESS_KEY | Porcupine wake word detection | - |
CACHE_TRACE | Debug prompt construction stages | false |
YOLO_MODE | Full autonomy | false |
MAX_COST | Cost limit ($) | 10 |
JWT_SECRET | API server auth | Required in prod |
TELEGRAM_BOT_TOKEN | Telegram bot token (from @BotFather) | - |
DISCORD_TOKEN | Discord bot token | - |
SLACK_BOT_TOKEN | Slack bot token | - |
Optional Rust tools:
| RTK | cargo install --git https://github.com/rtk-ai/rtk | CLI proxy that wraps commands to reduce LLM token usage 60-90% |
| ICM | cargo install --git https://github.com/rtk-ai/icm | MCP server for persistent cross-session memory |
Project Settings
Create .codebuddy/settings.json:
{
"systemPrompt": "You are working on a TypeScript project.",
"tools": {
"enabled": ["read_file", "search", "bash"],
"disabled": ["web_search"]
},
"security": {
"mode": "auto-edit",
"bashAllowlist": ["npm *", "git *"]
}
}
Development
git clone https://github.com/phuetz/code-buddy.git
cd code-buddy
npm install
npm run dev
npm test
npm run validate
npm run build
Test Coverage
23,700+ tests across 554+ suites covering:
- Core: Tool Policy, Bash Allowlist, Context Window Guard, Compaction
- Agent: Middleware Pipeline, Profiles, Reasoning, Streaming
- Autonomy: Daemon, Cron Bridge, Task Planner, Delegation Engine
- Observation: Screen Observer, Triggers, Proactive Notifications
- Orchestration: Supervisor, Shared Context, Self-Healing, Rollback
- Providers: Gemini (vision + conversation), OpenAI-compat, Failover
- Security: Trust Folders, Skill Scanner, Bash Parser, Session Locks
- Infrastructure: MCP Client, Webhooks, Extensions, ACP Protocol, RTK Compressor, ICM Bridge
- Voice: Wake Word, TTS Providers, Voice Control Loop
- UI: ChatHistory, ChatInterface, TabbedQuestion
Research & Inspiration
Code Buddy implements techniques from academic research and draws architectural inspiration from leading open-source projects.
Scientific Papers
Reasoning & Planning:
| Tree of Thoughts | Yao et al., 2023 β arXiv:2305.10601 | src/agent/reasoning/tree-of-thought.ts |
| RethinkMCTS | Zhang et al., 2024 β arXiv:2409.09584 | src/agent/reasoning/mcts.ts |
| TALE (Token-Budget-Aware Reasoning) | arXiv:2412.18547 | src/agent/token-budget-reasoning.ts β 68.9% token reduction |
| FrugalGPT | Stanford, 2023 β arXiv:2305.05176 | src/optimization/model-routing.ts β 30-70% cost reduction |
| LLMCompiler | arXiv:2312.04511 | src/optimization/parallel-executor.ts β 2.5-4.6x speedup |
Program Repair:
| ChatRepair | Xia et al., ISSTA 2024 β arXiv:2403.12538 | src/agent/repair/iterative-repair.ts |
| ITER | arXiv:2403.00418 | src/agent/repair/repair-templates.ts β iterative template repair |
| RepairAgent | ICSE 2024 | src/agent/repair/repair-engine.ts β autonomous LLM-based repair |
| AgentCoder | Huang et al., 2023 | src/agent/multi-agent/multi-agent-system.ts β hierarchical multi-agent code generation |
RAG & Context Management:
Observation & Optimization:
| JetBrains Context Management | JetBrains Research, 2024 | src/context/observation-masking.ts β -7% cost, +2.6% success |
| Complexity Trap | arXiv:2508.21433 | src/context/observation-masking.ts |
| Less-is-More (Tool Filtering) | arXiv, 2024 | src/optimization/tool-filtering.ts β 70% execution time reduction |
| The Prompt Report | arXiv:2406.06608 | src/prompts/system-base.ts |
Testing & Memory:
| TDD + LLM | ICSE 2024 | src/testing/tdd-mode.ts β TDD improves Pass@1 by 45.97% |
| MemGPT | UC Berkeley, 2023 | src/memory/prospective-memory.ts β stateful AI agents |
Fault Localization: Ochiai, DStar, and Tarantula (Jones et al., 2002) spectrum-based techniques in src/agent/repair/fault-localization.ts.
Inspiration Projects
Code Buddy's architecture draws from these open-source projects:
| OpenClaw | Multi-channel messaging, DM pairing, lane queue concurrency, memory lifecycle, tool policy, skills system, heartbeat, identity system, group security, hub marketplace | 40+ files across src/channels/, src/concurrency/, src/memory/, src/security/, src/skills/ |
| OpenAI Codex CLI | Apply-patch unified diff, head/tail truncation, per-model tool config, turn diff tracker, security modes, OS sandbox workspace-write tiers, shell-free exec, SSRF guard, exec policy prefix rules, shell env policy, named config profiles, tool prefix naming convention, stable JSON serialization, session fork/rollout unification | src/tools/apply-patch.ts, src/sandbox/os-sandbox.ts, src/security/ssrf-guard.ts, src/sandbox/execpolicy.ts, src/tools/registry/tool-aliases.ts, src/utils/stable-json.ts, src/observability/run-store.ts |
| Claude Code | Hook system, slash commands, MCP config, extended thinking, parallel subagents, headless output, Anthropic prompt cache breakpoints | src/hooks/, src/commands/slash-commands.ts, src/mcp/config.ts, src/optimization/cache-breakpoints.ts |
| Gemini CLI | Persistent checkpoints, context files, compress command, shell prefix, multimodal input | src/checkpoints/, src/context/context-files.ts, src/input/multimodal-input.ts |
| Aider | Repository map, voice input, unified diff editor, watch mode (IDE comments) | src/context/repository-map.ts, src/tools/voice-input.ts, src/commands/watch-mode.ts |
| Cursor | .cursorrules config, parallel agent system, sandboxed terminals, embedded browser | src/config/codebuddyrules.ts, src/agent/parallel/, src/browser/embedded-browser.ts |
| Mistral Vibe | External markdown prompts, TOML config, tool permission system, fuzzy match, update notifier | src/prompts/, src/config/toml-config.ts, src/utils/fuzzy-match.ts |
| Conductor | Spec-driven development, track system | src/tracks/ |
| RTK | Command proxy for 60-90% token reduction | src/utils/rtk-compressor.ts |
| ICM | Persistent cross-session memory via MCP | src/memory/icm-bridge.ts |
| Manus AI | Wide Research (parallel sub-agent research workers), Knowledge Base injection, todo.md attention bias, restorable context compression, pre-compaction NO_REPLY flush, inline web-search citations, observation variator (anti-repetition), structured prompt variation, tool result compaction guard, disk-backed tool results, response prefill modes (tool_choice control), WebSearchMode + domain policy, message queue debounce/cap/overflow | src/agent/wide-research.ts, src/context/observation-variator.ts, src/agent/response-constraint.ts, src/tools/web-search.ts, src/agent/message-queue.ts |
| OpenClaw | Multi-channel messaging, DM pairing, lane queue concurrency, memory lifecycle, tool policy, skills system, heartbeat, identity system, group security, hub marketplace, daily session reset, per-channel streaming policies | src/channels/streaming-policy.ts, src/channels/, src/skills/, src/daemon/daily-reset.ts |
Other influences: Rust (Result<T, E> pattern), AutoGPT, MetaGPT, CrewAI, ChatDev (role-based multi-agent), ReAct (reasoning + acting paradigm), Qodo/PR-Agent (RAG for code repos).
Benchmarks referenced: SWE-bench, HumanEval, MBPP, BigCodeBench, WebArena, Berkeley Function Calling Leaderboard.
For detailed research notes, see docs/RESEARCH_IMPROVEMENTS.md, docs/RAG_TOOL_SELECTION.md, and deep_research/ai-coding-assistant-improvements/.
Troubleshooting
API key not working
echo $GROK_API_KEY
buddy --prompt "test"
Switching providers doesn't work
buddy --base-url http://localhost:1234/v1 --api-key lm-studio --prompt "test"
buddy --list-models
Memory not persisting
ls ~/.codebuddy/memory/
rm -rf ~/.codebuddy/memory/
buddy
High latency
- Use a faster model:
buddy --model grok-code-fast-1
- Use local LLM:
buddy --base-url http://localhost:11434/v1 --model llama3
Debug mode
DEBUG=codebuddy:* buddy
License
MIT License - see LICENSE for details.