huddle-cli 0.1.0 → 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/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

@@ -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.
 
@@ -64,6 +68,21 @@ At the `huddle ›` prompt, type what you want built. Huddle plans it into paral
 - 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
@@ -73,7 +92,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",

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,

package/dist/attach/connect.js

@@ -35,7 +35,10 @@ const CLAUDE_ALLOW = "mcp__huddle";
 export function livePlug(repo, agent) {
     return { command: process.execPath, args: [CLI_PATH, "plug"], env: { HUDDLE_LIVE: "1", HUDDLE_AGENT_ID: agent, HUDDLE_REPO: repo } };
 }
-export const guardCommand = () => `"${process.execPath}" "${CLI_PATH}" guard`;
+// Quoted (paths with spaces: C:\Users\Some Name\…) and with forward slashes on
+// Windows, which node accepts and which survive both bash and cmd/PowerShell.
+const hookPath = (p) => (process.platform === "win32" ? p.replace(/\\/g, "/") : p);
+export const guardCommand = () => `"${hookPath(process.execPath)}" "${hookPath(CLI_PATH)}" guard`;
 /** What `huddle connect` would write for one agent. */
 export function wiresFor(adapter, repo, opts = {}) {
     const plug = livePlug(repo, adapter.id);

package/dist/attach/guard.js

@@ -14,13 +14,17 @@
 import { execFileSync } from "node:child_process";
 import { liveCall, mainRoot, readLive } from "./live.js";
 /** This process's ancestors (the hook's shell, then Claude itself, …). */
-export function ancestors(max = 8) {
+export function ancestors(max = 8, platform = process.platform) {
     const out = [];
+    // Windows has no `ps`: one PowerShell call lists every process's parent.
+    const parents = platform === "win32" ? windowsParents() : null;
     let pid = process.ppid;
     for (let i = 0; i < max && pid > 1; i++) {
         out.push(pid);
         try {
-            pid = Number(execFileSync("ps", ["-o", "ppid=", "-p", String(pid)], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim());
+            pid = parents
+                ? (parents.get(pid) ?? 0)
+                : Number(execFileSync("ps", ["-o", "ppid=", "-p", String(pid)], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim());
         }
         catch {
             break;
@@ -28,6 +32,21 @@ export function ancestors(max = 8) {
     }
     return out;
 }
+/** pid → parent pid, from `Get-CimInstance Win32_Process`. Empty if that fails. */
+export function windowsParents(run = () => execFileSync("powershell.exe", ["-NoProfile", "-Command", "Get-CimInstance Win32_Process | ForEach-Object { \"$($_.ProcessId) $($_.ParentProcessId)\" }"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: 4000, windowsHide: true })) {
+    const m = new Map();
+    try {
+        for (const l of run().split(/\r?\n/)) {
+            const [a, b] = l.trim().split(/\s+/).map(Number);
+            if (a > 0 && b >= 0)
+                m.set(a, b);
+        }
+    }
+    catch {
+        /* no PowerShell: the guard still works, just without pid matching */
+    }
+    return m;
+}
 async function readStdin() {
     let s = "";
     for await (const c of process.stdin)

package/dist/attach/live.js

@@ -103,7 +103,7 @@ export async function pingLive(st) {
         return false;
     }
 }
-function ensureHuddleDir(root) {
+export function ensureHuddleDir(root) {
     const f = liveFiles(root);
     fs.mkdirSync(path.dirname(f.log), { recursive: true });
     const gi = path.join(f.dir, ".gitignore");
@@ -142,6 +142,7 @@ export async function ensureLive(root, timeoutMs = 8000) {
         const child = spawn(process.execPath, [CLI_PATH, "up", "--serve"], {
             cwd: root,
             detached: true,
+            windowsHide: true, // detached on Windows = a new console window, unless hidden
             stdio: ["ignore", out, out],
             env: { ...process.env, HUDDLE_LIVE_ROOT: root },
         });
@@ -217,6 +218,9 @@ export async function stopLive(root) {
     process.kill(st.pid, "SIGTERM");
     for (let i = 0; i < 50 && alive(st.pid); i++)
         await new Promise((r) => setTimeout(r, 100));
+    // On Windows "SIGTERM" is TerminateProcess: the daemon's handler never runs, so tidy up for it.
+    if (!alive(st.pid))
+        fs.rmSync(liveFiles(root).state, { force: true });
     return true;
 }
 //# sourceMappingURL=live.js.map