---

What is Code Buddy?

An open-source, multi-provider AI coding agent with a terminal UI, an HTTP/WebSocket server, and the Cowork desktop app — all on one core engine. It reads files, writes code, runs commands, opens PRs, and plans complex tasks across 15 LLM providers with automatic failover and per-provider circuit breakers. With buddy login, a ChatGPT Plus / Pro subscription becomes the flat-fee brain of the whole system — no API keys, no per-token metering. An optional companion layer adds voice, durable memory, opt-in camera perception, and 24/7 background operation.

For that companion layer, buddy companion live now gives a MySoulmate-style integrated preflight: it checks whether the existing voice-assistant loop, Python vision sidecar, memory, sensory flags, Telegram, YOLO, and Fleet pieces are actually wired for a real live session, then records the result as a local self-percept.

---

In action

It writes the code and the test, then runs it — $0. Hand Code Buddy a task in the terminal; here Grok (a flat-fee subscription, no API key) writes FizzBuzz + a test and runs it green — then a human re-runs the test to confirm. Unedited:

Free local AI, with the reasoning on screen. A local Ollama model (qwen3.6:35b-a3b) thinks through a task, then uses tools to do it — no cloud, ~`$0.0001`. Unedited captures from the Cowork desktop app:

Reasoning chat — thinks step-by-step, then answers · local · ~$0.0001

Real task — reasons, uses the file tool, confirms the artifact · local · ~$0.0001

ChatGPT Pro / Plus login — buddy login, sign in once, then chat with gpt-5.6-sol from the terminal. No API key; cost reported as $0.0000 (flat-fee plan). Code Buddy discovers the models enabled for the account and keeps a compatibility fallback for staged rollouts.

xAI / SuperGrok login — buddy login xai, sign in once, then Grok answers for $0 (flat-fee subscription, no API key):

Self-audit. Asked to find a bug in its own integration code, gpt-5.5 reads provider-chatgpt-responses.ts, spots a stale-variable issue (mutated body.model not propagated), and proposes the exact fix:

On your phone — chat with the same agent over Telegram. Code Buddy runs as a messaging-channel bot, so the agent you use in the terminal is reachable from your pocket. Real, unedited captures (the bot is named "Lisa" here). The system prompt and tools scale to each question — light and instant for plain chat, escalating to load tools only when the request needs them (the same on-demand pattern as Codex / Claude):

Chat + live tools, on demand "Bonjour" answers instantly; "what time is it?" and "tomorrow's weather in Paris?" pull the time and web_search tools — only when actually asked.

Reads its own code Confirms it can inspect its own source (or any accessible file) via view_file — then introduces its recursive self-improvement →

Improves itself across sessions The lessons_* loop (Manus-inspired): after each fix or success it extracts RULE / PATTERN / CONTEXT lessons, persisted to .codebuddy/lessons.md (project + global). Accurate — matches its real source.

🎙️ And you can talk to it. Send a voice note and it replies by voice — speech-to-text (faster-whisper) and text-to-speech (Piper) both run locally, $0, mirroring your modality (voice in → voice out). Needs the local voice engines installed; it transparently degrades to a text reply otherwise.

More desktop demos (Fleet, Autonomy, Companion, …) and captures: cowork/readme.md · docs/screenshots/.

---

What's shipped

1.6.0 GA — these aren't roadmap items. The captures above are unedited, and the core runs today:

• ✅ $0 local coding agent — a local Ollama model reasons on screen, then calls tools to do real work. (the demos above)
• ✅ ChatGPT Plus/Pro → gpt-5.6-sol at $0 — buddy login, flat-fee, no API key, no per-token metering.
• ✅ Goal loops (Ralph loop) — a judge model re-checks completion every turn and auto-continues until done; proven multi-turn on a free local model, with a real in-loop length-truncation recovery (test, no mocks).
• ✅ Multi-AI Fleet — peers observe each other live and call each other's models & read-only tools (peer.chat / peer.tool.invoke).
• ✅ 15 providers with automatic failover and per-provider circuit breakers; ~110 tools, MCP connectors, and a skills marketplace.
• ✅ ~27K Vitest tests — run locally and on a real-environment runner (the suite is no-mocks / real-integration, so it needs live Ollama/Hermes/browser rather than a vanilla CI box).

