huddle-cli 0.0.0-stage → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,31 @@
+# Changelog
+
+## 0.1.1 — 2026-10-16
+
+The agents now work *together*, not just side by side. Verified live with real Claude, Codex and Cursor building an app from an empty repo (capstone: 29/29 checks, rounds 4 and 6).
+
+### Collaboration
+- **Design council v2.** Every agent proposes a design, then reviews the others: what it *adopts* from each teammate and what *flaw* it sees. The agent whose ideas teammates adopted most writes the plan (not always Claude). Everyone else ratifies it or objects; objections are taken before anyone codes.
+- **Shared contract.** The plan comes with `HUDDLE_CONTRACT.md` — file owners, function names, data fields, exact error messages — committed before work starts. `huddle_amend_contract` changes it and tells every working agent.
+- **The goal reaches every agent verbatim** and wins over the plan and the contract; a check makes sure every exact string in the goal lands in some task.
+- **Mail mid-task.** Messages arrive inside every Huddle tool result, and Claude also gets them after *every* tool call (a hook). Agents check in at ~25/50/75%.
+- **Buddy checks.** At ~50% (or after 2 minutes without a progress report) another agent looks at the work in progress and sends notes. Notes must be answered — fixed, or "won't fix, because…" — before the task can finish.
+- **Radar.** Every 20s Huddle compares the agents' unfinished work and warns both sides about overlapping edits or name mismatches (`getItems` vs `listItems`).
+- **Pairing.** A free agent takes a separable part of a task that's behind (or writes its tests) unless the author says no.
+- **QA checks the goal item by item**, and a suspiciously quick "clean" round gets a second opinion from another agent.
+- **Reviews say what they verified**; a bare APPROVE is marked shallow.
+
+### New
+- `huddle setup` — checks Node and git, installs the agents you pick, walks you through each sign-in.
+- `huddle agents use claude,codex` / `huddle agents skip cursor` — choose your agents, even ones that are installed.
+- **The shared screen.** Paste a long log or doc and it becomes one item (`ctx-1`) instead of one command per line; `add <file|folder>` or drag a file in; screenshots and PDFs too. Agents read, search and pin notes on it. Works in attach mode: `huddle add <file>`, `pbpaste | huddle add -`, `huddle ctx`. Secrets are caught before anything goes to an agent.
+- `huddle join "<goal>" --with <file>` and piped input (`cat log | huddle join "fix this"`).
+- **Lessons.** Huddle remembers what went wrong in earlier runs and tells the next run's agents (`huddle lessons`).
+- `npm run evolve` — Huddle runs on its own repo to fix its weaknesses, kept only if the capstone score holds.
+- The planner (brain) defaults to Claude Opus.
+
+### Better
+- Live output in clear phases (COUNCIL → PLAN → BUILD → QA → RESULT), one status line per agent, a TEAMWORK summary; redesigned `huddle view` and `huddle story --html`.
+- Windows: PowerShell install commands, agent CLIs launched correctly, Windows paths, process cleanup, no duplicated rows in `huddle doctor`. `HUDDLE_ASCII=1` for old consoles.
+- Fixed: lost reviewer answers and agent output when Huddle was busy; a log-stream crash on Linux; flaky tests.
+- `QUICKSTART.md`: install, first run, teammates, on one page.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Preet37
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/QUICKSTART.md

