huddle-cli 0.1.1 → 0.1.3

package/CHANGELOG.md

@@ -1,5 +1,43 @@
 # 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).

package/QUICKSTART.md

@@ -53,7 +53,21 @@ One-shot instead of the prompt: `huddle join "build a REST API for todos with te
 **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):
+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
@@ -64,8 +78,14 @@ huddle view            # live: who's doing what, messages, merges
 ```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.
@@ -77,6 +97,16 @@ Everyone installs Huddle as in step 1, on their own machine, with their own agen
 
 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 |
@@ -86,8 +116,11 @@ Not on the same Wi-Fi? Install [Tailscale](https://tailscale.com) on both machin
 | `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 |

package/README.md

@@ -65,6 +65,7 @@ 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
 
@@ -78,6 +79,8 @@ At the `huddle ›` prompt, type what you want built. Huddle plans it into paral
 - **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.
 

package/dist/adapters/codex.js

@@ -48,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/app/live.js

@@ -0,0 +1,142 @@
+// The bridge between a run and the dashboard (`huddle app`), which may be
+// another process: the run can start in a terminal and be watched, answered
+// and stopped from the browser, or start from the browser itself.
+//
+//   .huddle/live.json   the run's live state, rewritten every second: phase,
+//                       narrator, each agent's task / % / tokens, the
+//                       council so far, a question waiting on you
+//   .huddle/inbox/      what the dashboard sends the run: your answer to a
+//                       question, a line for the agents, stop. One JSON file
+//                       each; the run takes them within a second
+//   .huddle/app.json    the dashboard is open (pid, url): a run with no
+//                       terminal still asks you its questions there
+//
+// Files, not a socket: the council runs before the Room exists, and either
+// side may start first. Everything here is local to the repo's .huddle/.
+import fs from "node:fs";
+import path from "node:path";
+const dir = (root) => path.join(root, ".huddle");
+export const livePath = (root) => path.join(dir(root), "live.json");
+export const inboxDir = (root) => path.join(dir(root), "inbox");
+export const appFile = (root) => path.join(dir(root), "app.json");
+/** Is `pid` a process on this machine? */
+export function alive(pid) {
+    if (!Number.isInteger(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (e) {
+        return e?.code === "EPERM"; // exists, owned by someone else
+    }
+}
+/** Write atomically: a reader never sees half a file. */
+function writeJson(file, value) {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    const tmp = `${file}.${process.pid}.tmp`;
+    fs.writeFileSync(tmp, JSON.stringify(value));
+    fs.renameSync(tmp, file);
+}
+function readJson(file) {
+    try {
+        return JSON.parse(fs.readFileSync(file, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+export function writeLive(root, s) {
+    try {
+        writeJson(livePath(root), s);
+    }
+    catch {
+        /* a read-only or vanished .huddle: the dashboard just won't see this run */
+    }
+}
+/** The run in progress, or null: none, finished, or its process is gone (a crash, a kill -9). */
+export function readLive(root) {
+    const s = readJson(livePath(root));
+    if (!s || s.done || !alive(s.pid))
+        return null;
+    return s;
+}
+let seq = 0;
+/** The dashboard's side: queue a command for the run. */
+export function postCommand(root, c) {
+    const d = inboxDir(root);
+    fs.mkdirSync(d, { recursive: true });
+    // Sorted by name = oldest first: two commands in one millisecond keep their order (seen on Linux).
+    const name = `${String(Date.now()).padStart(15, "0")}-${String(seq++).padStart(6, "0")}-${process.pid}.json`;
+    writeJson(path.join(d, name), c);
+}
+/** The run's side: every queued command, oldest first, each taken once. */
+export function takeCommands(root) {
+    const d = inboxDir(root);
+    let names = [];
+    try {
+        names = fs.readdirSync(d).filter((n) => n.endsWith(".json")).sort();
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const n of names) {
+        const f = path.join(d, n);
+        const c = readJson(f);
+        try {
+            fs.unlinkSync(f);
+        }
+        catch {
+            continue; // another taker got it
+        }
+        if (c && typeof c === "object" && ["answer", "say", "stop"].includes(c.type))
+            out.push(c);
+    }
+    return out;
+}
+/** Commands left from an earlier run must not steer this one. */
+export function clearCommands(root) {
+    try {
+        for (const n of fs.readdirSync(inboxDir(root)))
+            fs.rmSync(path.join(inboxDir(root), n), { force: true });
+    }
+    catch {
+        /* no inbox yet */
+    }
+}
+export function writeAppInfo(root, info) {
+    writeJson(appFile(root), info);
+}
+export function clearAppInfo(root) {
+    const cur = readJson(appFile(root));
+    if (cur?.pid === process.pid)
+        fs.rmSync(appFile(root), { force: true });
+}
+/** The dashboard that's open on this repo, if any. */
+export function openApp(root) {
+    const a = readJson(appFile(root));
+    return a && alive(a.pid) ? a : null;
+}
+/** The run's WHAT YOU GOT write-up, kept for the dashboard: .huddle/reports/<session>.md */
+const reportFile = (root, session) => path.join(dir(root), "reports", `${session.replace(/[^\w-]/g, "_")}.md`);
+export function saveReport(root, session, text) {
+    try {
+        fs.mkdirSync(path.dirname(reportFile(root, session)), { recursive: true });
+        fs.writeFileSync(reportFile(root, session), text);
+    }
+    catch {
+        /* the terminal had it; the dashboard just won't */
+    }
+}
+export function readReport(root, session) {
+    if (!session)
+        return null;
+    try {
+        return fs.readFileSync(reportFile(root, session), "utf8");
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=live.js.map