<div align="center"> <img src="https://img.shields.io/badge/🤖-Code_Buddy-blueviolet?style=for-the-badge&labelColor=1a1a2e" alt="Code Buddy"/>

Code Buddy

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

<p align="center"> <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://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-feca57.svg?style=flat-square" alt="License: MIT"/></a> <a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-%3E%3D18.0.0-54a0ff?style=flat-square&logo=node.js" alt="Node Version"/></a> <a href="https://www.typescriptlang.org/"><img src="https://img.shields.io/badge/TypeScript-5.3-5f27cd?style=flat-square&logo=typescript" alt="TypeScript"/></a> <a href="https://deepwiki.com/phuetz/code-buddy/"><img src="https://deepwiki.com/badge.svg" alt="Ask DeepWiki"/></a> </p> <p align="center"> <a href="https://github.com/phuetz/code-buddy/stargazers"><img src="https://img.shields.io/github/stars/phuetz/code-buddy?style=flat-square&logo=github&color=feca57&label=Star" alt="GitHub stars"/></a> <img src="https://img.shields.io/badge/Tests-27K%2B-00d26a?style=flat-square&logo=jest" alt="Tests"/> <img src="https://img.shields.io/badge/v1.6.0-GA-blueviolet?style=flat-square" alt="Version 1.6.0 GA"/> </p> <br/>

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.

<p align="center"> <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 creates a file — for ~$0.0001" width="760"/></a> <br/> _{A <b>local</b> model reasons, then uses a tool to create a real file — <code>~$0.0001</code>, no cloud. <a href="cowork/readme.md#demo">More demos →</a>} </p>

• 🆓 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).

<br/>

Live site ↗ · Proof ✅ · Quick Start · In action · What it does · FAQ · Docs · Contributing

</div>

---

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:

<p align="center"> <img src="docs/assets/coding-demo.gif" alt="Code Buddy writes fizzbuzz.mjs and a test on Grok, runs it, and the test passes — $0, no API key" width="760"/> </p>

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:

<table> <tr> <td width="50%" align="center"> <a href="docs/qa/code-buddy-studio/cowork-demo-chat.mp4"><img src="docs/qa/code-buddy-studio/cowork-demo-chat.gif" alt="Local reasoning chat" width="430"/></a><br/> _{<b>Reasoning chat</b> — thinks step-by-step, then answers · local · <code>~$0.0001</code>} </td> <td width="50%" align="center"> <a href="docs/qa/code-buddy-studio/cowork-demo-task.mp4"><img src="docs/qa/code-buddy-studio/cowork-demo-task.gif" alt="Agent creates a file" width="430"/></a><br/> _{<b>Real task</b> — reasons, <b>uses the file tool</b>, confirms the artifact · local · <code>~$0.0001</code>} </td> </tr> </table>

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.

<p align="center"> <img src="docs/screenshots/chatgpt-oauth-login.png" alt="ChatGPT OAuth login flow" width="820"/> </p>

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

<p align="center"> <img src="docs/assets/login-demo.gif" alt="After buddy login xai, Grok writes a haiku with no API key, $0 marginal" width="760"/> </p>

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:

<p align="center"> <img src="docs/screenshots/self-audit-bug-1.png" alt="Self-audit bug found" width="820"/> </p>

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

<table> <tr> <td width="33%" align="center" valign="top"> <img src="docs/screenshots/telegram-companion-chat.jpg" alt="Telegram chat: instant greeting, the time, and tomorrow's live weather in Paris via web search" width="250"/><br/> _{<b>Chat + live tools, on demand</b><br/>"Bonjour" answers instantly; <i>"what time is it?"</i> and <i>"tomorrow's weather in Paris?"</i> pull the time and <b><code>web_search</code></b> tools — only when actually asked.} </td> <td width="33%" align="center" valign="top"> <img src="docs/screenshots/telegram-companion-selfcode.jpg" alt="Telegram chat: the agent confirms it can read and inspect its own source code via view_file" width="250"/><br/> _{<b>Reads its own code</b><br/>Confirms it can inspect its own source (or any accessible file) via <code>view_file</code> — then introduces its recursive self-improvement →} </td> <td width="33%" align="center" valign="top"> <img src="docs/screenshots/telegram-companion-recursive.jpg" alt="Telegram chat: the agent explains its recursive self-improvement — Manus-inspired lessons in RULE / PATTERN / CONTEXT categories, stored in .codebuddy/lessons.md" width="250"/><br/> _{<b>Improves itself across sessions</b><br/>The <code>lessons_*</code> loop (Manus-inspired): after each fix or success it extracts <b>RULE / PATTERN / CONTEXT</b> lessons, persisted to <code>.codebuddy/lessons.md</code> (project + global). <i>Accurate — matches its real source.</i>} </td> </tr> </table>

🎙️ 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 p