@@ -0,0 +1,102 @@
+# Huddle quickstart
+
+Two commands on any computer, then you type what you want built.
+
+## 1. Install (once per computer)
+
+You need **Node.js 20+** and **git**. Check with `node -v` and `git --version`.
+Missing one? Node: [nodejs.org](https://nodejs.org) (or `nvm install 22`). git on macOS: `xcode-select --install`. On Windows, see [below](#windows).
+
+```bash
+npm install -g huddle-cli && huddle setup
+```
+
+`huddle setup` checks Node and git, asks which agents you want (say no to any you don't use — e.g. skip Cursor), installs the missing ones with the right command for your computer, then opens each one's own sign-in, one at a time. You need at least one agent. `huddle setup --yes` skips the questions (sign-ins still need you: they open a browser).
+
+By hand instead:
+
+| Agent | Install (macOS / Linux) | Install (Windows PowerShell) | Sign in (once) |
+|---|---|---|---|
+| Claude Code | `curl -fsSL https://claude.ai/install.sh \| bash` | `irm https://claude.ai/install.ps1 \| iex` | `claude auth login` |
+| Codex | `npm install -g @openai/codex` | same | `codex login` |
+| Cursor | `curl https://cursor.com/install -fsS \| bash` | `irm 'https://cursor.com/install?win32=true' \| iex` | `cursor-agent login` |
+| Antigravity | `curl -fsSL https://antigravity.google/cli/install.sh \| bash` | `irm https://antigravity.google/cli/install.ps1 \| iex` | run `agy`, sign in, then ctrl-c twice |
+
+Each agent uses its own account; Huddle never sees a password or key. Changed your mind? `huddle agents skip cursor` keeps Cursor out of every run (even when it's installed and signed in); `huddle agents use cursor` brings it back; `huddle agents` shows who's ready and who's skipped.
+
+### Windows
+
+Huddle runs natively in PowerShell (Windows Terminal or VS Code's terminal):
+
+```powershell
+winget install OpenJS.NodeJS.LTS                  # if `node -v` fails (then open a new terminal)
+winget install --id Git.Git -e --source winget    # if `git --version` fails
+npm install -g huddle-cli
+huddle setup
+```
+
+`huddle setup` uses the PowerShell installers above. If PowerShell says "running scripts is disabled", run `Set-ExecutionPolicy -Scope CurrentUser RemoteSigned` once.
+**If anything fails on Windows, WSL is the fallback:** `wsl --install`, restart, open "Ubuntu", then follow the macOS / Linux steps inside it (install Node there too, and keep your repo inside the Linux file system, e.g. `~/code`).
+
+## 2. Use it
+
+```bash
+cd my-project          # any git repo (not one? huddle offers to set it up)
+huddle
+```
+
+At the `huddle ›` prompt, type the goal, e.g. `build a REST API for todos with tests`.
+Huddle plans it, every agent works at once in its own copy of the repo, and work merges only when tests pass.
+
+One-shot instead of the prompt: `huddle join "build a REST API for todos with tests"`.
+
+**Pasting and files.** Paste anything long (a stack trace, a spec, code) at the prompt: it goes on the *shared screen* as one item, every agent can read it, and what you type next is the goal. Drag a file or screenshot into the terminal, or type `add notes.md` / `add src/` / `add *.png`. `ctx` shows what's on the screen; `ctx rm ctx-2` takes one off. Prompts only carry a short index, so a huge paste doesn't get copied to every agent. Keys and tokens in a paste are caught first: Huddle asks before showing them to agents, and redacts them unless you say no.
+One-shot: `huddle join "fix this" --with error.log --with screenshot.png`, or `cat error.log | huddle join "fix this"`.
+
+**While it runs** (second terminal, same folder):
+
+```bash
+huddle view            # live: who's doing what, messages, merges
+```
+
+**After it runs:**
+
+```bash
+huddle story                   # replay: plan, messages between agents, reviews, merges
+huddle story --html story.html # the same as a page you can open or share
+```
+
+## 3. Working with teammates (e.g. a hackathon)
+
+Everyone installs Huddle as in step 1, on their own machine, with their own agents.
+
+1. Put the repo on GitHub and have each teammate clone it.
+2. In your `huddle`, type `sync on` so merged work gets pushed for them.
+3. Type `invite @their-github-name`. Huddle prints a one-time `huddle join <address> <CODE>` line (valid 10 minutes).
+4. They run that line inside their clone. Their agents now take tasks off your board, using their own accounts.
+
+Not on the same Wi-Fi? Install [Tailscale](https://tailscale.com) on both machines, or run `huddle relay` on a server and type `relay <url>` in your huddle.
+
+## Everyday commands
+
+| Command | What it does |
+|---|---|
+| `huddle` | open Huddle in this repo |
+| `huddle join "<goal>" --plan` | dry run: show who would do what |
+| `huddle setup` | install and sign in to your agents (asks first) |
+| `huddle doctor` | check Node, git and your agents |
+| `huddle agents` · `huddle agents skip <id>` · `use <id>` | who's ready, and which agents Huddle uses |
+| `huddle view` | watch a run live |
+| `huddle story` | replay the last run |
+| `huddle board` | print the task board |
+| `add <file>` / `ctx` | (at the prompt) put a file on the shared screen / see what's on it |
+| `huddle add <file\|->` / `huddle ctx` | running claude/codex/cursor yourself (`huddle connect`): put a file, folder or stdin (`cat err.log \| huddle add -`) on the shared screen every session reads / see it |
+| `npm install -g huddle-cli` | update to the newest version |
+| `npm uninstall -g huddle-cli` | remove it (your repos keep their work) |
+
+## If something goes wrong
+
+- **`EACCES` when installing:** your npm global folder is owned by root. Use [nvm](https://github.com/nvm-sh/nvm), or run `npm config set prefix ~/.npm-global` and add `~/.npm-global/bin` to your `PATH`. Don't use `sudo`.
+- **An agent says "not signed in":** `huddle setup` walks you through it, or run the sign-in command `huddle doctor` shows next to it.
+- **"Node.js 20 or newer":** `nvm install 22`, then install Huddle again.
+- **Anything else:** `HUDDLE_DEBUG=1 huddle …` prints the full error.

package/README.md

@@ -1,3 +1,377 @@
-# Temporary Holding Version
+<div align="center">
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# 🏈 Huddle
+
+### The multiplayer layer for AI coding agents.
+
+**One command. Every agent. One repo. Zero collisions.**
+
+`npm install -g huddle-cli` → `huddle`
+
+**New here? [QUICKSTART.md](QUICKSTART.md)** — install, first run, teammates, in one page.
+
+</div>
+
+---
+
+## Get started (any computer)
+
+You need **Node.js 20+** and **git**. Then:
+
+```bash
+npm install -g huddle-cli        # puts `huddle` on your PATH
+huddle setup                     # checks node + git, installs and signs in the agents you pick
+
+cd ~/some-git-repo
+huddle                           # welcome → connects your agents → huddle ›
+```
+
+Prefer a script? `install.sh` checks Node, npm, git and a root-owned npm folder first, then runs the same `npm install -g` (this URL works only once the GitHub repo is public; until then use the npm command above):
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/Preet37/Huddle/main/install.sh | sh
+```
+
+**Agents.** Huddle drives the coding-agent CLIs you already use — Claude Code (`claude`), Codex (`codex`), Antigravity (`agy`), Cursor (`cursor-agent`), and Gemini CLI if it's installed. You need at least one. `huddle setup` (and the first `huddle`) offers to install any that are missing and to sign you in, **always asking first**; `huddle doctor` prints the exact install commands for your OS. Don't want one? `huddle agents skip cursor` keeps it off every run, even when installed; `huddle agents use cursor` undoes it.
+
+**Windows:** works natively in PowerShell — the same two commands; `huddle setup` uses each agent's PowerShell installer. Fallback if anything fails: WSL (`wsl --install`, then the Linux steps). Details in [QUICKSTART.md](QUICKSTART.md#windows). Each agent signs in with its own account and bills to it — Huddle never sees or stores a credential.
+
+**Not a git repo?** `huddle` offers to set one up (git init + a first commit). One-shot `huddle join "<goal>"` won't touch a non-repo folder.
+
+**Updating:** `npm install -g huddle-cli` again · **Version:** `huddle --version` · **Remove:** `npm uninstall -g huddle-cli` (your repos keep their work; delete a repo's `.huddle/` folder to clear its board).
+
+<details>
+<summary>Troubleshooting a fresh install</summary>
+
+- **`EACCES` from npm** — your Node's global folder is root-owned. Use a version manager ([nvm](https://github.com/nvm-sh/nvm)), or `npm config set prefix ~/.npm-global` and add `~/.npm-global/bin` to `PATH`. Don't `sudo npm`.
+- **"couldn't open its room database (SQLite)"** — the room db uses `better-sqlite3`, a native module that normally downloads a prebuilt binary. If it couldn't (offline, unusual platform, Node upgraded after install), reinstall with `npm install -g huddle-cli`. On **Node 22.13+** Huddle falls back to Node's built-in SQLite automatically, so nothing needs building.
+- **`huddle needs Node.js 20 or newer`** — update Node (`nvm install 22`), then reinstall.
+- **An agent shows "not signed in"** — run the command `huddle doctor` prints next to it (e.g. `codex login`), then `huddle doctor` again.
+- Anything else: `HUDDLE_DEBUG=1 huddle …` prints the full stack.
+
+</details>
+
+### From source (contributors)
+
+```bash
+git clone https://github.com/Preet37/Huddle.git && cd Huddle
+npm install && npm link          # builds dist/ and links `huddle`
+npm test                         # no tokens spent — mock agents (test/README.md)
+```
+
+## Using it
+
+At the `huddle ›` prompt, type what you want built. Huddle plans it into parallel tasks, runs your agents at the same time (each in its own sandbox), merges finished work when tests pass, and ends with a "what you got" report. Ask a question (`where are we with this project?`) and it answers read-only instead.
+
+- **shift+tab** switches mode: `manual` (approve the plan and each merge) → `auto` → `plan` (dry run)
+- **`approvals safe|auto|yolo`** sets what agents may do without asking
+- keep typing while agents work: `board`, questions, and new goals (queued) all work mid-run
+- `cd`, `!cmd`, `clear` behave like a shell; not a git repo? Huddle offers to set it up
+
+**How the agents work together on a big goal:**
+
+- **Council.** Each agent proposes a design, then reads the others' and answers `ADOPT` (what a teammate got right that it missed), `FLAW` (what a teammate got wrong, and why) and `REVISED`. The agent whose ideas were adopted by the most teammates writes the plan (ties: the most adoptions in all, then the fewest flaws found, then whoever has written fewest plans); the brain writes it if nobody adopted anything. Each task records whose idea it was.
+- **Contract.** The plan comes with a contract: the exact shared names (files and owners, signatures, data fields, routes, error strings). The other agents reply `OK` or `OBJECT: <change>`, with one revision round. It's committed as `HUDDLE_CONTRACT.md` and included in every task prompt. To change a name mid-task an agent calls `huddle_amend_contract`, and everyone still working is told.
+- **Mid-task mail.** Every Plug call result includes the agent's new messages. Claude also gets them after any tool use, through a hook. Agents report progress at about 25/50/75%.
+- **Radar.** About every 20s Huddle compares the uncommitted work of the agents in flight. It looks for edits to the same lines, and for imports of a name the other agent's module doesn't export (`getItems` vs `listItems`). It tells both agents while they can still fix it. Turn it off with `HUDDLE_RADAR_SEC=off`.
+- **Buddy checks.** At about 40% (and again at 75% if there were notes), another agent reads the work in progress. It checks it against the task, the contract and the other tasks in flight, and its notes go to the author's inbox. An agent that finishes while a check is still being written waits for it. An agent that never reports progress gets its check after 2 minutes instead (`HUDDLE_BUDDY_AFTER_SEC`). Turn it off with `HUDDLE_BUDDY=off`.
+- **Notes need an answer.** A buddy note or a radar finding stays open until the author fixes the file it names or replies to it (`won't fix: <why>` counts). `huddle_done` with notes still open is refused once, with the list; the second `huddle_done` always goes through, and the note is recorded as ignored.
+- **Pairing.** When an agent is free and a task is under 50% done (one that never reports progress only after twice the help wait, with little of its file list started), the free agent proposes taking a separate part of it, or its tests. The author has 60s to say no.
+- `huddle story` shows all of this afterwards: who adopted whose idea, who objected, contract versions, what the radar caught, buddy notes (addressed or ignored), and pairs.
+
+None of these steps blocks the run. If an agent doesn't answer or doesn't follow the format, the run continues as it would without that step.
+
+**Pasting and files: one shared screen, not N copies.** Paste a stack trace, a doc or a block of code at the prompt and it becomes one item on the Room's *shared screen* (`📎 pasted 214 lines (ctx-3 'TypeError…')`) instead of 214 commands; what you type next is the goal. Drag a file or screenshot into the terminal, or `add <file|folder|glob>`. Prompts carry only a one-line index per item; the planner links items to the tasks that need them, and agents open them with `huddle_context_read` (400 lines a call, images and PDFs as a file path; Codex also gets linked screenshots via `--image`), search them, and pin notes on them that everyone sees. `ctx` lists the screen (`ctx show|rm|note|clear`). Likely secrets (API keys, tokens, private keys, `.env` lines) are flagged before anything is shown to agents, and redacted unless you say no. One-shot: `huddle join "fix this" --with error.log --with shot.png`, or `cat log.txt | huddle join "fix this"`. Items live in `.huddle/context/` (git-ignored); caps: 2 MB of text, 25 MB per file, 200 MB in all (`HUDDLE_CTX_MAX_*_MB`).
+
+**Running claude, codex and cursor yourself, in one repo at once (attach mode):**
+
+```bash
+huddle connect      # shows the project config files it will write per agent, asks, then wires each one in
+                    # (git-excluded, backed up, never your global configs; `huddle disconnect` undoes it)
+claude              # open your agents as usual, in as many terminals as you like
+huddle peers        # who's live, what each is doing, which files each one holds
+```
+
+Each session checks in before editing, claims the files it's about to change, and gets warned (Claude: asked through its own permission prompt) when another session holds them. Sessions can leave each other notes. The shared screen works here too: `huddle add err.log` (or `cat err.log | huddle add -`) from any terminal puts it up, every session hears `📎 new on the screen: ctx-4 …` on its next Huddle call and reads it with `huddle_context_read`; `huddle ctx` lists it (`show|rm|note|clear`). Want each session on its own branch instead? `huddle attach codex` opens it in a worktree, and `huddle land` tests and merges it. Live-verified for Claude and Codex; Cursor checks in but hasn't finished a live attach run yet (see STATUS).
+
+**With a team:** `invite @harsh` in your Huddle; Harsh installs Huddle the same way and runs the `huddle join …` line it prints, from his clone of the repo. His agents take tasks off your board, work on his machine with his accounts, and push branches you test, review and merge. Different networks? `huddle relay` somewhere and `relay <url>`.
+
+What's real today vs. designed: **[docs/STATUS.md](docs/STATUS.md)**.
+
+---
+
+## The one-sentence pitch
+
+You already pay for Claude Code, Codex, Gemini CLI, and Cursor — but you run them **one at a time**, because they can't see each other and would trash the same repo. **Huddle puts all of them in the same room**: they split the work, each codes in its own invisible sandbox, they watch each other's progress live, and nothing merges until the tests pass. You stop waiting. You stop babysitting. You never touch git.
+
+---
+
+## The problem (in your words)
+
+> "I have Claude, I have Codex, I have Gemini, I have Cursor. I tend not to use Gemini or Cursor if Claude is running, and I try not to use Codex when Claude is running because it's doing something. I don't know what Cursor is going to do versus Codex versus Claude."
+
+That's the whole problem in one paragraph. It isn't a *team* problem. It's **one person with four agents who are blind to each other.** So you serialize them by hand — which means you're paying for four engines and running one.
+
+The deeper version, for teams:
+
+> "I'm person A working on one portion. Person B is on another. I don't know what B is doing until B pushes to git. I could be done and just *waiting*."
+
+Both are the **same coordination problem**: no shared awareness, no shared plan, no shared memory. Git only tells you what happened *after* it happened.
+
+```mermaid
+%%{init: {'theme':'dark'}}%%
+flowchart LR
+    subgraph today["❌ Today — blind & serialized"]
+        direction TB
+        You1["👤 You"] -->|"run one,<br/>wait, run next"| C1["Claude"]
+        C1 -.->|"finishes"| X1["Codex"]
+        X1 -.->|"finishes"| G1["Gemini"]
+        G1 -.->|"finishes"| U1["Cursor"]
+        note1["Agents can't see each other.<br/>You are the message bus.<br/>3 engines idle at all times."]
+    end
+
+    subgraph huddle["✅ With Huddle — parallel & aware"]
+        direction TB
+        Room(("🏈 Huddle<br/>Room")) 
+        Ca["Claude"] <--> Room
+        Xa["Codex"] <--> Room
+        Ga["Gemini"] <--> Room
+        Ua["Cursor"] <--> Room
+        note2["Shared plan · shared memory · live progress.<br/>All engines running. No collisions."]
+    end
+
+    today ==> huddle
+```
+
+---
+
+## What Huddle actually is
+
+Huddle is **not** a new editor, and **not** a new agent. It's a thin neutral layer that sits *above* the agents you already use. Three moving parts:
+
+```mermaid
+%%{init: {'theme':'dark'}}%%
+flowchart TB
+    subgraph laptop["Your laptop"]
+        CLI["🧰 huddle CLI<br/><i>the daemon</i>"]
+        Room[("🏈 The Room<br/>SQLite + WebSocket<br/><i>tasks · progress · shared memory</i>")]
+        subgraph agents["Your agents — unchanged"]
+            A1["Claude Code"]
+            A2["Codex"]
+            A3["Gemini CLI"]
+            A4["Cursor Agent"]
+        end
+        MCP["🔌 The Plug<br/><i>one MCP server</i>"]
+        subgraph boxes["Isolated sandboxes (git worktrees)"]
+            W1["worktree/claude"]
+            W2["worktree/codex"]
+            W3["worktree/gemini"]
+        end
+    end
+
+    CLI --> Room
+    CLI --> MCP
+    A1 & A2 & A3 & A4 -->|"speak MCP"| MCP
+    MCP <--> Room
+    CLI -->|"spawns each agent in"| boxes
+    A1 --> W1
+    A2 --> W2
+    A3 --> W3
+    boxes -->|"tests pass → merge"| main["🌳 main branch"]
+
+    style Room fill:#3b1f6e,stroke:#a78bfa,color:#fff
+    style MCP fill:#1e3a5f,stroke:#60a5fa,color:#fff
+```
+
+**1. The Room** — a tiny local server + a single-file SQLite database. It holds the task board, who claimed what, live progress, and *shared memory* (decisions + the "why" behind them). Think group chat + whiteboard + kanban, but for agents.
+
+**2. The Plug** — one [MCP](https://modelcontextprotocol.io) server. MCP is the "USB-C for AI tools": Claude, Codex, Gemini, and Cursor **all already speak it**. We build the plug once, and every agent instantly gains new verbs: *see the board, claim a task, announce a plan, post progress, read shared memory, check what everyone else is doing, mark done.* This is why Huddle works **without switching tools**.
+
+**3. The Sandboxes** — when an agent claims a task, Huddle silently gives it its own [git worktree](https://git-scm.com/docs/git-worktree): a separate working copy of the repo. Agents physically cannot corrupt each other's files. Git is the plumbing; **you never see it**. Work only rejoins `main` when tests are green.
+
+> **The reframe that matters:** we don't kill git — we *hide* it. "Git is dead" is a claim engineers argue with. **"You never have to touch git again"** is a claim they pay for.
+
+---
+
+## The magic loop
+
+```mermaid
+%%{init: {'theme':'dark'}}%%
+sequenceDiagram
+    autonumber
+    participant You
+    participant Orch as 🧠 Orchestrator<br/>(Opus 5.5)
+    participant Room as 🏈 Room
+    participant Claude
+    participant Codex
+    participant Gemini
+
+    You->>Orch: "Build the checkout flow"
+    Orch->>Orch: decompose into tasks +<br/>route by strength
+    Orch->>Room: post task board
+    par Everyone reads the same board
+        Claude->>Room: claim "payment UI" (best at frontend)
+        Codex->>Room: claim "Stripe integration"
+        Gemini->>Room: claim "order-confirmation email"
+    end
+    Note over Claude,Gemini: each works in its own sandbox
+    Claude->>Room: announce plan → "renaming Cart type"
+    Codex->>Room: reads memory → "Cart type is changing, I'll wait / adapt"
+    Note over Room: ⚠️ collision predicted BEFORE it happens
+    Codex->>Room: progress 40% · 60% · done ✅
+    Codex->>Room: tests green → merged to main
+    Claude->>Room: I'm free — what's backlogged?
+    Room-->>Claude: steal "email template" (Gemini is slow)
+    Note over You,Gemini: You watch one dashboard.<br/>No engine sits idle.
+```
+
+Five behaviors fall out of this loop — the ones you called for:
+
+| Behavior | What it does | Where it lives |
+|---|---|---|
+| **Talk it out first** | Agents announce plans before coding: "I'll take auth, you take the DB." | Room + Plug |
+| **Live awareness** | Your agent sees a teammate's piece is 70% done and lines up the next step. No waiting on a push. | Room (WebSocket) |
+| **Collision radar** | Two agents about to edit the same symbol? Flagged *before* a line is written. | Overlap detector |
+| **Shared memory** | My agent knows *why* your agent renamed that function, not just *what* changed. | Room (`memory` table) |
+| **Work-stealing** | An idle agent grabs backlogged tasks from a busy one — the bottleneck removed automatically. | Scheduler |
+
+---
+
+## The account problem — designed for from day one
+
+Real setups are messy: some agents are on a personal account, one comes through school or work, and subscriptions start and lapse month to month.
+
+**Huddle never handles a single credential.** That's the core design decision, and it's what makes it survive every subscription change.
+
+Each vendor CLI (`claude`, `codex`, `gemini`, `cursor-agent`) already logs in **its own way, to its own account** — Claude to your personal Anthropic login, Cursor to your school or work SSO, etc. Huddle treats each as a **black box it launches**, not an account it owns. It only ever asks two questions: *are you installed?* and *are you logged in?*
+
+```mermaid
+%%{init: {'theme':'dark'}}%%
+flowchart TB
+    Roster["📇 roster.toml<br/><i>which agents exist,<br/>which model each maps to</i>"]
+    Doctor["🩺 huddle doctor<br/><i>runs on every join</i>"]
+
+    Roster --> Doctor
+    Doctor --> Q1{"claude<br/>installed +<br/>authed?"}
+    Doctor --> Q2{"codex?"}
+    Doctor --> Q3{"gemini?"}
+    Doctor --> Q4{"cursor-agent?"}
+
+    Q1 -->|"✅ personal acct"| Pool["🏈 Active roster<br/>for this session"]
+    Q2 -->|"✅ personal acct"| Pool
+    Q3 -->|"✅ personal acct"| Pool
+    Q4 -->|"✅ school / work SSO"| Pool
+    Q4 -.->|"❌ expired?"| Skip["gracefully skipped<br/>— session still runs"]
+
+    Pool --> Session["huddle join 🚀"]
+
+    style Roster fill:#3b1f6e,stroke:#a78bfa,color:#fff
+    style Pool fill:#14532d,stroke:#4ade80,color:#fff
+```
+
+**Why this survives all of that:**
+
+- **Different accounts?** Each CLI carries its own login. Huddle doesn't care that one agent is on a work account and the rest are personal — it just shells out to `cursor-agent` and that binary knows who it is.
+- **Subscription expires next month?** `huddle doctor` sees the auth check fail, drops that agent from the roster, and the session runs with whoever's left. Nothing breaks.
+- **You get GPT/Codex back later?** Reinstall the CLI, log in, and it reappears in the roster automatically. Zero Huddle config change.
+- **A vendor ships a new CLI or renames flags?** Only that one **adapter file** changes (~30 lines). The Room, Plug, and everything else are untouched. See [`docs/ADAPTERS.md`](docs/ADAPTERS.md).
+
+Each agent is described by a small **adapter** — a declaration of "how do I launch you, and how do I hand you the Plug?" That's the entire vendor-specific surface area.
+
+---
+
+## The agent architecture (Opus 5.5 orchestrator + Fable/Opus workers)
+
+You wanted every agent to be a top-tier model — an **Opus 5.5 orchestrator** with **Fable / Opus 5.5** workers, not cheap subagents. That's the design: a strategist that never writes code, and a pool of elite executors.
+
+```mermaid
+%%{init: {'theme':'dark'}}%%
+flowchart TB
+    You["👤 You: one goal"] --> Orch
+
+    subgraph brain["🧠 Orchestrator — Opus 5.5"]
+        Orch["Decompose goal → tasks<br/>Route by model strength<br/>Predict conflicts<br/>Rebalance the queue"]
+    end
+
+    Orch --> Board[("🏈 Task Board")]
+
+    subgraph workers["⚡ Worker pool — Opus 5.5 / Fable, routed by strength"]
+        direction LR
+        Wf["Fable<br/><i>fast execution,<br/>breadth</i>"]
+        Wo["Opus 5.5<br/><i>hard reasoning,<br/>architecture</i>"]
+        Wr["Opus 5.5 (reviewer)<br/><i>adversarial check</i>"]
+    end
+
+    Board --> Wf & Wo
+    Wf & Wo --> Wr
+    Wr -->|"✅ approved + tests green"| Merge["merge → main"]
+    Wr -->|"❌ found a bug"| Board
+
+    style Orch fill:#3b1f6e,stroke:#a78bfa,color:#fff
+    style Wr fill:#5b2121,stroke:#f87171,color:#fff
+```
+
+The orchestrator maps to Claude Code's native pattern (Opus 5.5 orchestrating, spawning workers), and the *same* Room lets **external** agents (Codex, Gemini, Cursor) join the exact same board as first-class workers. One brain, many hands, mixed vendors.
+
+> **Guardrail:** agents advising each other raises quality, but two models can also talk each other *into* the same wrong answer. So **tests — not agent consensus — are the referee.** Nothing merges on vibes.
+
+---
+
+## Why nobody has shipped this (and why now)
+
+- **Real-time shared coding was tried for *humans*** — VS Code Live Share, Replit multiplayer, Zed — and never became the default, because humans coordinate fine by *talking*. A daily pull request was good enough.
+- **Agents broke that math.** One person now runs four agents that type faster than any human and are blind to each other. Coordination went from *annoying* to *the actual bottleneck* — and only in the last year, once agents got trustworthy enough to run in parallel.
+- **The labs won't build the neutral version.** Anthropic wants you on Claude; OpenAI wants you on Codex. Neither is motivated to make its agent cooperate with a rival's. **A neutral middle layer is exactly the gap a small team can own.**
+
+So it's not that it was tried and failed. **The problem is new.**
+
+---
+
+## Honest hard parts (we're not hiding these)
+
+- **Agents forget to check the room.** Mitigation: the Plug injects "check the board before you start and after each step" into the launch prompt, and the daemon nudges idle agents.
+- **Merges can still break** when two "separate" tasks were secretly coupled. Mitigation: the overlap detector + tests-as-referee catch most; a human approves the rest.
+- **Shared resources outside code** — same port, same dev DB, same package version. Mitigation: the Room brokers a lease on shared resources (ports, migrations).
+- **Cost & rate limits multiply** with four agents. Mitigation: per-agent budgets + a live spend meter; the orchestrator throttles.
+- **Token savings are a *maybe*, not a promise.** Fewer duplicated efforts and less re-reading save tokens; checking the room and cross-advising spend them. **We pitch "less wasted work," and we'll only claim token savings once we've measured them.**
+
+---
+
+## Where this is going
+
+```mermaid
+%%{init: {'theme':'dark'}}%%
+timeline
+    title Huddle roadmap
+    V0 · You + your laptop : Claude + Codex, one repo : split a task, see each other, auto-merge : (you are your own first customer)
+    V1 · Full local roster : Gemini + Cursor adapters : work-stealing + collision radar : live TUI dashboard
+    V2 · Two humans : Room moves to the cloud : your agents + your teammate's, same board : no more "waiting on a push"
+    V3 · Teams & trust : self-hosted Room for companies : replay log + budgets + approvals : the coordination layer for agentic teams
+```
+
+**V0 is the wedge**: just *you*, on one laptop, Claude and Codex splitting a task in the same repo without colliding. If that feels magical to you, adding a second human is mostly moving the Room to the cloud.
+
+---
+
+## Repo map
+
+| Path | What's inside |
+|---|---|
+| [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) | Deep dive: the Room schema, the Plug's MCP verbs, the sandbox/merge model, data flow diagrams. |
+| [`docs/ADAPTERS.md`](docs/ADAPTERS.md) | The account/auth strategy in full — how Huddle stays alive as your subscriptions change. |
+| [`docs/STATUS.md`](docs/STATUS.md) | **What's built right now**, verified status per component, and the changelog. Updated with every change. |
+| [`docs/MULTIPLAYER.md`](docs/MULTIPLAYER.md) | V2 design: crews on different laptops, the Room relay, security, invite/join/leave, no-idle agents. |
+| [`docs/ROADMAP.md`](docs/ROADMAP.md) | Build order, V0→V3, and what's a demo vs. what's real. |
+| `src/` | The runnable prototype — app (`src/ui`), Room, Plug, scheduler, sandboxes, adapters. |
+| `install.sh` | One-line installer for the `huddle` CLI. |
+| `teaser/` | The cinematic teaser page (screen-record → video). |
+
+---
+
+<div align="center">
+
+**Huddle** — your agents, in the same room.
+
+*Built as a working prototype + full design. Not vaporware.*
+
+</div>

package/dist/adapters/amp.js

@@ -0,0 +1,40 @@
+import { ampUsage } from "./usage.js";
+// Amp (Sourcegraph) — headless via execute mode, `amp -x`. The Plug is passed
+// inline with --mcp-config '{"huddle": {...}}', which "specif[ies] an MCP server
+// without changing your settings file". Auth is Amp's own (`amp login`, or
+// AMP_API_KEY).
+//
+// Sources (checked 2026-10):
+//   https://ampcode.com/docs/cli                 install script, amp login, AMP_API_KEY
+//   https://ampcode.com/docs/cli/execute-mode    -x/--execute, --mcp-config '{"name": {"command", "args"}}'
+//   https://ampcode.com/docs/cli/streaming-json  --stream-json (needs --execute), message schema with usage
+//   https://ampcode.com/news/amp-x               -x runs tools (renames files) without stopping to ask
+// Amp picks models by mode, not by a model flag, so Huddle passes none.
+// Approvals: Amp doesn't ask before running tools by default, so all three
+// Huddle modes run the same; the worktree is the fence. Unverified: whether
+// --mcp-config honors "env" (it's sent anyway; the agent's own env has the
+// same values, which stdio servers normally inherit). Not yet run live.
+export const ampAdapter = {
+    id: "amp",
+    vendor: "sourcegraph",
+    bin: "amp",
+    roles: ["worker", "reviewer"],
+    prefers: ["refactor", "backend", "frontend"],
+    models: { orchestrator: "", worker: "", fast: "", reviewer: "" },
+    accountNote: "your Amp account",
+    homepage: "https://ampcode.com/docs/cli",
+    optional: true,
+    install: { cmd: "curl -fsSL https://ampcode.com/install.sh | bash", win: null, login: ["amp", "login"] },
+    authProbe: {
+        cmd: ["amp", "--version"],
+        ok: (r) => r.code === 0,
+        fixHint: "run `amp login` (or set AMP_API_KEY)",
+    },
+    plug: {},
+    usage: ampUsage,
+    launch: ({ worktree, prompt, plug }) => ({
+        cmd: ["amp", "--mcp-config", JSON.stringify({ huddle: plug }), "-x", prompt, "--stream-json"],
+        cwd: worktree,
+    }),
+};
+//# sourceMappingURL=amp.js.map

package/dist/adapters/antigravity.js

@@ -0,0 +1,54 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { agyUsage } from "./usage.js";
+// Antigravity CLI (`agy`) — Google's terminal agent, which replaced Gemini CLI
+// for personal Google accounts in June 2026. Headless via `-p`; MCP servers are
+// read from .agents/mcp_config.json in the workspace, so the launcher writes
+// the Plug there (and the merge engine keeps it out of commits).
+// NOTE: flags taken from Antigravity docs; not yet verified on a real run.
+const agyAuthed = () => Boolean(process.env.GEMINI_API_KEY) || fs.existsSync(path.join(os.homedir(), ".gemini", "antigravity-cli"));
+export const antigravityAdapter = {
+    id: "antigravity",
+    vendor: "google",
+    bin: "agy",
+    roles: ["worker", "fast"],
+    prefers: ["research", "breadth", "docs", "data"],
+    models: { orchestrator: "", worker: "", fast: "", reviewer: "" },
+    accountNote: "personal Google",
+    install: {
+        // https://antigravity.google/docs/getting-started?tab=cli
+        cmd: "curl -fsSL https://antigravity.google/cli/install.sh | bash",
+        win: "irm https://antigravity.google/cli/install.ps1 | iex",
+        login: ["agy"],
+        // agy has no login subcommand — signing in happens inside its own chat UI.
+        loginNote: "Antigravity opens its own chat to sign you in — once your email shows at the top, press ctrl-c twice to come back to Huddle",
+    },
+    authProbe: {
+        cmd: ["agy", "--version"],
+        ok: (r) => r.code === 0,
+        check: agyAuthed,
+        fixHint: "run `agy` once and sign in with Google (or set GEMINI_API_KEY)",
+    },
+    plug: {
+        file: { path: ".agents/mcp_config.json", in: "worktree" },
+        entry: (plug) => ({ mcpServers: { huddle: plug } }),
+    },
+    ask: ({ prompt, cwd, model }) => ({ cmd: ["agy", "-p", prompt, "--mode", "plan", ...(model ? ["--model", model] : [])], cwd }),
+    usage: agyUsage,
+    launch: ({ worktree, prompt, model, approvals }) => ({
+        cmd: [
+            "agy",
+            "-p",
+            prompt,
+            "--output-format",
+            "stream-json", // so Huddle can count tokens
+            ...(model ? ["--model", model] : []),
+            ...(approvals === "safe" ? ["--mode", "accept-edits"] : []),
+            ...(approvals === "auto" ? ["--sandbox", "--dangerously-skip-permissions"] : []),
+            ...(approvals === "yolo" ? ["--dangerously-skip-permissions"] : []),
+        ],
+        cwd: worktree,
+    }),
+};
+//# sourceMappingURL=antigravity.js.map