@phuetz/code-buddy 1.1.0 → 1.3.0

package/README.md

@@ -4,7 +4,7 @@
 
 # Code Buddy
 
-### Your AI-Powered Development Tool & Personal Assistant
+### 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>
@@ -15,15 +15,14 @@
 </p>
 
 <p align="center">
-  <img src="https://img.shields.io/badge/Tests-30K%2B-00d26a?style=flat-square&logo=jest" alt="Tests"/>
-  <img src="https://img.shields.io/badge/Build-passing-00d26a?style=flat-square" alt="Build"/>
+  <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.3.0-GA-blueviolet?style=flat-square" alt="Version 1.3.0 GA"/>
 </p>
 
 <br/>
 
-### The open-source AI coding agent that runs **free, on your own machine.**
-
-Code, commands, web, voice, and vision — from your terminal, a desktop app, your phone, or a 24/7 autonomous service. Use **local Ollama models at `$0`**, or bring any of **15 providers**. No lock-in.
+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>
@@ -31,21 +30,24 @@ Code, commands, web, voice, and vision — from your terminal, a desktop app, yo
   <sub>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></sub>
 </p>
 
-- 🆓 **Free & local-first** — runs entirely on **local Ollama (`$0`)**, or any of **15 providers** (Claude, GPT, Grok, Gemini, …) with auto-failover. Or log in with **ChatGPT Plus/Pro** for a flat-fee brain — no API metering.
-- 🧠 **Reasoning you can watch** — local models think step-by-step on screen, then act — see the [live captures](cowork/readme.md#demo).
-- 🖥️ **Runs everywhere** — terminal TUI, the **Cowork desktop app**, an HTTP/WebSocket server, your phone, or a 24/7 background service — all on the same core engine.
-- 🤝 **Multi-AI Fleet** — multiple peers observe each other live and call each other's models & read-only tools (`peer.chat` / `peer.tool.invoke`) across your network.
-- 🤖 **Autonomous** — `buddy autonomy install` runs a self-driving service that claims & executes tasks **free-first** on local models, 24/7.
-- 🛠️ **~110 tools, skills & MCP** — edit, shell, web search, browser, PDFs/Office, a skills marketplace, and MCP connectors to extend it.
-- 👁️ **Personal companion** — bidirectional voice, opt-in camera/presence (MediaPipe), persistent memory, and 20+ messaging channels.
+- 🆓 **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](cowork/readme.md#demo).
+- 🛠️ **~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 ✅](docs/proof.md).** 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/>
 