Honest about scope: Hermes / OpenClaw parity lays out exactly what's shipped, what's externally-gated, and where the edges are — including which messaging channels are full integrations vs. in-process stubs.

---

Research — a sensory "nervous system" (experimental)

Toward the long-term companion/robot vision, buddy-sense/ is a Rust, event-driven perception layer. Parallel sense modules (audio VAD — energy or Silero neural; an autonomic heartbeat; screen via xcap; UI focus via AT-SPI) feed a thalamus that gates + coalesces the stream and broadcasts it over a loopback WebSocket into Code Buddy's event bus — where the heartbeat paces background memory consolidation ("dreaming", inspired by OpenClaw). Local, $0, permissive deps only (clean-room — no proprietary code copied).

The eyes are now live. buddy-vision/ (Python sidecar, sibling to buddy-sense/) watches a camera and emits semantic events — camera_alive, person_entered / person_observed / person_lost and drowsy (MediaPipe FaceLandmarker by default, optional YOLOv8 person-presence backend; transition events are state-machine deduplicated) — into the same bus. A local vision model (e.g. moondream) describes the scene on motion, and meaningful events push a Telegram alert. The world model keeps anonymous detector-episode continuity and normalized 2D image position; detection loss becomes unknown, not an invented physical departure. Raw images and paths never enter the cognitive workspace. Telegram photo upload is off by default and requires the separate CODEBUDDY_VISION_TELEGRAM_PHOTO=true consent; redacted VLM text can be explicitly enabled as short-lived cloud conversation context. Setup: buddy-vision/setup.sh.

Honestly experimental — distinct from the GA core above: the Rust daemon emits the heartbeat (+ audio from a WAV file), while live camera and live microphone run as Python sidecars (buddy-vision/watch.py and buddy-vision/ear.py) into the same bridge. The ear sidecar now defaults to BUDDY_EAR_DEVICE=auto, preferring webcam/USB microphones discovered through ALSA. speech_end → STT → response gate → think/agent → speak is wired with faster-whisper + Piper; resident voice actions use the async-scoped guarded posture CODEBUDDY_SENSORY_SPEAK_PERMISSION_MODE=default (an explicit buddy voice --mode plan session remains read-only). What's real today: the pure detector cores + thalamus + bridge are unit-tested (cargo test, 20 tests, no hardware), and the loopback bridge → event bus → reaction path (incl. speech transcription) is covered on the Code Buddy side.

cd buddy-sense && cargo test     # 20 tests, no hardware
./buddy-sense/demo.sh            # headless end-to-end: heartbeat + audio VAD → Code Buddy

Design, the five sense modules, the opt-in features, and the diagrams: buddy-sense/README.md.

---

Quick Start

# One command — installs Node if needed (no sudo), then Code Buddy
curl -fsSL https://raw.githubusercontent.com/phuetz/code-buddy/main/install.sh | sh

# …or, if you already have Node ≥ 20:
npm install -g @phuetz/code-buddy

# …or run it 24/7 in Docker (the VPS path):
docker compose up -d          # after: cp .env.example .env && set JWT_SECRET

# …or from source (newest features)
git clone https://github.com/phuetz/code-buddy.git
cd code-buddy && npm install && npm run build && npm link   # exposes `buddy` globally

Requirements: Node.js ≥ 18 for the CLI (the one-command installer provisions ≥ 20). The Cowork desktop app needs Node ≥ 22 plus a C++ build toolchain for native modules (better-sqlite3). Run buddy doctor anytime to check your environment (--fix to auto-remediate). Full install guide (one-command, Docker/VPS, npm): docs/install.md.

Then pick a brain:

# Option A — free & local: point at a local Ollama, $0
export CODEBUDDY_PROVIDER=ollama
buddy

