@phuetz/code-buddy

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.

_{A local model reasons, then uses a tool to create a real file — ~$0.0001, no cloud. More demos →}

• 🆓 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:

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.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 · [e-mail] · 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.

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

Desktop cockpit — menus, sessions, composer	Onboarding — 15 providers, ChatGPT $0 or local Ollama
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.

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}