-[Quick Start](#quick-start) |
-[Cowork + Companion](#cowork-desktop--buddy-companion) |
-[Features](#features) |
-[FAQ](docs/faq.md) |
-[Documentation](#documentation) |
+[Live site ↗](https://phuetz.github.io/code-buddy/) ·
+[Proof ✅](docs/proof.md) ·
+[Quick Start](#quick-start) ·
+[In action](#in-action) ·
+[Features](#features) ·
+[FAQ](docs/faq.md) ·
+[Docs](#documentation) ·
 [Contributing](#contributing)
 
 </div>
@@ -54,12 +56,18 @@ Code, commands, web, voice, and vision — from your terminal, a desktop app, yo
 
 ## What is Code Buddy?
 
-Code Buddy is an open-source multi-provider AI coding agent with a terminal UI, HTTP/WebSocket server, and Cowork desktop app. It supports **15 LLM providers** with automatic failover and per-provider circuit breakers. It works as both a **development tool** (reads files, writes code, runs commands, creates PRs, plans complex tasks) and a **personal companion** (bidirectional voice conversation, durable memory, opt-in camera perception, screen/presence context, push notifications via 20+ messaging channels, and 24/7 background operation). With `buddy login`, a ChatGPT Plus / Pro subscription can become the flat-fee brain of the system without API-key metering.
+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
 
+**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>
@@ -75,115 +83,199 @@ Code Buddy is an open-source multi-provider AI coding agent with a terminal UI,
   </tr>
 </table>
 
-More desktop demos (Fleet, Autonomy, Companion, …): [`cowork/readme.md`](cowork/readme.md#demo).
-
----
-
-**ChatGPT Pro / Plus subscription login** — `buddy login`, sign in once with your ChatGPT account, then chat with `gpt-5.5` directly from the terminal. No API key, cost reported as `$0.0000` (flat-fee plan).
+**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).
 
 <p align="center">
-  <img src="docs/screenshots/chatgpt-oauth-login.png" alt="ChatGPT OAuth login flow" width="900"/>
+  <img src="docs/screenshots/chatgpt-oauth-login.png" alt="ChatGPT OAuth login flow" width="820"/>
 </p>
 
-**Interactive TUI + tool calling.** The agent reads project context, calls tools in parallel (`web_search` ×2 for the screenshot below), and streams the synthesised answer.
+**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/screenshots/tool-calling-parallel.png" alt="Tool calling parallel" width="900"/>
+  <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 `src/codebuddy/providers/provider-chatgpt-responses.ts`, identifies a stale-variable issue (mutated `body.model` not propagated), and proposes the exact fix:
+**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="900"/>
+  <img src="docs/screenshots/self-audit-bug-1.png" alt="Self-audit bug found" width="820"/>
 </p>
 
-More captures + walk-through: [`docs/screenshots/`](docs/screenshots/README.md).
+More desktop demos (Fleet, Autonomy, Companion, …) and captures: [`cowork/readme.md`](cowork/readme.md#demo) · [`docs/screenshots/`](docs/screenshots/README.md).
+
+---
+
+## 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](tests/agent/in-loop-recovery.real.test.ts), 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](docs/hermes-openclaw-parity.md) 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/`](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).
+
+<p align="center"><img src="buddy-sense/docs/architecture.svg" alt="buddy-sense nervous-system architecture: senses → thalamus → bridge → Code Buddy event bus" width="840"/></p>
+
+**Honestly experimental** — distinct from the GA core above: the default daemon emits the heartbeat (+ audio from a WAV file); the live camera/mic aren't wired into the daemon yet. `speech → STT → 'hearing' percept` **is** wired (faster-whisper), with a hook left for driving a full agent turn. What's real today: the pure detector cores + thalamus + bridge are unit-tested (`cargo test`, 20 tests, no hardware), and the loopback bridge → event bus → reaction path (incl. the speech transcription) is covered on the Code Buddy side.
+
+```bash
+cd buddy-sense && cargo test     # 20 tests, no hardware
+./buddy-sense/demo.sh            # headless end-to-end: heartbeat + audio VAD → Code Buddy
+```
+
+Design, the five sense modules, the opt-in features, and the diagrams: [`buddy-sense/README.md`](buddy-sense/README.md).
 
 ---
 
 ## Quick Start
 
 ```bash
-# Install — from source (recommended during the 1.0 release-candidate phase: gets the latest)
+# 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
+```
 
-# Or install the published release from npm
-# ⚠️ during rc, the npm release can lag the source — prefer from-source for the newest features
-npm install -g @phuetz/code-buddy
+> **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 — bring your own API key
-export GROK_API_KEY=your_api_key   # or GEMINI_API_KEY / OPENAI_API_KEY / ANTHROPIC_API_KEY
+```bash
+# 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 needed)
-buddy login                         # opens browser for OAuth → tokens persisted
-buddy whoami                        # ✅ connected · your.email@example.com · Plan: pro
-buddy                               # auto-routes to gpt-5.5 via the Codex backend, cost $0.0000
+# Option B — log in with your ChatGPT Plus / Pro subscription (no API key)
+buddy login        # opens browser for OAuth → tokens persisted
+buddy whoami       # ✅ connected · you@example.com · 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
 
-# Or with a specific task
-buddy --prompt "analyze the codebase structure"
+# 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
+```
 
-# Full autonomy
-buddy --yolo
+```bash
+buddy --prompt "analyze the codebase structure"   # one-shot task
+buddy --yolo                                       # full autonomy
 ```
 
-See [Getting Started](docs/getting-started.md) for installation options, headless mode, session management, and typical workflows. The ChatGPT Codex OAuth flow is documented with screenshots in [`docs/screenshots/`](docs/screenshots/README.md). The desktop cockpit has a public overview in [Cowork Desktop](docs/cowork.md).
+**Use several logins at once, or fail over automatically across them:**
+
+```bash
+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
+```
+
+<p align="center">
+  <img src="docs/assets/llm-demo.gif" alt="buddy llm lists your active LLMs, then auto-fails over from Grok to ChatGPT when the primary errors" width="760"/>
+  <br/>
+  <sub>Your logins at a glance — and automatic failover from one to the next when one has a problem, at <code>$0</code>. Real run, unedited.</sub>
+</p>
+
+<p align="center">
+  <img src="docs/assets/ensemble-demo.gif" alt="buddy llm ensemble asks ChatGPT, Ollama and Grok the same question, then synthesizes one answer" width="760"/>
+  <br/>
+  <sub><code>buddy llm ensemble</code> — every brain you're logged into answers, then it's synthesized into one. Real run, unedited.</sub>
+</p>
+
+See [Getting Started](docs/getting-started.md) for install options, headless mode, sessions, and typical workflows.
 
 ---
 
-## Cowork Desktop + Buddy Companion
+## 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 run against the same core agent as the CLI. The Code Buddy settings panel can probe the local backend, start it when needed, discover models, and route Cowork turns through the embedded engine or a configured server endpoint.
+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.
 
-```bash
-# First-time identity and flat-fee brain route
-buddy login
-buddy companion setup
-
-# Local backend for Cowork, Fleet, and OpenAI-compatible clients
-buddy server --port 3000
-
-# Launch the desktop app from an installed build
-buddy gui
-# or
-buddy desktop
-
-# Source checkout dev loop
-npm install
-npm run build
-npm run dev:gui
-```
+<p align="center">
+  <a href="docs/qa/code-buddy-studio/showcase-2026-06-16/cowork-chat-stream.mp4"><img src="docs/qa/code-buddy-studio/showcase-2026-06-16/cowork-chat-stream.gif" alt="Real gpt-5.5 chat streaming in the Cowork desktop app for $0" width="760"/></a>
+  <br/>
+  <sub>Real <code>gpt-5.5</code> in the Cowork desktop app — the answer streams in, cost <code>$0.0000</code>. <a href="docs/qa/code-buddy-studio/showcase-2026-06-16/cowork-chat-stream.mp4">MP4 →</a></sub>
+</p>
 
-Buddy companion commands are available in both the CLI and Cowork panel:
+<p align="center">
+  <a href="docs/assets/cowork-chat-demo.mp4"><img src="docs/assets/cowork-chat-demo.gif" alt="A local reasoning model thinks through a haiku on screen in the Cowork desktop app, $0" width="760"/></a>
+  <br/>
+  <sub>…and fully local: a reasoning model (<code>qwen3.6:35b-a3b</code>) <b>thinks on screen</b>, then answers — no cloud, <code>$0</code>. <a href="docs/assets/cowork-chat-demo.mp4">MP4 →</a></sub>
+</p>
 
-```bash
-buddy companion status
-buddy companion self
-buddy companion evaluate
-buddy companion radar
-buddy companion impulses
-buddy companion missions sync
-buddy companion missions run-next
-buddy companion safety recent
-buddy companion camera status
-buddy companion camera snapshot
-buddy companion percepts recent
-```
+<p align="center">
+  <a href="docs/assets/cowork-panels-demo.mp4"><img src="docs/assets/cowork-panels-demo.gif" alt="The Cowork left rail opens the Autonomy dashboard, Memory and other panels as dock tabs" width="760"/></a>
+  <br/>
+  <sub>The left rail opens every panel as a dock tab — here the <b>Autonomy dashboard</b> (24/7 daemon, free-first model ladder, live subagents) and <b>Project Memory</b>. <a href="docs/assets/cowork-panels-demo.mp4">MP4 →</a></sub>
+</p>
+
+<table>
+  <tr>
+    <td width="50%" align="center"><img src="docs/assets/cowork-welcome.png" alt="Cowork desktop home with the expanded left menu and quick-action cards" width="430"/><br/><sub>Home — expanded menu, quick-action cards, gradient hero</sub></td>
+    <td width="50%" align="center"><img src="docs/assets/cowork-panel.png" alt="A launcher opens its panel as a tab — here the Autonomy dashboard" width="430"/><br/><sub>A launcher opens its panel as a tab — here the Autonomy dashboard (daemon, model ladder, subagents)</sub></td>
+  </tr>
+  <tr>
+    <td width="50%" align="center"><img src="docs/qa/code-buddy-studio/showcase-2026-06-16/03-fleet-autonomy.png" alt="Fleet and autonomy dashboard" width="430"/><br/><sub>Fleet dispatch · tool-permission posture · Hermes toolsets</sub></td>
+    <td width="50%" align="center"><img src="docs/qa/code-buddy-studio/showcase-2026-06-16/02-chat-dark-theme.png" alt="Cowork dark theme" width="430"/><br/><sub>Light &amp; dark themes</sub></td>
+  </tr>
+</table>
+
+**📄 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`:
+
+<p align="center">
+  <a href="docs/qa/code-buddy-studio/showcase-2026-06-16/cowork-office-skill.mp4"><img src="docs/qa/code-buddy-studio/showcase-2026-06-16/office-skill-steps.png" alt="The Cowork agent builds a styled Excel file via a multi-step skill at $0" width="820"/></a>
+  <br/>
+  <sub>Prompt → the <code>xlsx</code> skill runs <code>openpyxl</code> in visible steps → a verified <code>budget.xlsx</code> with a live <code>=SUM</code> formula and styling, <code>$0.0000</code>. <a href="docs/qa/code-buddy-studio/showcase-2026-06-16/cowork-office-skill.mp4">▶ Watch the run (MP4) →</a></sub>
+</p>
+
+**🐍 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`:
 
-The camera bridge is explicit and local: snapshots are opt-in, percepts are append-only under `.codebuddy/companion/`, and Cowork uses MediaPipe Tasks Vision for face, hand, finger-tip, and pose signals. Face enrollment/presence recognition lives in Cowork's presence bridge and uses the local MediaPipe/Buffalo_S pipeline.
+<p align="center">
+  <img src="docs/qa/code-buddy-studio/showcase-2026-06-16/swarm-real-team.png" alt="A swarm of coder/tester/reviewer agents completes a task at $0" width="760"/>
+  <br/>
+  <sub>Orchestrator plans → <code>coder</code> / <code>tester</code> / <code>reviewer</code> run in turn (live activity) → tester reports <code>4 tests · OK</code> → synthesized result, all on <code>gpt-5.5</code> for <code>$0.0000</code>.</sub>
+</p>
 
-For low-latency voice experiments, Cowork can route STT/TTS through a local Kyutai DSM / `moshi-server` endpoint while keeping faster-whisper and Piper as fallbacks:
+**🎯 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:
+
+<p align="center">
+  <img src="docs/qa/code-buddy-studio/showcase-2026-06-16/goal-mode-real-loop.png" alt="Goal mode autonomous loop with LLM judge verification at $0" width="760"/>
+  <br/>
+  <sub>Act → judge rejects turn 1/20 (<em>"not exactly one line"</em>) → agent self-corrects → <code>✓ Goal achieved</code>. Real <code>gpt-5.5</code> loop, <code>$0.0000</code>.</sub>
+</p>
 
 ```bash
-$env:COWORK_VOICE_PROVIDER='kyutai'
-$env:COWORK_KYUTAI_URL='ws://127.0.0.1:8080'
-npm run dev:gui
-```
+# 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
 
-Use Buddy companion's **Inspect voice** action to probe the active route, Kyutai STT/TTS websocket reachability, `ffmpeg` availability, and the Piper/faster-whisper fallback state from the Electron app.
+# Source dev loop
+npm install && npm run build && npm run dev:gui
+```
 
-From source, Cowork requires Node.js `>=22` in `cowork/`; the root CLI still supports Node.js `>=18`.
+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`](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](docs/cowork.md) · [Cowork Architecture](cowork/ARCHITECTURE.md).
 
 ---
 
@@ -192,34 +284,21 @@ From source, Cowork requires Node.js `>=22` in `cowork/`; the root CLI still sup
 | 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](docs/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](docs/tools-reference.md) |
-| **Commands** | 190+ slash commands, CLI subcommands (`/goal`, `/dev`, `/pr`, `/lint`, `/switch`, `/think`, `/batch`, `/watch`, `/conflicts`, `/vulns`, `/replace`) | [commands.md](docs/commands.md) |
-| **Cowork Desktop** | Electron cockpit, embedded Code Buddy engine, backend health/start controls, model settings, permission rules, visual workflows, traces, artifacts, MCP/skills/plugin management | [Cowork Desktop](docs/cowork.md), [cowork/readme.md](cowork/readme.md), [cowork/ARCHITECTURE.md](cowork/ARCHITECTURE.md) |
-| **Buddy Companion** | ChatGPT-backed identity, voice/TTS, proactive check-ins, self-evaluation, competitive radar, mission board, learned routines, safety ledger, local percept journal | [commands.md](docs/commands.md) |
-| **Vision & Presence** | Opt-in webcam snapshots, MediaPipe face/hand/pose/finger-tip analysis, local face enrollment, presence state for the agent | [cowork/ARCHITECTURE.md](cowork/ARCHITECTURE.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](docs/tools-reference.md) |
+| **Commands** | 190+ slash commands & CLI subcommands (`/goal`, `/dev`, `/pr`, `/lint`, `/switch`, `/think`, `/batch`, …) | [commands.md](docs/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](docs/cowork.md), [ARCHITECTURE.md](cowork/ARCHITECTURE.md) |
 | **Agents** | Multi-agent orchestration (5-tool API), 8 specialized agents, SWE agent, planning flow, A2A protocol, batch decomposition, agent teams | [agents.md](docs/agents.md) |
-| **Reasoning** | Tree-of-Thought + MCTS (4 depth levels), extended thinking, auto-escalation, `/think` command | [reasoning.md](docs/reasoning.md) |
-| **Security** | Guardian Agent (AI risk scoring), OS/Docker/OpenShell sandbox, SSRF guard, secrets vault, write policy, exec policy, loop detection, omission detection, output sanitizer | [security.md](docs/security.md) |
-| **Channels** | 20+ messaging channels (Telegram, Discord, Slack, WhatsApp, Signal, Teams, Matrix, IRC, and more), DM pairing, send policy | [channels.md](docs/channels.md) |
-| **Context Engine** | Smart compression, tool output masking, image pruning, transcript repair, pre-compaction flush, restorable compression, JIT context, importance-weighted window | [context-engine.md](docs/context-engine.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, claim TTL/lease, DAG task dependencies, workers→verifier→synthesizer swarm, free-first local→Tailscale→paid model tier, judge-gated goal loops (`/goal` Ralph loop, `buddy goal`, board goal-mode, peer-session goals) | [fleet-guide.md](docs/fleet-guide.md) |
-| **Infrastructure** | HTTP server (OpenAI-compatible), WebSocket gateway, daemon mode, cron, device nodes, canvas/A2UI, 6 cloud deploy configs, MCP, plugins | [infrastructure.md](docs/infrastructure.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](docs/fleet-guide.md) |
+| **Reasoning** | Tree-of-Thought + MCTS (4 depth levels), extended thinking, auto-escalation, `/think` | [reasoning.md](docs/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](docs/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](docs/security.md) |
+| **Context Engine** | Smart compression, tool-output masking, image pruning, transcript repair, pre-compaction flush, JIT context, importance-weighted window | [context-engine.md](docs/context-engine.md) |
+| **Channels** | 20+ messaging channels (Telegram, Discord, Slack, WhatsApp, Signal, Teams, Matrix, …), DM pairing, send policy | [channels.md](docs/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](docs/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](docs/context-engine.md) |
+| **Infrastructure** | HTTP server (OpenAI-compatible), WebSocket gateway, daemon, cron, device nodes, canvas/A2UI, cloud deploy configs, MCP, plugins | [infrastructure.md](docs/infrastructure.md) |
 | **Configuration** | Env vars, TOML config with profiles, model-aware limits, per-agent params, i18n (6 locales), personas | [configuration.md](docs/configuration.md) |
-| **Development** | TypeScript strict, Vitest (27,334 tests), ESM, middleware pipeline, facade architecture | [development.md](docs/development.md) |
-
-### Additional Capabilities
-
-- **Voice**: 7 TTS providers, wake word detection, voice-to-code pipeline, hands-free companion conversation
-- **Companion Loop**: readiness checks, self-state snapshots, self-evaluation, competitive radar, impulses, missions, routines, and safety review
-- **Vision**: local camera snapshots, MediaPipe face/hand/pose/finger-tip percepts, face enrollment, and presence state for context-aware collaboration
-- **Memory**: Persistent + semantic + prospective + decision + coding style memory, ICM cross-session memory
-- **Knowledge**: Knowledge base injection, 40 bundled skills, self-authoring skills at runtime
-- **Goal Loops (Ralph loop)**: `/goal <text>` + `/subgoal` — a judge model re-checks completion after every turn and auto-continues until done (turn budget, pause/resume, fail-open judge); also headless (`buddy goal`), on fleet board tasks (`--goal-mode`, blocks for human review when the budget is spent), and on peer sessions (`peer.chat-session.goal`)
-- **Git Workflow**: Auto-commit (Aider-style), `/pr` creation, merge conflict resolver, ghost snapshots
-- **Code Intelligence**: LSP rename/refactor, auto-import, bug finder (25+ patterns, 6 langs), OpenAPI generator, log analyzer
-- **IDE Integration**: VS Code extension (diff view, inline edit, model switch), JetBrains plugin, LSP server
-- **Inline Context**: `@web`, `@git`, `@terminal` mentions for contextual references
-- **Workflows**: Lobster typed DAG engine with approval gates, pause/resume tokens
+| **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](docs/development.md) |
 
 ---
 
@@ -227,47 +306,18 @@ From source, Cowork requires Node.js `>=22` in `cowork/`; the root CLI still sup
 
 | Document | Description |
 |:---------|:------------|
-| [Getting Started](docs/getting-started.md) | Prerequisites, install, first run, headless mode, session management |
-| [Application Validation Guide](docs/application-validation-guide.md) | Full-app validation matrix with safe commands, evidence, and screenshot rules |
+| [Getting Started](docs/getting-started.md) | Prerequisites, install, first run, headless mode, sessions |
 | [Providers](docs/providers.md) | All 15 providers, connection profiles, model pairs, circuit breaker |
-| [Tools Reference](docs/tools-reference.md) | Tool categories, RAG selection, edit matching, apply_patch, streaming |
+| [Tools Reference](docs/tools-reference.md) | Tool categories, RAG selection, edit matching, `apply_patch`, streaming |
 | [Commands](docs/commands.md) | All slash commands, CLI subcommands, companion commands, global flags |
-| [Cowork Desktop](docs/cowork.md) | GitHub-visible overview, ChatGPT `gpt-5.5` route, real validation commands, screenshot privacy policy |
-| [Autonomous Coding + Cowork Progress](docs/autonomous-coding-cowork-progress.md) | End-to-end autonomous task execution, RunStore artifacts, and Cowork progress tracking |
-| [Cowork README](cowork/readme.md) | Desktop installation, features, source build, sandbox modes |
-| [Cowork Architecture](cowork/ARCHITECTURE.md) | Electron contexts, bridges, embedded engine, persistence, runner model |
-| [Agents](docs/agents.md) | Multi-agent orchestration, roles, SWE agent, planning flow, A2A |
-| [Reasoning](docs/reasoning.md) | Extended thinking, Tree-of-Thought, MCTS, /think command |
-| [Security](docs/security.md) | Permission modes, Guardian Agent, sandboxing, SSRF, secrets vault |
-| [Channels](docs/channels.md) | 20+ messaging channels, DM pairing, send policy |
-| [Context Engine](docs/context-engine.md) | Compression, tool output masking, JIT context, pre-compaction flush |
-| [Infrastructure](docs/infrastructure.md) | HTTP server, WebSocket gateway, daemon, cron, deploy, plugins |
-| [Deployment](docs/deployment.md) | Production deployment — systemd, Docker, Kubernetes, reverse proxy, env vars, upgrades |
-| [PdfCommander MCP Integration](docs/mcp-pdfcommander-integration.md) | Register the PdfCommander headless MCP server in `mcp.json`, verify with `buddy mcp test`, drive PDF ops from the agent |
-| [Fleet Guide](docs/fleet-guide.md) | **Multi-AI hub** — `/fleet listen` + `/fleet send peer.chat`, env-driven multi-provider auto-detect, Tailscale lab examples, autonomous fleet protocol |
-| [Hermes / OpenClaw Parity](docs/hermes-openclaw-parity.md) | Where Code Buddy stands vs Hermes Agent & OpenClaw — shipped capabilities, externally-gated features, and the one open code gap |
-| [Configuration](docs/configuration.md) | Environment variables, TOML config, project settings, model limits |
-| [Development](docs/development.md) | Build, test, architecture, coding conventions, adding tools |
-
----
-
-## Validation Snapshot
-
-Latest local verification for the Cowork + Buddy companion loop (2026-05-24):
-
-```bash
-npm run typecheck
-cd cowork && npm run typecheck
-cd cowork && npm run build:e2e
-cd cowork && npx vitest run tests/kyutai-bridge.test.ts tests/voice-bridge.test.ts tests/tts-bridge.test.ts
-cd cowork && npx playwright test e2e/cowork-smoke.spec.ts --reporter=line --workers=1
-cd cowork && npx playwright test e2e/companion-panel.spec.ts --reporter=line --workers=1
-cd cowork && npx playwright test e2e/recent-features-smoke.spec.ts e2e/companion-panel.spec.ts --workers=1
-cd cowork && npx playwright test e2e/codebuddy-settings.spec.ts e2e/recent-features-smoke.spec.ts e2e/companion-panel.spec.ts e2e/companion-live.spec.ts --reporter=line --workers=1
-cd cowork && npx vitest run
-```
-
-Result: root and Cowork typechecks passed, Vite E2E build passed with existing chunk/dynamic-import warnings, Kyutai/voice bridge unit tests passed (`31` tests), focused companion panel Playwright passed (`1` test), recent-features IPC smoke passed (`9` tests), Cowork smoke passed (`29` tests), focused companion/settings/recent-feature Playwright suite passed (`11` passed, `1` live hardware test skipped unless `COWORK_LIVE_COMPANION=1`), and Cowork Vitest passed (`205` files, `1318` tests).
+| [Cowork Desktop](docs/cowork.md) · [Architecture](cowork/ARCHITECTURE.md) · [README](cowork/readme.md) | Desktop overview, install, source build, sandbox modes, internals |
+| [Agents](docs/agents.md) · [Reasoning](docs/reasoning.md) | Orchestration, SWE agent, planning flow, A2A; thinking, ToT, MCTS |
+| [Fleet Guide](docs/fleet-guide.md) | Multi-AI hub, peer-rpc methods, env-driven auto-detect, Tailscale labs |
+| [Security](docs/security.md) · [Context Engine](docs/context-engine.md) | Permission modes, Guardian, sandboxing, secrets; compression, JIT context |
+| [Channels](docs/channels.md) · [Configuration](docs/configuration.md) | 20+ channels, DM pairing; env vars, TOML, model limits |
+| [Infrastructure](docs/infrastructure.md) · [Deployment](docs/deployment.md) | Server, gateway, daemon, cron; systemd, Docker, Kubernetes, upgrades |
+| [Development](docs/development.md) | Build, test, architecture, conventions, adding tools |
+| [Hermes / OpenClaw Parity](docs/hermes-openclaw-parity.md) | Where Code Buddy stands vs Hermes Agent & OpenClaw |
 
 ---
 
@@ -275,29 +325,27 @@ Result: root and Cowork typechecks passed, Vite E2E build passed with existing c
 
 ```bash
 git clone https://github.com/phuetz/code-buddy.git
-cd code-buddy
-npm install
-npm run dev          # Development mode
-npm test             # Run all tests
-npm run validate     # Lint + typecheck + test (run before committing)
+cd code-buddy && npm install
+npm run dev          # development mode
+npm run validate     # lint + typecheck + test (run before committing) — 27K+ Vitest tests
 ```
 
-See [Development](docs/development.md) for architecture details and coding conventions.
+See [Development](docs/development.md) for architecture and coding conventions, and [CONTRIBUTING.md](CONTRIBUTING.md) for the workflow.
 
 ---
 
 ## License
 
-MIT License - see [LICENSE](LICENSE) for details.
+MIT — see [LICENSE](LICENSE).
 
 ---
 
 <div align="center">
 
-**[Report Bug](https://github.com/phuetz/code-buddy/issues)** |
-**[Request Feature](https://github.com/phuetz/code-buddy/discussions)** |
-**[Star on GitHub](https://github.com/phuetz/code-buddy)**
+**[Report Bug](https://github.com/phuetz/code-buddy/issues)** ·
+**[Request Feature](https://github.com/phuetz/code-buddy/discussions)** ·
+**[Star on GitHub ⭐](https://github.com/phuetz/code-buddy)**
 
-<sub>Multi-AI: Grok | Claude | ChatGPT | Gemini | LM Studio | Ollama | AWS Bedrock | Azure | Groq | Together | Fireworks | OpenRouter | vLLM | Copilot | Mistral</sub>
+<sub>Multi-AI: Grok · Claude · ChatGPT · Gemini · LM Studio · Ollama · AWS Bedrock · Azure · Groq · Together · Fireworks · OpenRouter · vLLM · Copilot · Mistral</sub>
 
 </div>