# Option B — log in with your ChatGPT Plus / Pro subscription (no API key)
buddy login        # opens browser for OAuth → tokens persisted
buddy whoami       # ✅ connected · [email protected] · Plan: pro
buddy              # auto-routes to gpt-5.6-sol via the Codex backend, cost $0.0000

# Option C — bring your own API key
export GROK_API_KEY=...   # or GEMINI_API_KEY / OPENAI_API_KEY / ANTHROPIC_API_KEY
buddy

# Option D — log in with your xAI / SuperGrok subscription (no API key)
buddy login xai    # browser OAuth → routes to Grok (grok-4-latest), cost $0

buddy --prompt "analyze the codebase structure"   # one-shot task
buddy --yolo                                       # full autonomy

Use several logins at once, or fail over automatically across them:

buddy llm                                    # list the LLMs you're logged into + the failover order
buddy llm ensemble "is this approach sound?" # ask ChatGPT + Grok + Ollama together, then synthesize
buddy council "compare REST vs GraphQL"      # conductor roles + synthesis + judge + learned ranking
buddy council --scoreboard                   # the learned ranking (which model is best for code / reasoning / …)
CODEBUDDY_LLM_FAILOVER=1 buddy -p "…"         # if the primary errors, auto-continue on the next active LLM

buddy council takes the ensemble further: for complex tasks, a lightweight conductor assigns complementary roles (architect, implementer, reviewer, verifier, skeptic, etc.) instead of asking every model the exact same prompt. It still routes by capability and past win rate, an impartial judge scores the candidates, a synthesis pass merges the best role-specialized contributions, and a scoreboard learns which AI is best for which kind of task and role over time — so future runs can put stronger models on reviewer/verifier/architect jobs. Use --no-conductor to force the old direct fan-out, or --no-synthesis to keep only the judge-selected answer. Works in Telegram too (council <task>).

_{Your logins at a glance — and automatic failover from one to the next when one has a problem, at $0. Real run, unedited.}

_{buddy llm ensemble — every brain you're logged into answers, then it's synthesized into one. Real run, unedited.}

See Getting Started for install options, headless mode, sessions, and typical workflows.

---

Cowork Desktop

Cowork is the desktop cockpit for Code Buddy: chat, tools, traces, workflows, settings, permissions, models, MCP connectors, skills, artifacts, and companion controls — all against the same core agent as the CLI. The Code Buddy settings panel can probe the local backend, start it, discover models, and route turns through the embedded engine or a configured server.

_{Real gpt-5.5 in the Cowork desktop app — the answer streams in, cost $0.0000. MP4 →}

_{…and fully local: a reasoning model (qwen3.6:35b-a3b) thinks on screen, then answers — no cloud, $0. MP4 →}

_{The left rail opens every panel as a dock tab — here the Autonomy dashboard (24/7 daemon, free-first model ladder, live subagents) and Project Memory. MP4 →}

Home — expanded menu, quick-action cards, gradient hero	A launcher opens its panel as a tab — here the Autonomy dashboard (daemon, model ladder, subagents)
Fleet dispatch · tool-permission posture · Hermes toolsets	Light & dark themes

📄 It also builds real Office documents — via multi-step skills. Ask in plain language → the agent triggers an open-source document skill that drives openpyxl / python-pptx / python-docx in visible steps (check the lib → write the script → run it → verify) → a real, professionally-styled Excel, PowerPoint, Word, or PDF. Below, gpt-5.5 builds an Excel budget in the desktop app — the activity shows each step, cost $0.0000:

_{Prompt → the xlsx skill runs openpyxl in visible steps → a verified budget.xlsx with a live =SUM formula and styling, $0.0000. ▶ Watch the run (MP4) →}

🐍 The same engine reads, charts, researches, and automates — via clean-room Python skills. Open-source (MIT) skills extend the document story, each running real Python in the same visible steps (preflight the libs → write the script → run it → verify):

