@phuetz/code-buddy

Code Buddy 2.1

A local-first AI coding agent that can also run as a fleet, a desktop app, and a companion. It reads your repository, writes code, runs commands, and you can watch it work — on your machine, at $0 with Ollama or a ChatGPT subscription.

Français · What Code Buddy is · Install · First run · Opt-in · Not ready · License · Documentation

_{A local model reasons on screen, then uses a tool to create a real file. No cloud API bill.}

_{The big picture: interfaces, the agentic runtime, tools and providers, and the loop that turns an idea into an improvement.}

What Code Buddy is

One minute with Lisa · French presentation

Watch on YouTube · MP4 alternative · French subtitles

Lisa introduces the multi-AI hub, installation and optional perception components. Edited on September 13, 2026 from an existing September 10 master, with a synthetic voice and portrait, illustrative footage and French captions. Illustrations are not execution evidence. Voice and robotics require additional components beyond the npm package.

Code Buddy combines a terminal coding agent with cloud, gateway and local model routing, query-selected tools, and the following interfaces. Optional services require their documented configuration; enabling a feature does not replace its permission checks.

New in 2.1: explicit resource discovery and selection, RagChat search with page citations, MCP configuration import, a bounded A2A JSON-RPC bridge, and fixes for terminal sessions, configuration diagnostics and Cowork workflows. Read the release notes for setup and the limits of each integration.

• A multi-AI fleet hub. Peers running buddy server observe each other's events and call each other's models: one-shot peer.chat, multi-turn peer.chat-session.*, and peer.tool.invoke for remote read-only tools. That last one passes three ordered gates — an allowlist, a per-tool fleetSafe flag, and a workspace root that fails closed when unset, so a misconfigured peer cannot expose its disk. See Fleet.

• Cowork, a desktop GUI. An Electron app with a visual workflow runner, a media library and a video studio. It is a separate package needing Node.js ≥ 22 — see Cowork.

• Ten opt-in innovations. Speculative writes validated in a ghost worktree before touching your files, per-turn time-travel sessions, falsifiable intent specs, pull-only knowledge-graph federation between peers, a capability self-benchmark, recoverable ("zoom-in") compaction, generative widgets, on-screen error watching, signed skill packages, and read-only multi-repo search. Index: docs/cb2/README.md.

• A self-improvement loop with four learnable surfaces. The agent can propose lessons, tools it writes itself, skills, and execution strategies — and each proposal is empirically gated: applied to a snapshot, re-scored, and rolled back on regression or no gain. Authored tools face held-out cases hidden from the proposer, so a tool that hardcodes the visible answers is rejected. A strategy is a schema-checked JSON in which no field can disable a guard. The loop never edits the agent's own src/ — that is a scanned invariant.

• A council that learns which model to trust. Several models answer under a falsifiable-output contract, a judge scores them, and a scoreboard records which model wins which kind of task. The judge abstains rather than guess.

• A perception layer. A Rust sense daemon (audio, vision, screen, UI focus, heartbeat) feeds events to the agent over a loopback-only bridge; speech, camera reactions and spoken reminders build on it. It stays silent until you turn it on.

Install

Three commands (Node.js ≥ 20):

npm i -g @phuetz/code-buddy   # the package is scoped; `code-buddy` alone is not on npm
buddy login                   # ChatGPT subscription — no API key, $0 marginal cost
buddy                         # start chatting

buddy login also accepts xai. To stay entirely local instead, skip it, start Ollama, and run buddy onboard. Either way buddy doctor tells you in one line whether you are ready, and buddy doctor --fix can point a running Ollama at a suitable installed model and say why it chose it.

The published package can lag this repository. To track the source instead:

git clone https://github.com/phuetz/code-buddy.git
cd code-buddy && npm install
npm run build && npm link

The Cowork desktop app is a separate step needing Node.js ≥ 22: buddy install-gui, then buddy gui. Details in Getting started.

Use it from Claude Code (plugin, one command)

This repository is also a Claude Code plugin marketplace. It installs a skill that teaches Claude Code how to drive buddy correctly (headless one-shot, provider and model pinning, permission modes, the verify loop) and a read-only MCP server exposing Code Buddy's tools:

npm i -g @phuetz/code-buddy
claude plugin marketplace add phuetz/code-buddy
claude plugin install code-buddy@code-buddy
# optional, same marketplace: the context filter
claude plugin install lm-resizer@code-buddy

Codex users: cp -r .codex/skills/code-buddy ~/.codex/skills/. Remove with claude plugin uninstall code-buddy@code-buddy.

First run

A real task, start to finish. buddy loop plans, edits, runs your verification command, and stops only when that command exits 0 — the model's word is not the proof:

buddy loop "make the failing tests pass" --verify-cmd "npm test"

Other paths worth knowing on day one:

buddy try                             # 60-second demo: writes FizzBuzz + a test, runs it, verifies
buddy -p "explain the entry point"    # one-shot, headless — good for scripts and CI
buddy research "map this repository"  # parallel research workers
buddy cost --latency                  # measured per-model TTFT/TTFM, read-only

Parallel sub-agents and self-improvement

In a session, /batch <goal> splits independent work across multiplexed sub-agents; each unit is a real bounded agent, not a bare completion. CODEBUDDY_BATCH_CONCURRENCY caps how many run at once (default 1).

buddy improve status reports the local self-improvement state. buddy improve cycle|tools|skills is propose-only by default; to keep an empirically validated result you must opt in with CODEBUDDY_SELF_IMPROVE=true and pass --apply. Without the variable, --apply refuses and names it.

Memory and learning

