Code Buddy

The open-source AI coding agent that runs free, on your own machine

Watch a local model reason on screen, then use real tools to do the work — no cloud, no API bill, ~$0. Or bring any of 15 providers (Claude, GPT, Grok, Gemini, …) with automatic failover. From your terminal, a desktop app, your phone, or a 24/7 service. No lock-in.

• 🆓 Free & local-first — runs entirely on local Ollama ($0), any of 15 providers with auto-failover, or a flat-fee ChatGPT Plus/Pro login (no API metering).
• 🧠 Reasoning you can watch — local models think step-by-step on screen, then call tools to act. See the live captures.
• 🛠️ ~110 tools — edit, shell, web search, browser, PDFs/Office, a skills marketplace, and MCP connectors to extend it.
• 🖥️ Runs everywhere — terminal TUI, the Cowork desktop app, an HTTP/WebSocket server, your phone, or a 24/7 background service — one core engine.
• 🤝 Multi-AI Fleet — peers observe each other live and call each other's models & read-only tools (peer.chat / peer.tool.invoke) across your network.
• 👁️ Personal companion (optional) — bidirectional voice, opt-in camera/presence, persistent memory, and 20+ messaging channels.

Don't take our word for it — see it work, reproduce it yourself ✅. Every headline claim above, with the exact command and the real $0 output (local model writes code + a passing test, goal mode, the desktop app, the autonomous fleet loop).

Live site ↗ · Proof ✅ · Quick Start · In action · Features · FAQ · Docs · Contributing

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.

In action

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:

ChatGPT Pro / Plus login — buddy login, sign in once, then chat with gpt-5.5 from the terminal. No API key; cost reported as $0.0000 (flat-fee plan).

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:

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

What's shipped

1.2.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.5 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.

Quick Start

# Install from npm
npm install -g @phuetz/code-buddy

# …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 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).

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.5 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
CODEBUDDY_LLM_FAILOVER=1 buddy -p "…"         # if the primary errors, auto-continue on the next active LLM

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.

📄 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:

🐍 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:

🎯 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:

# 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.

Features

| Category | Highlights | Docs | |:---------|:-----------|:-----| | AI Providers | 15 providers (Grok, Claude, GPT, Gemini, Ollama, LM Studio, AWS Bedrock, Azure, Groq, Together, Fireworks, OpenRouter, vLLM, Copilot, Mistral), circuit breaker, model pairs | providers.md | | Tools | ~110 tools with RAG selection, multi-strategy edit matching, Codex-style apply_patch, streaming, BM25 tool search, code-exec sandbox | tools-reference.md | | Commands | 190+ slash commands & CLI subcommands (/goal, /dev, /pr, /lint, /switch, /think, /batch, …) | commands.md | | Cowork Desktop | Electron cockpit, embedded engine, backend health/start controls, model settings, permission rules, visual workflows, traces, artifacts, MCP/skills/plugins | cowork.md, ARCHITECTURE.md | | Agents | Multi-agent orchestration (5-tool API), 8 specialized agents, SWE agent, planning flow, A2A protocol, batch decomposition, agent teams | agents.md | | Goal loops | /goal + /subgoal Ralph loop — a judge model re-checks completion every turn and auto-continues until done (turn budget, pause/resume, fail-open); headless buddy goal, board goal-mode, peer-session goals | fleet-guide.md | | Reasoning | Tree-of-Thought + MCTS (4 depth levels), extended thinking, auto-escalation, /think | reasoning.md | | Fleet & Autonomy | Peer-to-peer hub (peer.chat / peer.tool.invoke / peer_delegate), A2A + ACP + MCP interop, 24/7 autonomous service (buddy autonomy install), event-driven daemon, free-first local→Tailscale→paid tiering | fleet-guide.md | | Security | Guardian Agent (AI risk scoring), OS/Docker/OpenShell sandbox, SSRF guard, secrets vault, write/exec policy, loop & omission detection, output sanitizer | security.md | | Context Engine | Smart compression, tool-output masking, image pruning, transcript repair, pre-compaction flush, JIT context, importance-weighted window | context-engine.md | | Channels | 20+ messaging channels (Telegram, Discord, Slack, WhatsApp, Signal, Teams, Matrix, …), DM pairing, send policy | channels.md | | Companion & Vision | ChatGPT-backed identity, voice/TTS, proactive check-ins, self-evaluation, mission board; opt-in webcam + MediaPipe face/hand/pose percepts, local face enrollment | commands.md | | Memory & Knowledge | Persistent + semantic + decision + coding-style memory, cross-session ICM, knowledge-base injection, 40 bundled skills, runtime self-authored skills | context-engine.md | | Infrastructure | HTTP server (OpenAI-compatible), WebSocket gateway, daemon, cron, device nodes, canvas/A2UI, cloud deploy configs, MCP, plugins | infrastructure.md | | Configuration | Env vars, TOML config with profiles, model-aware limits, per-agent params, i18n (6 locales), personas | configuration.md | | Git & Code Intel | Auto-commit (Aider-style), /pr, merge-conflict resolver, LSP rename/refactor, bug finder (25+ patterns, 6 langs), OpenAPI generator, IDE extensions | development.md |

Documentation

| Document | Description | |:---------|:------------| | 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.

Report Bug · Request Feature · Star on GitHub ⭐

Multi-AI: Grok · Claude · ChatGPT · Gemini · LM Studio · Ollama · AWS Bedrock · Azure · Groq · Together · Fireworks · OpenRouter · vLLM · Copilot · Mistral