• doc-ingest — turn existing PDF / Word / PowerPoint / Excel files into clean Markdown the agent can reason over: the read counterpart to the create skills, using the already-bundled libraries (zero extra install).
• data-charts — analyze tabular data and render bar / line / scatter / pie / histogram charts with pandas + matplotlib.
• web-automate — drive a real headless browser with playwright (optional camoufox stealth) to navigate, screenshot, scrape rendered content, and fill forms.
• web-research — autonomous multi-source research: fetch pages, extract their main content, and synthesize a cited Markdown brief (lean — bundled beautifulsoup4, falls back to web-automate for JS pages).

The heavier skills are opt-in (npm run prepare:python:extras) so the base download stays lean; each preflights its dependencies and tells you exactly how to enable them — no proprietary content.

🤖 It coordinates a team of agents. /swarm <task> decomposes a goal, delegates to specialist sub-agents (coder → tester → reviewer), then synthesizes — each agent's live activity (round N, tool calls) and output visible in the panel. Below, gpt-5.5 writes and tests a Python function end-to-end — cost $0.0000:

_{Orchestrator plans → coder / tester / reviewer run in turn (live activity) → tester reports 4 tests · OK → synthesized result, all on gpt-5.5 for $0.0000.}

🎯 It works toward a standing goal. Goal mode runs an autonomous loop: the agent acts, an LLM judge checks whether the goal is satisfied after each turn, and it keeps going (within a turn budget) until done — self-correcting on the judge's feedback:

_{Act → judge rejects turn 1/20 ("not exactly one line") → agent self-corrects → ✓ Goal achieved. Real gpt-5.5 loop, $0.0000.}

# Node >= 22 required for the desktop app (the CLI runs on >= 18)
buddy install-gui          # one-time: install Electron + build the desktop bundle
buddy gui                  # launch the desktop app (or: buddy desktop)
buddy server --port 3000   # optional: shared backend for Cowork, Fleet, OpenAI-compatible clients

# Source dev loop
npm install && npm run build && npm run dev:gui

The CLI guards this: on Node < 22, buddy gui prints a clear upgrade message instead of crashing. Linux source builds need a manual Electron rebuild — see cowork/DEV-LINUX.md. Camera/voice are opt-in and local: snapshots are explicit, percepts are append-only under .codebuddy/companion/, and Cowork uses MediaPipe Tasks Vision for face/hand/pose signals. Details: Cowork Desktop · Cowork Architecture.

---

What Code Buddy does

Code Buddy is one engine — terminal, desktop, and HTTP — that an LLM drives to read code, edit files, run commands, search the web, open PRs, and plan complex work. Below is the whole surface, explained. Jump to any area:

Area	In one line	Deep dive
Providers & login	15 LLM providers + ChatGPT/xAI login at $0 flat-fee, auto-failover, ensembles	providers.md
The agentic loop	autonomous tool-calling with a middleware pipeline + confirm-before-execute	CLAUDE.md
~110 tools	edit/shell/web/browser/docs/media, RAG-selected, 5-strategy edit matching	tools-reference.md
Reasoning	extended thinking + Tree-of-Thought / MCTS, /think	reasoning.md
Goal loops & autonomy	Ralph loop + LLM judge, YOLO, a 24/7 daemon	fleet-guide.md
Multi-AI Fleet	peers call each other's models + read-only tools over WebSocket	fleet-guide.md
Self-improvement	authors + empirically gates its own lessons/tools/skills, and evolves human-gated src/ variants grounded in research (opt-in)	CLAUDE.md
Skills	40 bundled (Office/research/automation) + authored + imported, firewalled	commands.md
Memory & context	compression, importance-weighted window, JIT project context	context-engine.md
Security & sandboxing	Guardian risk-scorer, permission modes, sandbox tiers, SSRF guard, secrets	security.md
Server & infrastructure	OpenAI-compatible HTTP, WS gateway, daemon, cron	infrastructure.md
Channels	20+ messaging platforms with DM-pairing access control	channels.md
Git & code intelligence	auto-commit, /pr, LSP rename, bug finder, the Code Explorer graph	development.md
Config & modes	TOML profiles, permission/agent/security modes, model-aware limits	configuration.md