Code Buddy keeps project/user memory, retrieves relevant lessons and can propose review-gated lesson candidates after substantial sessions. Authored skills can be inspected, improved and consolidated; code evolution evaluates variants in isolated worktrees. These change external state and inference-time behavior, not model weights.

Start with buddy lessons candidate list, buddy lessons list, buddy improve status and buddy evolve list. Council's role-based cooperation and the ToT/MCTS engine are separate mechanisms with their own execution paths and budgets. Inspiration from Manus, Sakana DGM/ShinkaEvolve/Fugu and reasoning papers is not a reproduction claim or a measured productivity gain.

Read activation conditions, source evidence and limitations, or the French overview. A two-host fleet recipe has combined a Windows RPC review, a Linux code correction and an independent five-case oracle passing on both hosts. The pilot explicitly relayed messages and files; this was not a Council run.

Opt-in

Nothing below is needed to chat with a local model. Defaults stay off.

Switch	What it turns on
CODEBUDDY_PROVIDER=ollama	Force the local Ollama path (no API key).
CODEBUDDY_MAX_CONTEXT	Override the context window for every consumer, including the Ollama server itself.
CODEBUDDY_SELF_IMPROVE=true	Enable the learned-layer proposal path. true stays propose-only; keeping validated changes needs explicit application authorization. The separate buddy evolve path can edit code in isolated worktrees. See contracts.
CODEBUDDY_SHADOW_WORKSPACE	Validate proposed writes in a ghost worktree before touching your files.
CODEBUDDY_TIMELINE	Per-turn timeline; buddy replay inspects, restores or forks a session.
CODEBUDDY_INTENTS	Falsifiable versioned specs, so "done" stays re-provable later.
CODEBUDDY_CONTEXT_ZOOM	Compaction becomes recoverable — the agent can re-expand a summarised segment.
CODEBUDDY_WORKSPACE	Read-only search and read across several repositories.
CODEBUDDY_SELF_BENCH	Track capability over time and flag regressions.
CODEBUDDY_CKG_SYNC	Pull-only knowledge-graph sync between fleet peers (fail-closed on both sides).
CODEBUDDY_COLLECTIVE_MEMORY	Inject the shared cross-agent knowledge graph into context.
CODEBUDDY_DIFF_REVIEW	Review every proposed diff before it is applied; an unreviewable diff is rejected, not applied.
CODEBUDDY_PEER_TOOL_WORKSPACE_ROOT	Required for remote read-only tools between peers. Unset ⇒ every peer.tool.invoke fails closed.
CODEBUDDY_SENSORY=true	Perception and companion wiring on buddy server.
CODEBUDDY_SENSORY_ERRORWATCH	Offer help when an error appears on screen — debounced, capped, never acts on its own.
CODEBUDDY_TTS_VOICE	Spoken replies. Unset ⇒ the agent may hear, but stays silent.
CODEBUDDY_INCLUDE_INTEROP_CONTEXT	Also load interoperability context files (CLAUDE.md, GEMINI.md, CONTEXT.md, INSTRUCTIONS.md) into the system prompt.
JWT_SECRET	Required by the HTTP server in production.
buddy --yolo or /yolo on	Full autonomy with guardrails. Setting YOLO_MODE=true alone only warns; it does not arm it.

Signed skill exchange, generative widgets, council-learned routing and kernel sandboxing have their own gates, listed in docs/cb2/README.md and Security.

Not ready

Honest limits for a first-time visitor:

• The npm release can lag this tree. Releases use GitHub Actions trusted publication. Check buddy --version, the npm dist-tag and the corresponding Git tag when identifying a build.
• CI gates all three operating systems. Linux, macOS and Windows run Node.js 20 and 22 jobs. A local pass or an earlier platform recipe does not replace the candidate’s CI results.
• Node ≥ 20 is the real floor, for the CLI and for the test toolchain alike (engines says so since 2.0.0).
• Cowork is a separate install (Node.js ≥ 22, buddy install-gui), not part of the three commands above.
• Film production needs ffmpeg; without a local voice binary, scenes stay silent rather than getting a fake voice-over.
• buddy loop needs a model that really calls tools. A very small model can stall or give up without ever turning the test suite green.
• Fleet is two processes and a JWT, not one flag. Remote tools expose nothing until the workspace root is set.
• Voice and robot paths need extra local binaries (speech-to-text, text-to-speech, optionally a camera). They do not come from npm install.
• better-sqlite3 is native. It is optional and degrades cleanly, but Cowork rebuilds it against Electron headers.

Test suite

38 088 tests in 2 115 files at 788f0ef23 (measured 2026-09-10 with npm test; 26 failures on that run were environment-only: a running local server, dist/ not built, 20 s timeouts under load). npm test -- tests/path/to/file.test.ts to run a slice.

Part of a toolchain

Code Buddy is the agent. Two sibling tools carry the context work around it: lm-resizer filters noisy command output before it reaches the model (Rust, Apache-2.0, npm i @phuetz/lm-resizer), and Code Explorer pre-indexes a repository into a queryable knowledge graph served over MCP (available as a service on private codebases — agile-up.com). Understand, compress, act.

License

Business Source License 1.1 — see LICENSE. Self-host and personal / non-commercial use are free; providing Code Buddy as a commercial service to third parties is not permitted. Converts to Apache 2.0 on 2030-08-31. Bundled Python skills stay MIT (see their SKILL.md).

Documentation

• Getting started — first run, headless mode, sessions.
• Release notes 2.1.0 — current changes and integration limits.
• Release notes 2.0.0 — previous major release.
• Install — published npm, Docker/VPS, the one-command installer.
• Commands · Features · Security
• Cowork Desktop · Fleet · Code Buddy 2 features
• Honest comparison — where other agents are still ahead.

Report a bug · Discuss · Star on GitHub