huddle-cli 0.1.0 → 0.1.3

package/CHANGELOG.md

@@ -0,0 +1,69 @@
+# Changelog
+
+## 0.1.3 — 2026-10-16
+
+You can follow a run, and take part in it, without being an engineer. Live capstone: 29/29 with real Claude, Codex and Cursor (13 merged, 0 failed, 22 min, 5.6M tokens, down from 6.6M).
+
+- **The plan in plain words.** The plan now opens with "What you'll get" (one or two sentences, no jargon) and "For example" (one real use and what you'd see). The technical decisions and risks fold into one line; `details` shows them.
+- **A narrator.** The top line of a live run says what's happening now ("the agents are each sketching how they'd build it", "building — 2 of 8 parts done · claude: argv parser") and ends with "nothing needed from you", unless something is.
+- **Agents can ask you.** For a big call the goal doesn't settle, an agent asks with 2–4 numbered options, its recommendation first (`huddle_ask_user`). Type a number, press Enter for the recommended one, or answer in your own words. With no answer in 90 seconds (`HUDDLE_ASK_USER_SEC`), it goes with its pick. At most 2 questions per agent per run; the answer goes into shared memory and shows in `huddle story` / `huddle export`.
+- **Talk to the agents mid-run.** Anything you type during a run goes to every agent working now and to every task that starts later, marked as from you; it wins over the plan and the contract. `@codex …` sends it to one agent. This works in `huddle` and in `huddle join` on a terminal (a typing line under the live status). `next <goal>` queues another run.
+- **`huddle build a temperature converter`**: plain words are a goal, with no `join` and no quotes.
+- **Names for the parts**: Room, Screen, Whiteboard, Board, Brief (see QUICKSTART).
+- **`huddle app`, the dashboard.** Huddle in your browser, for the repo you're in:
+  - **Live view:** the narrator, the overall bar, one card per agent (task, %, tokens).
+  - **Questions:** an agent's question shows as buttons, with a box for your own words.
+  - **Talk:** a composer to start a run or talk to the agents, with hold-to-talk voice (hold Space or the mic; the browser's own speech recognition).
+  - **History:** every past run as a conversation, with filters, the plan (who did what, what they agreed, the contract), cost per agent, "What you got", and one-click exports.
+  - **Any run:** it works for runs started in a terminal too (through `.huddle/live.json` and `.huddle/inbox/`).
+  - **Local and private:** it listens on 127.0.0.1 only, behind a per-session key. Runs started there keep going if you close the page.
+
+- **The dashboard reads as a story**: what you'll get (or got) in prose; the live status as one sentence, four steps and a chip per agent; the design as idea cards with who borrowed what; the plan part by part, each with its thread (reviews, mid-way checks, messages) in plain words. The raw log has its own tab. Serif headings, real icons, light and dark.
+- **Huddle for macOS** (`desktop/macos`): a ~1 MB native app around the dashboard. ⌘O picks a project, standard menus, exports to Downloads, hold-to-talk. `desktop/macos/build.sh` makes a universal `Huddle.app` and `Huddle.dmg`; see `desktop/README.md` for signing and notarizing.
+
+### Fixed (found in a live 0.1.2 run)
+- The design council waited 2 minutes on one agent's ratify that then timed out; ratifying (an OK or a few objections) now has 75 seconds (`HUDDLE_RATIFY_TIMEOUT_S`).
+- The budget's 90% line fired at 108%: Codex reports tokens only when its turn ends. Work in flight is now estimated at that agent's own pace for the 90% line (the 120% line still waits for real numbers).
+- Agents required Node 22 on a Node 20 machine: the planner and council now see the machine's OS and Node version.
+- A sent-back review's notes were stored as a "lesson" word for word; they're about one task, so they no longer are.
+- Two dashboard commands sent in the same millisecond could reach the run out of order.
+
+## 0.1.2 — 2026-10-16
+
+Memory that outlives the run, chat exports, progress bars, and a cost guard. Live capstone: 29/29 with real claude, codex and cursor.
+
+- **Quiet isn't stuck.** Before taking over an agent that has printed nothing for the silence window, Huddle checks whether it is working: a child process using CPU (a long test run, a build), files changing in its worktree, or its log growing. A busy agent gets more time and the run shows "⧗ running a long command" (in `huddle view` and `huddle story` too). It is still taken over after a hard cap, 3× the window by default (`HUDDLE_SILENCE_MAX_MIN`). This happened live: Claude was taken over in the middle of an 8-minute test suite.
+- **Cost guard.** The plan now comes with an estimate (`≈ 4–6M tokens, ~15–20 min with 3 agents`), based on this repo's past runs or on built-in defaults. `--budget=5M` (or `"budget"` in prefs) sets a limit. At 90% Huddle starts no new tasks, takeovers, QA rounds, buddy checks or pairings, and lets running tasks finish. At 120% it stops the agents, as Ctrl-C does. RESULT shows how much of the budget was used and lists what was left undone.
+- **Progress bars.** The live run pins an overall bar (`BUILD ███████░░░░░ 6/9 tasks · 12m`) that moves through the council's four steps, the build (fix tasks QA files included) and each QA round; every agent's status line has a mini bar from its own reported % (a dotted track and "no report yet" until it reports — never a made-up number). `huddle view` and ctrl-t show the same bars in the top bar, the agent panes and the board, ✓ when done and red when failed. Everything fits 60/80/120 columns; with NO_COLOR or piped output it's plain words ("BUILD 6/9 tasks"), one log line each time the numbers move.
+- **Hand-off brief.** Every run writes `.huddle/BRIEF.md` (goal, who built what, decisions, contract, open issues, how to continue) and points to it from a marked, uncommitted block in `CLAUDE.md` / `AGENTS.md`, so solo agents opened afterwards know what the team did. `huddle brief [--run n]`, `huddle brief off|on`.
+- **Run history and chat exports.** `huddle runs` lists every run in the repo (goal, agents, merged/failed, time, tokens, QA). `huddle export [<run>|latest]` saves a run like a chat app keeps a conversation: `--level summary` (result, who did what, decisions, contract, teamwork, cost), `chat` (every message between agents, buddy notes and replies, radar alerts, reviews, QA bugs and Huddle's notes, in full and in time order) or `full` (plus each agent's own session per task, read from the claude / codex / cursor logs), as Markdown, a self-contained HTML page with an agent filter, or JSON with a stable schema. Likely secrets are redacted (`--no-redact` keeps them).
+
+## 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/QUICKSTART.md

@@ -0,0 +1,135 @@
+# 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"`.
+
+Or skip the prompt: `huddle build a temperature converter with tests` (no quotes needed).
+
+**While it runs** the top line says what's happening in plain words, and whether you're needed:
+
+```
+  Now: building — 2 of 8 parts done · claude: argv parser · codex: conversion core 25% · nothing needed from you
+```
+
+- **Talk to the agents:** just type. `use two decimals` goes to every agent working now (and every one that starts later); `@codex use two decimals` to one. Your words win over the plan.
+- **When they need you:** for a big call the goal doesn't settle, an agent asks with numbered options, its pick first. Type a number, press Enter for the recommended one, or answer in your own words. No answer in 90 seconds and it goes with its pick, so a run never waits on you.
+- `details` shows the technical decisions behind the plan; `stop` (or ctrl-c) stops the agents and still shows what got done.
+
+**The dashboard:** `huddle app` opens Huddle in your browser. You get the run going now (who's on what, how far along, a question waiting for you), every past run as a conversation, the plan and what each agent cost. Type there to start a run or talk to the agents; hold Space (or the mic) to say it instead. It works for runs started in a terminal too. Runs keep going if you close the page.
+
+**A second view** (another 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
+huddle brief                   # the hand-off brief your next solo claude/codex/cursor reads
+huddle runs                    # every run in this repo: goal, agents, result, cost
+huddle export                  # the last run as a chat: who said what to whom (Markdown)
+huddle export 2 --level full --format html  # run 2 with each agent's own session, as a page
+```
+
+Each run leaves `.huddle/BRIEF.md` (decisions, contract, open issues) and a short pointer to it at the top of `CLAUDE.md` and `AGENTS.md`, so an agent you open on your own afterwards knows what the team did. The pointer isn't committed; `huddle brief off` removes it.
+
+## 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.
+
+## The words Huddle uses
+
+| Word | What it is |
+|---|---|
+| **Room** | Where your agents (and teammates' agents) meet for a goal. `huddle` opens yours; `invite` lets people in. |
+| **Screen** | The shared screen: what you paste, drag in or `add` — logs, docs, screenshots. Every agent reads it. |
+| **Whiteboard** | Where they design it together before coding: each one's idea, what they borrow from each other, the plan, and the contract (`HUDDLE_CONTRACT.md`, the exact names everyone codes to). `details` and `huddle story` show it. |
+| **Board** | Who's doing which part, how far along, what's merged. `board`, `huddle view`, ctrl-t. |
+| **Brief** | What a finished run leaves for your next solo agent (`.huddle/BRIEF.md`). |
+
+## 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 app` | the dashboard in your browser: live run, history, talk to the agents (or speak) |
+| `huddle view` | watch a run live |
+| `huddle story` | replay the last run |
+| `huddle brief` · `huddle brief off` | what the last run left for your next solo agent · stop pointing CLAUDE.md / AGENTS.md at it |
+| `huddle runs` · `huddle export [run]` | list past runs · save one as a chat (`--level summary\|chat\|full`, `--format md\|html\|json`) |
+| `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

@@ -8,6 +8,8 @@
 
 `npm install -g huddle-cli` → `huddle`
 
+**New here? [QUICKSTART.md](QUICKSTART.md)** — install, first run, teammates, in one page.
+
 </div>
 
 ---
@@ -18,19 +20,21 @@ 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
+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` (works once the GitHub repo is public):
+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` 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.
+**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.
 
@@ -61,9 +65,27 @@ At the `huddle ›` prompt, type what you want built. Huddle plans it into paral
 
 - **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
+- **`--budget=5M`** (typed with the goal, on `huddle join`, or `"budget": "5M"` in `~/.huddle/prefs.json`) caps the tokens a run may use. The plan shows an estimate first. At 90% no new work starts and running tasks finish; at 120% the agents stop. RESULT lists what was left undone. Cached tokens count in full, so the budget runs out before the bill does.
 - 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.
+- **Hand-off brief.** Every run ends with `.huddle/BRIEF.md`: the goal, what was built and by whom, the decisions and why, the contract, open issues and how to continue — from the Room's records, no model call. A short marked block at the top of `CLAUDE.md` and `AGENTS.md` points to it, so a `claude`, `codex` or `cursor` you open on your own afterwards reads it first. It's never committed: a file Huddle creates is git-excluded, and in a file you own the block is lifted out while each run works and put back after. `huddle brief` prints it (`--run n`); `huddle brief off` removes the pointers; `HUDDLE_NO_BRIEF=1` turns it all off.
+- `huddle runs` lists every run in the repo (goal, agents, result, time, tokens, QA). `huddle export [<run>|latest]` saves one as a document you can read or share, like a chat app's history: `--level summary` (result, who did what, decisions, contract, teamwork, cost), `chat` (the default: every message between agents, buddy notes and replies, radar alerts, reviews, QA bugs and Huddle's notes, in time order and in full), or `full` (also each agent's own session per task: what it said, read, ran and wrote, parsed from its log). `--format md|html|json` (HTML is one offline file with an agent filter; JSON is a stable schema, documented in `src/ui/export.ts`). It goes to `.huddle/exports/` unless you pass `--out <file|dir|->`. Likely secrets are redacted unless you pass `--no-redact`.
+
+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
@@ -73,7 +95,7 @@ claude              # open your agents as usual, in as many terminals as you lik
 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).
+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>`.
 

package/dist/adapters/amp.js

@@ -24,7 +24,7 @@ export const ampAdapter = {
     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"] },
+    install: { cmd: "curl -fsSL https://ampcode.com/install.sh | bash", win: null, login: ["amp", "login"] },
     authProbe: {
         cmd: ["amp", "--version"],
         ok: (r) => r.code === 0,

package/dist/adapters/antigravity.js

@@ -17,7 +17,9 @@ export const antigravityAdapter = {
     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",

package/dist/adapters/claude.js

@@ -18,7 +18,12 @@ export const claudeAdapter = {
     // 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" },
+    // https://code.claude.com/docs/en/setup · sign-in: https://code.claude.com/docs/en/cli-reference
+    install: {
+        cmd: "curl -fsSL https://claude.ai/install.sh | bash",
+        win: "irm https://claude.ai/install.ps1 | iex",
+        login: ["claude", "auth", "login"],
+    },
     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 +
@@ -26,7 +31,7 @@ export const claudeAdapter = {
         // 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",
+        fixHint: "run `claude auth login` (or set ANTHROPIC_API_KEY)",
     },
     plug: {
         file: { path: "claude-mcp.json", in: "run-dir" },
@@ -46,12 +51,22 @@ export const claudeAdapter = {
         ],
         cwd,
     }),
+    // `claude -p` with no prompt argument reads it from stdin.
+    stdinPrompt: "",
     usage: claudeUsage,
-    launch: ({ worktree, prompt, model, mcpConfigPath, approvals }) => ({
+    // A PostToolUse hook, loaded with --settings (a file in .huddle/run/, never
+    // the user's settings): after any tool call, `huddle mail --hook` prints
+    // {hookSpecificOutput:{hookEventName:"PostToolUse",additionalContext}} when
+    // a teammate wrote, and nothing otherwise. Schema per
+    // https://code.claude.com/docs/en/hooks; --settings per `claude --help` (2.1.300).
+    mailHook: (command) => ({ hooks: { PostToolUse: [{ matcher: "*", hooks: [{ type: "command", command, timeout: 5 }] }] } }),
+    launch: ({ worktree, prompt, model, mcpConfigPath, approvals, context, hookSettingsPath }) => ({
         cmd: [
             "claude",
             "-p",
             prompt,
+            // The shared screen lives outside the worktree; Read opens its images and PDFs.
+            ...(context ? ["--add-dir", context.dir] : []),
             ...(model ? ["--model", model] : []),
             ...PERMISSIONS[approvals],
             "--mcp-config",
@@ -59,6 +74,7 @@ export const claudeAdapter = {
             // 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",
+            ...(hookSettingsPath ? ["--settings", hookSettingsPath] : []),
             // JSON events so Huddle can count tokens live (logs stay in .huddle/logs)
             "--output-format",
             "stream-json",

package/dist/adapters/codex.js

@@ -26,11 +26,16 @@ export const codexAdapter = {
         cwd,
         usesOutFile: true,
     }),
+    // `codex exec -`: "instructions are read from stdin".
+    stdinPrompt: "-",
     usage: codexUsage,
-    launch: ({ worktree, prompt, model, plug, approvals }) => ({
+    launch: ({ worktree, prompt, model, plug, approvals, context }) => ({
         cmd: [
             "codex",
             "exec",
+            // `codex exec -i/--image <FILE>`: screenshots the planner linked to this task, attached to the prompt.
+            // One flag per file, before the other flags, so the list never swallows the prompt.
+            ...(context?.images ?? []).flatMap((f) => ["--image", f]),
             "--json", // JSON events so Huddle can count tokens live
             ...(model ? ["--model", model] : []),
             "-c",
@@ -43,6 +48,9 @@ export const codexAdapter = {
             // calls under exec. The Plug is Huddle's own server, so pre-approve it.
             "-c",
             `mcp_servers.huddle.default_tools_approval_mode="approve"`,
+            // huddle_ask_user waits up to 90s for the person at the keyboard; Codex's default tool timeout is 60s.
+            "-c",
+            "mcp_servers.huddle.tool_timeout_sec=150",
             // `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

package/dist/adapters/cursor.js

@@ -1,4 +1,4 @@
-import { spawnSync } from "node:child_process";
+import { spawnToolSync } from "../platform.js";
 import { cursorUsage } from "./usage.js";
 /**
  * The model for quick prompt-only answers (council turns, cross-reviews), or
@@ -24,7 +24,7 @@ export function cursorFastModel(list = listCursorModels) {
     catch {
         /* not installed / signed out: keep the default */
     }
-    const ids = out.split("\n").map((l) => /^\s*([\w.-]+)\s+-\s/.exec(l)?.[1]).filter((x) => !!x);
+    const ids = out.split(/\r?\n/).map((l) => /^\s*([\w.-]+)\s+-\s/.exec(l)?.[1]).filter((x) => !!x);
     fastPick = { model: ids.find((id) => /^composer-[\d.]+$/.test(id)) };
     return fastPick.model;
 }
@@ -33,7 +33,7 @@ export function resetCursorFastModel() {
     fastPick = undefined;
 }
 function listCursorModels() {
-    const r = spawnSync("cursor-agent", ["--list-models"], { encoding: "utf8", timeout: 15_000 });
+    const r = spawnToolSync(["cursor-agent", "--list-models"], { encoding: "utf8", timeout: 15_000 });
     return r.status === 0 ? r.stdout : "";
 }
 // Cursor CLI (cursor-agent) — headless coding agent. Personal, team or SSO
@@ -47,7 +47,12 @@ export const cursorAdapter = {
     prefers: ["in-editor-edits", "frontend", "quickfix"],
     models: { orchestrator: "", worker: "", fast: "", reviewer: "" },
     accountNote: "your Cursor account (SSO handled by cursor-agent itself)",
-    install: { cmd: "curl https://cursor.com/install -fsS | bash", login: ["cursor-agent", "login"] },
+    // https://cursor.com/docs/cli/installation (native Windows: PowerShell)
+    install: {
+        cmd: "curl https://cursor.com/install -fsS | bash",
+        win: "irm 'https://cursor.com/install?win32=true' | iex",
+        login: ["cursor-agent", "login"],
+    },
     authProbe: {
         cmd: ["cursor-agent", "status"],
         ok: (r) => r.code === 0 && !/not logged in/i.test(r.stdout + r.stderr),
@@ -64,11 +69,13 @@ export const cursorAdapter = {
         return { cmd: ["cursor-agent", "-p", prompt, "--mode", "ask", "--trust", ...(m ? ["--model", m] : [])], cwd };
     },
     usage: cursorUsage,
-    launch: ({ worktree, prompt, model, approvals }) => ({
+    launch: ({ worktree, prompt, model, approvals, context }) => ({
         cmd: [
             "cursor-agent",
             "-p",
             prompt,
+            // No image flag on cursor-agent: the shared screen's folder, so its tools can open items by path.
+            ...(context ? ["--add-dir", context.dir] : []),
             ...(model ? ["--model", model] : []),
             // headless: trust the worktree and the Plug without prompting
             "--trust",

package/dist/adapters/custom.js

@@ -28,7 +28,7 @@ export const USAGE_PARSERS = {
     qwen: qwenUsage,
 };
 const SPEC_KEYS = new Set([
-    "id", "bin", "launch", "vendor", "approvals", "ask", "askOutFile", "plug", "env", "install", "login", "loginNote",
+    "id", "bin", "launch", "vendor", "approvals", "ask", "askOutFile", "plug", "env", "install", "installWin", "login", "loginNote",
     "auth", "usage", "roles", "prefers", "models", "accountNote", "homepage", "optional", "$comment",
 ]);
 const ROLES = new Set(["orchestrator", "worker", "reviewer", "fast"]);
@@ -124,6 +124,8 @@ export function validateSpec(raw) {
         errs.push(`"login" must be an array of strings`);
     if (s.install !== undefined && typeof s.install !== "string")
         errs.push(`"install" must be a shell command string`);
+    if (s.installWin !== undefined && typeof s.installWin !== "string")
+        errs.push(`"installWin" must be a PowerShell command string`);
     if (s.auth !== undefined) {
         const a = s.auth;
         if (!a || typeof a !== "object")
@@ -216,7 +218,7 @@ export function specToAdapter(spec, source) {
         roles: spec.roles ?? (spec.ask ? ["worker", "reviewer"] : ["worker"]),
         prefers: spec.prefers ?? [],
         models: { orchestrator: "", worker: "", fast: "", reviewer: "", ...spec.models },
-        install: { cmd: spec.install ?? "", login: spec.login, loginNote: spec.loginNote },
+        install: { cmd: spec.install ?? "", ...(spec.installWin !== undefined ? { win: spec.installWin } : {}), login: spec.login, loginNote: spec.loginNote },
         authProbe: {
             cmd: authCmd,
             ok: (r) => r.code === 0 && !(fail && fail.test(r.stdout + r.stderr)),

package/dist/adapters/droid.js

@@ -34,6 +34,7 @@ export const droidAdapter = {
     optional: true,
     install: {
         cmd: "curl -fsSL https://app.factory.ai/cli | sh",
+        win: "irm https://app.factory.ai/cli/windows | iex",
         login: ["droid"],
         loginNote: "Droid signs you in from its own screen — once you're in, press ctrl-c to come back to Huddle",
     },

package/dist/adapters/goose.js

@@ -37,6 +37,8 @@ export const gooseAdapter = {
     optional: true,
     install: {
         cmd: "curl -fsSL https://github.com/aaif-goose/goose/releases/download/stable/download_cli.sh | CONFIGURE=false bash",
+        // Windows has a download_cli.ps1 that saves itself into the current folder: point at the docs instead.
+        win: null,
         login: ["goose", "configure"],
         loginNote: "pick a provider and paste its key in goose's own setup — Huddle never sees it",
     },

package/dist/adapters/index.js

@@ -2,7 +2,7 @@
 // uses to decide who's in the roster for a session. Because we only ever ask
 // "installed?" and "authed?", expiring subscriptions and account swaps are a
 // non-event: a failing probe just drops that agent, the session runs on.
-import { execFile, execFileSync } from "node:child_process";
+import { spawn } from "node:child_process";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
 import { claudeAdapter } from "./claude.js";
@@ -18,6 +18,7 @@ import { qwenAdapter } from "./qwen.js";
 import { droidAdapter } from "./droid.js";
 import { kiroAdapter } from "./kiro.js";
 import { loadAgentsFiles } from "./custom.js";
+import { onPath, spawnToolSync, toolCommand } from "../platform.js";
 export const ADAPTERS = [
     claudeAdapter,
     codexAdapter,
@@ -80,23 +81,18 @@ export function registerAdapter(adapter) {
     else if (adapter.id !== "gemini")
         LEGACY.delete(adapter.id);
 }
-function onPath(bin) {
-    try {
-        execFileSync(process.platform === "win32" ? "where" : "which", [bin], { stdio: "pipe" });
-        return true;
-    }
-    catch {
-        return false;
-    }
+/** Mark the agents you skipped, keeping what the probe found in `was`. */
+export function applySkips(results, skip) {
+    const s = new Set(skip);
+    return results.map((r) => s.has(r.adapter.id) && r.state !== "skipped" ? { ...r, state: "skipped", was: r.state, detail: `skipped by you — huddle agents use ${r.adapter.id}` } : r);
+}
+/** Undo applySkips for `ids` — `--agents=` on a run overrides a skip for that run. */
+export function unskip(results, ids) {
+    return results.map((r) => (r.state === "skipped" && r.was && ids.includes(r.adapter.id) ? { ...r, state: r.was, was: undefined } : r));
 }
 function run(cmd) {
-    try {
-        const stdout = execFileSync(cmd[0], cmd.slice(1), { encoding: "utf8", stdio: "pipe", timeout: 8000 });
-        return { code: 0, stdout, stderr: "" };
-    }
-    catch (e) {
-        return { code: e?.status ?? 1, stdout: e?.stdout?.toString() ?? "", stderr: e?.stderr?.toString() ?? "" };
-    }
+    const r = spawnToolSync(cmd, { encoding: "utf8", stdio: "pipe", timeout: 8000 });
+    return { code: r.error ? 1 : (r.status ?? 1), stdout: String(r.stdout ?? ""), stderr: String(r.stderr ?? "") };
 }
 /** Detect + auth-probe a single adapter. */
 export function probe(adapter) {
@@ -109,9 +105,21 @@ export function probe(adapter) {
     }
     return { adapter, state: "ready", detail: `${adapter.vendor} · ${adapter.accountNote ?? "ready"}` };
 }
-function runAsync(cmd) {
+function runAsync(cmd, timeoutMs = 8000) {
     return new Promise((resolve) => {
-        execFile(cmd[0], cmd.slice(1), { encoding: "utf8", timeout: 8000 }, (err, stdout, stderr) => resolve({ code: err ? (typeof err.code === "number" ? err.code : 1) : 0, stdout, stderr }));
+        const t = toolCommand(cmd);
+        const child = spawn(t.file, t.args, { stdio: ["ignore", "pipe", "pipe"], windowsVerbatimArguments: t.verbatim });
+        let stdout = "";
+        let stderr = "";
+        child.stdout.on("data", (d) => (stdout += d));
+        child.stderr.on("data", (d) => (stderr += d));
+        const timer = setTimeout(() => child.kill(), timeoutMs);
+        const done = (code) => {
+            clearTimeout(timer);
+            resolve({ code, stdout, stderr });
+        };
+        child.on("error", () => done(1));
+        child.on("close", (code) => done(code ?? 1));
     });
 }
 /** Non-blocking probe, so the welcome screen can animate while agents connect. */
@@ -125,6 +133,24 @@ export async function probeAsync(adapter) {
     }
     return { adapter, state: "ready", detail: `${adapter.vendor} · ${adapter.accountNote ?? "ready"}` };
 }
+/**
+ * The install command for this platform, or null when there's no native one.
+ * An `npm install -g …` works everywhere; curl-pipe-bash doesn't on Windows.
+ */
+export function installCommand(a, platform = process.platform) {
+    if (platform !== "win32")
+        return a.install.cmd || null;
+    if (a.install.win !== undefined)
+        return a.install.win;
+    return /^npm (install|i) /.test(a.install.cmd) ? a.install.cmd : null;
+}
+/** What to say when installCommand() is null. */
+export function noInstallHint(a, platform = process.platform) {
+    const docs = a.homepage ? `see ${a.homepage}` : `install ${a.bin} the way its docs say`;
+    return platform === "win32" && a.install.cmd ? `no Windows installer — ${docs}, or use it from WSL` : docs;
+}
+/** The sign-in command as one line, for messages ("codex login"). */
+export const loginLine = (a) => (a.install.login ? a.install.login.join(" ") : null);
 /** Probe the whole roster. */
 export function probeAll() {
     return ADAPTERS.map(probe);

package/dist/adapters/kiro.js

@@ -23,7 +23,7 @@ export const kiroAdapter = {
     accountNote: "your Kiro login",
     homepage: "https://kiro.dev/docs/cli/",
     optional: true,
-    install: { cmd: "curl -fsSL https://cli.kiro.dev/install | bash", login: ["kiro-cli", "login"] },
+    install: { cmd: "curl -fsSL https://cli.kiro.dev/install | bash", win: null, login: ["kiro-cli", "login"] },
     authProbe: {
         cmd: ["kiro-cli", "whoami"],
         ok: (r) => r.code === 0 && !/not logged in/i.test(r.stdout + r.stderr),

package/dist/adapters/opencode.js

@@ -35,7 +35,7 @@ export const opencodeAdapter = {
     accountNote: "your OpenCode providers",
     homepage: "https://opencode.ai/docs/",
     optional: true,
-    install: { cmd: "curl -fsSL https://opencode.ai/install | bash", login: ["opencode", "auth", "login"] },
+    install: { cmd: "curl -fsSL https://opencode.ai/install | bash", win: "npm install -g opencode-ai", login: ["opencode", "auth", "login"] },
     authProbe: {
         cmd: ["opencode", "--version"],
         ok: (r) => r.code === 0,