Providers & login

Code Buddy talks to 15 LLM providers through one OpenAI-compatible dispatcher (src/codebuddy/client.ts), picking exactly one strategy at startup: Grok, Claude, GPT, Gemini, Ollama, LM Studio, AWS Bedrock, Azure, Groq, Together, Fireworks, OpenRouter, vLLM, Copilot, Mistral. buddy login signs into a ChatGPT Plus/Pro subscription (routed via OpenAI's Codex Responses backend) and buddy login xai into SuperGrok — both flat-fee, no API key, cost reported $0.0000 (no per-token metering). Multiple logins coexist: buddy llm lists them, buddy llm ensemble "<q>" asks them all and synthesizes one answer, and CODEBUDDY_LLM_FAILOVER=1 auto-continues on the next active LLM when one errors (per-provider circuit breakers). [model_pairs] in TOML splits an architect and editor model. Validated live (2026-06-23, real keys / local): chat works on Mistral, Ollama, Gemini, xAI/Grok, OpenRouter and DeepSeek; agentic tool-use (real create_file/bash calls) is confirmed on Mistral and Grok. Ollama/Grok/ChatGPT are also reproduced in docs/proof.md. Anthropic is wired but its key needs API credits to verify. Other listed providers share the same dispatcher but aren't individually load-tested here.

The agentic loop

The core is a stateful multi-turn loop (src/agent/execution/agent-executor.ts, runTurnLoop): the LLM proposes tool calls, the executor validates + confirms + runs them, feeds results back, and loops until done or you stop. A middleware pipeline (src/agent/middleware/) adds turn/cost limits, reasoning injection, workflow guards, auto-repair, and quality gates in priority order. Before any risky action the ConfirmationService checks permission mode → declarative rules → session flags → the Guardian Agent, and fail-closed guards block catastrophic commands (rm -rf /, fork bombs, drop database). Run it interactively (buddy), one-shot (buddy -p "<task>"), or fully autonomous (buddy --yolo).

~110 tools

The agent has ~110 tools — file edit, shell, web search (5-provider fallback), a real headless browser, PDF/Office, media/vision, code-exec, agent orchestration — and uses RAG selection to send only the relevant ones each turn (BM25 tool_search as fallback). Edits land even in refactored code via a 5-strategy cascade: exact → flexible (trim/indent) → regex (tokenized) → fuzzy (Levenshtein 10%) → LCS (90%). It also speaks Codex-style apply_patch, and code_exec runs LLM-written JavaScript in a vm sandbox (no process/require, 30s). Extend it with MCP servers (auto-discovered from .codebuddy/mcp.json), plugins, or new tool classes.

Reasoning

Two systems: Extended Thinking (provider budget tokens — off/minimal/low/medium/high/xhigh) and Code Buddy's own Tree-of-Thought + MCTS with four depths (shallow CoT → beam search → MCTS → exhaustive). A reasoning middleware auto-detects complex queries and injects guidance; /think, /megathink, and /ultrathink set the depth, and the reason tool streams its search. (MCTSr Q-value Q(a) = 0.5·(min(R) + mean(R)).)

Goal loops & autonomy

A goal loop is autonomy with a referee: the agent acts, an LLM judge checks the goal after each turn, and it self-corrects until done or the turn budget runs out — no hand-written retry logic. Drive it with /goal "<objective>" + /subgoal (numbered criteria), or headless buddy goal. buddy --yolo grants 400 tool rounds under a $100 cap with guardrails, and the 24/7 autonomous daemon (buddy autonomy install) claims tasks from a shared queue and runs them free-first (local → Tailscale → paid). That queue is a unified kanban board: the agent's kanban_* tools and the daemon drive one shared board with a claim lease + heartbeat, zombie reclaim of a crashed peer's work, a retry budget that dead-letters a hopeless task to a review column, and a dependency DAG — view it as Hermes-style columns with buddy autonomy tasks board.

Multi-AI Fleet

Run several Code Buddy instances as peers on a WebSocket mesh that observe each other's events live and call each other's models + read-only tools: peer.chat (one-shot), peer.chat-session.* (multi-turn, persisted), and peer.tool.invoke (remote read-only tools, behind three security gates that fail closed). /fleet route "<prompt>" classifies a task, gathers peer capabilities, runs a privacy lint (SSN/IBAN/card detection), and recommends a delegation; /fleet listen|send|status|history manage the mesh. It interops over A2A + ACP + MCP.

Self-improvement

A confirmation-gated conversational forge plus two opt-in improvement loops. None auto-edit main.

• Conversational extension forge (extension_forge): on request, authors a new inert widget, sandboxed executable tool (authored__*), or reusable skill (authored-*). It is confirmation-gated; tools must pass functional plus robustness cases, widgets pass an inert-markup and anti-hardcoding gate, and skills pass a prompt-injection/exfiltration firewall. Accepted tools are callable in the same conversation and persist across restarts. Never touches src/.
• Autonomous learned layer (CODEBUDDY_SELF_IMPROVE=true, buddy improve …): runs the bounded background author-and-measure loop for lessons, tools, and skills. It remains opt-in even though user-requested extension_forge creation is available by default.
• Evolutionary self-improvement (CODEBUDDY_EVOLVE=true, buddy evolve run|list|tree|review|keep): generates candidate code variants of Code Buddy's own source in throwaway git worktrees, scores each against an empirical fitness baseline (regressions + tests), keeps the best via MAP-Elites diversity — and it's human-gated: keep --confirm merges only into your current branch, never automatically, never onto main. Each generation records its genealogy (parent/generation) and the plan that produced it. Goals can be grounded in ingested research (--source research): it matches scientific articles in the collective knowledge graph to the concerned feature and synthesizes a targeted goal — so improvement draws on the literature, not just internal heuristics. Deliberately bounded, reversible, opt-in and off by default.

Skills

Skills are procedural guidance (Markdown + frontmatter + triggers) the agent discovers and injects by topic. 40 are bundled, including ones that build real Office docs and run analysis in visible Python steps (preflight libs → write script → run → verify): xlsx/docx/pptx, doc-ingest (PDF/Office → Markdown), data-charts (pandas/matplotlib), web-automate (Playwright), web-research (cited briefs). The agent can also author its own skills and import external ones from Hermes / OpenClaw — every imported skill is scanned by a firewall that quarantines prompt-injection/exfiltration payloads (buddy skills import|imported|list).

Memory & context

For long sessions, ContextManagerV2 compresses with a sliding window + importance-weighted scoring (errors 0.95, decisions 0.90, code 0.70, chat 0.25 — high-value messages survive truncation), masks old tool output, prunes stale images, and repairs the transcript after compaction. JIT context loads nearby CODEBUDDY.md/CONTEXT.md/AGENTS.md files when a tool touches a path, and each turn injects <lessons_context> and <todo_context>. Durable facts persist to bounded project/user memory (/memory recent|remember|recall), security-scanned against injection/secret-exfiltration.

Security & sandboxing

Layered, fail-closed safety: the Guardian Agent scores each operation 0–100 (auto-approve <80, prompt 80–90, deny ≥90; read-only tools skip the LLM call), permission modes (plan/acceptEdits/dontAsk/bypassPermissions), sandbox tiers (read-only / workspace-write / full-access via bubblewrap·landlock·seatbelt, with .git/.ssh/.aws always read-only), an SSRF guard (blocks private ranges + IPv4/IPv6 bypass vectors with a DNS check before every fetch), an AES-256-GCM secrets vault (buddy secrets), a write policy (strict forces apply_patch), and an output sanitizer that strips model-leakage tokens.

Server & infrastructure

buddy server exposes an HTTP API (port 3000) including an OpenAI-compatible /api/chat/completions, plus a WebSocket gateway (3001) for desktop/mobile clients (device pairing, presence, Origin-hardened, JWT in production). A daemon runs 24/7 with auto-restart, a heartbeat checklist, daily session reset, and a cross-platform service installer (systemd/launchd/Task Scheduler). Cron scheduling (buddy cron add) supports no-LLM --watchdog monitors and --pre-check gates so an expensive LLM run only fires when something actually changed.

Channels

Code Buddy runs on 20+ messaging platforms — Telegram, Discord, Slack, WhatsApp, Signal, Matrix, IRC, Nostr, Mattermost, Nextcloud Talk, iMessage (real persistent transports with auto-reconnect) plus REST/webhook adapters (Teams, Google Chat, Feishu, LINE, ntfy, DingTalk, WeCom, …). DM pairing prevents unauthorized credit burn: an unknown user gets a 6-char code (15-min TTL) you approve via buddy pairing approve. (A few niche adapters — Twitch/Tlon/Gmail — are in-process stubs, and Feishu real-time inbound needs the Lark SDK installed.)

Multiple bots, each with its own memory. Run several bots from one instance (e.g. several Telegram tokens). Each gets its own persona — name, model, and system prompt via channels.json — and its own isolated persistent memory under ~/.codebuddy/bots/<id>/, so two bots never see each other's remembered facts. Every conversation is session-isolated per (channel, user) (no cross-user context bleed) and persists across daemon restarts (history is replayed from disk onto a cold agent). Cross-channel identity links can still collapse the same person's Telegram + Discord into one canonical thread.

Git & code intelligence

buddy dev run plans + implements + tests + auto-commits with a Conventional-Commit message; /pr opens a summarized PR; lsp_rename/lsp_code_action drive language servers for safe refactors; the bug finder flags 25+ patterns across 6 languages. For whole-repo understanding, the optional Code Explorer (the gitnexus MCP server — a standalone Rust code-intelligence engine) pre-indexes the repo into a knowledge graph with 30 public tools (+ a private business tool) for impact/blast-radius, coupling, hotspots, and execution traces, answering structural questions with ~40× less context. Code Buddy also runs as an ACP agent (buddy acp) so editors like Zed can drive it natively.

Config & modes

Configure via env vars, TOML profiles ([profiles.<name>], buddy --profile), and per-project .codebuddy/settings.json. Permission modes gate approvals, agent modes (plan/code/ask/architect) restrict the tool surface, and security modes (suggest/auto-edit/full-auto) tune the approval flow. Per-model capabilities (context window, max output, patch format) live in src/config/model-tools.ts. The UI ships in English and French (complete); de/es/ja/zh are registered locale scaffolds that currently fall back to English.

---

Documentation

Document	Description
Install	The three install paths — one-command curl | sh, Docker/VPS (24/7), npm
Getting Started	Prerequisites, install, first run, headless mode, sessions
Providers	All 15 providers, connection profiles, model pairs, circuit breaker
Tools Reference	Tool categories, RAG selection, edit matching, apply_patch, streaming
Commands	All slash commands, CLI subcommands, companion commands, global flags
Cowork Desktop · Architecture · README	Desktop overview, install, source build, sandbox modes, internals
Agents · Reasoning	Orchestration, SWE agent, planning flow, A2A; thinking, ToT, MCTS
Fleet Guide	Multi-AI hub, peer-rpc methods, env-driven auto-detect, Tailscale labs
Security · Context Engine	Permission modes, Guardian, sandboxing, secrets; compression, JIT context
Channels · Configuration	20+ channels, DM pairing; env vars, TOML, model limits
Infrastructure · Deployment	Server, gateway, daemon, cron; systemd, Docker, Kubernetes, upgrades
Development	Build, test, architecture, conventions, adding tools
Hermes / OpenClaw Parity	Where Code Buddy stands vs Hermes Agent & OpenClaw

---

Contributing

git clone https://github.com/phuetz/code-buddy.git
cd code-buddy && npm install
npm run dev          # development mode
npm run validate     # lint + typecheck + test (run before committing) — 27K+ Vitest tests

See Development for architecture and coding conventions, and CONTRIBUTING.md for the workflow.

---

License

MIT — see LICENSE.

---