huddle-cli 0.0.0-stage → 0.1.0

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/README.md

@@ -1,3 +1,358 @@
-# 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`
+
+</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 doctor                    # checks node, git, and which agents you have
+
+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` (works once the GitHub repo is public):
+
+```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` offers to install any that are missing and to sign you in, **always asking first**; `huddle doctor` prints the exact install commands. 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
+
+**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. 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", 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,52 @@
+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: {
+        cmd: "curl -fsSL https://antigravity.google/cli/install.sh | bash",
+        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

package/dist/adapters/claude.js

@@ -0,0 +1,70 @@
+import { claudeUsage } from "./usage.js";
+// Claude Code — launched headless with `-p`. The Plug is handed over with
+// --mcp-config pointing at a file in .huddle/run/, so nothing lands in the
+// agent's worktree. Auth is Claude's own (OAuth or ANTHROPIC_API_KEY); Huddle
+// never touches it.
+const PERMISSIONS = {
+    safe: ["--permission-mode", "acceptEdits", "--allowedTools", "mcp__huddle"],
+    // Claude's own auto mode: a safety check approves routine actions.
+    auto: ["--permission-mode", "auto", "--allowedTools", "mcp__huddle"],
+    yolo: ["--dangerously-skip-permissions"],
+};
+export const claudeAdapter = {
+    id: "claude",
+    vendor: "anthropic",
+    bin: "claude",
+    roles: ["orchestrator", "worker", "reviewer"],
+    prefers: ["frontend", "design", "product", "refactor"],
+    // CLI aliases, not dated ids — Claude Code resolves them to the latest model.
+    models: { orchestrator: "opus", worker: "opus", fast: "haiku", reviewer: "opus" },
+    accountNote: "personal Anthropic",
+    install: { cmd: "curl -fsSL https://claude.ai/install.sh | bash" },
+    authProbe: {
+        // `claude auth status` (JSON by default, verified on 2.1.300): exit 0 +
+        // "loggedIn": true when signed in (OAuth or ANTHROPIC_API_KEY), exit 1 +
+        // "loggedIn": false when not. `--version` used to be the probe, which showed
+        // a signed-out Claude as ready.
+        cmd: ["claude", "auth", "status"],
+        ok: (r) => r.code === 0 && !/"loggedIn"\s*:\s*false/.test(r.stdout),
+        fixHint: "run `claude` once and sign in (OAuth) or set ANTHROPIC_API_KEY",
+    },
+    plug: {
+        file: { path: "claude-mcp.json", in: "run-dir" },
+        entry: (plug) => ({ mcpServers: { huddle: { type: "stdio", ...plug } } }),
+    },
+    // Read-only questions never need your personal MCP servers (Gmail, Drive, …).
+    // Self-contained prompts go further: safe mode + no tools ≈ 15k tokens of
+    // context instead of ~38k (or 200k+ on Haiku, which loads every tool eagerly).
+    ask: ({ prompt, cwd, model, noTools }) => ({
+        cmd: [
+            "claude",
+            "-p",
+            prompt,
+            "--model",
+            model || "opus",
+            ...(noTools ? ["--safe-mode", "--tools", ""] : ["--permission-mode", "plan", "--strict-mcp-config"]),
+        ],
+        cwd,
+    }),
+    usage: claudeUsage,
+    launch: ({ worktree, prompt, model, mcpConfigPath, approvals }) => ({
+        cmd: [
+            "claude",
+            "-p",
+            prompt,
+            ...(model ? ["--model", model] : []),
+            ...PERMISSIONS[approvals],
+            "--mcp-config",
+            mcpConfigPath,
+            // Only Huddle's Plug — not your personal MCP servers. Smaller context
+            // every turn, and a headless agent can't reach your Gmail/Drive/etc.
+            "--strict-mcp-config",
+            // JSON events so Huddle can count tokens live (logs stay in .huddle/logs)
+            "--output-format",
+            "stream-json",
+            "--verbose",
+        ],
+        cwd: worktree,
+    }),
+};
+//# sourceMappingURL=claude.js.map

package/dist/adapters/codex.js

@@ -0,0 +1,59 @@
+import { codexUsage } from "./usage.js";
+// OpenAI Codex CLI — runs non-interactively via `codex exec`. The Plug is
+// passed as `-c mcp_servers.huddle.*` overrides, so neither ~/.codex/config.toml
+// nor the worktree is touched. Auth is `codex login` (ChatGPT) or OPENAI_API_KEY.
+const toml = (v) => JSON.stringify(v); // strings/arrays are valid TOML as JSON
+const tomlTable = (o) => `{${Object.entries(o).map(([k, v]) => `${k}=${toml(v)}`).join(",")}}`;
+export const codexAdapter = {
+    id: "codex",
+    vendor: "openai",
+    bin: "codex",
+    roles: ["worker", "reviewer"],
+    prefers: ["systems", "algorithms", "refactor", "backend"],
+    models: { orchestrator: "", worker: "", fast: "", reviewer: "" },
+    accountNote: "personal OpenAI",
+    install: { cmd: "npm install -g @openai/codex", login: ["codex", "login"] },
+    authProbe: {
+        // `codex login status` exits non-zero when not authenticated.
+        cmd: ["codex", "login", "status"],
+        ok: (r) => r.code === 0,
+        fixHint: "run `codex login` (or set OPENAI_API_KEY)",
+    },
+    plug: {},
+    // exec streams its work to stdout; -o captures just the final answer.
+    ask: ({ prompt, cwd, outFile, model }) => ({
+        cmd: ["codex", "exec", "--sandbox", "read-only", ...(model ? ["-m", model] : []), "-o", outFile, prompt],
+        cwd,
+        usesOutFile: true,
+    }),
+    usage: codexUsage,
+    launch: ({ worktree, prompt, model, plug, approvals }) => ({
+        cmd: [
+            "codex",
+            "exec",
+            "--json", // JSON events so Huddle can count tokens live
+            ...(model ? ["--model", model] : []),
+            "-c",
+            `mcp_servers.huddle.command=${toml(plug.command)}`,
+            "-c",
+            `mcp_servers.huddle.args=${toml(plug.args)}`,
+            "-c",
+            `mcp_servers.huddle.env=${tomlTable(plug.env)}`,
+            // Headless: nobody can click "allow", and Codex refuses unapproved MCP
+            // calls under exec. The Plug is Huddle's own server, so pre-approve it.
+            "-c",
+            `mcp_servers.huddle.default_tools_approval_mode="approve"`,
+            // `codex exec` never stops to ask; its sandbox confines commands to the
+            // worktree. Without network, the sandbox also refuses to listen on
+            // localhost: seen live on the capstone, Codex couldn't run its own HTTP
+            // API tests ("26 HTTP tests blocked by sandbox listen EPERM"). `auto`
+            // runs commands freely, so it gets network; `safe` stays offline.
+            ...(approvals === "yolo"
+                ? ["--dangerously-bypass-approvals-and-sandbox"]
+                : ["--sandbox", "workspace-write", ...(approvals === "auto" ? ["-c", "sandbox_workspace_write.network_access=true"] : [])]),
+            prompt,
+        ],
+        cwd: worktree,
+    }),
+};
+//# sourceMappingURL=codex.js.map