<div align="center">

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.

<p> <a href="https://www.npmjs.com/package/@phuetz/code-buddy"><img src="https://img.shields.io/npm/v/@phuetz/code-buddy.svg?style=flat-square&color=ff6b6b&label=version" alt="npm version"/></a> <a href="https://github.com/phuetz/code-buddy/actions/workflows/ci.yml?query=branch%3Amain"><img src="https://github.com/phuetz/code-buddy/actions/workflows/ci.yml/badge.svg?branch=main" alt="CI on main"/></a> <a href="LICENSE"><img src="https://img.shields.io/badge/license-BSL_1.1-feca57.svg?style=flat-square" alt="License: Business Source License 1.1"/></a> </p>

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

<p> <a href="docs/qa/code-buddy-studio/cowork-demo-moneyshot.mp4"><img src="docs/qa/code-buddy-studio/cowork-demo-moneyshot.gif" alt="A local model reasons, then uses a tool to create a real file — no cloud API bill" width="760"/></a> <br/> _{A local model reasons on screen, then uses a tool to create a real file. No cloud API bill.} </p> <p> <a href="docs/assets/infographic-code-buddy-2.webp"><img src="docs/assets/infographic-code-buddy-2.webp" width="900" alt="Code Buddy 2 architecture: you, multi-channel interfaces (terminal, Cowork, PWA, chat, voice, App Studio), the agentic runtime (council, fleet, memory, shadow workspace, evolve, knowledge graph), 220+ tools, 64 providers, and the autonomous engineering loop"/></a> <br/> _{The big picture: interfaces, the agentic runtime, tools and providers, and the loop that turns an idea into an improvement.} </p> </div>

---

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.

<p align="center"> <img src="buddy-sense/docs/architecture.svg" alt="Sense modules feed a thalamus that coalesces events and broadcasts them to a WebSocket bridge" width="720"/> </p>

---

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

<p align="center"> <img src="docs/assets/showcase-try.gif" alt="buddy try — the agent writes FizzBuzz and a test, runs it, independently verifies" width="760"/> </p>

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 `