# huddle

> **One session. Many AI brains. Supervised.**
> `@codex`, `@gemini`, `@opencode` — answer inline in the agent session you're already in. And when one of them works, another one checks the work.

You're in opencode. You want a second brain on a diff, a second opinion on an architecture call, a worker to fix the file while a supervisor verifies it did what you asked. Today you switch terminals and copy-paste context. Huddle puts every agent at **one table**: you @mention, that agent answers in your conversation, every agent shares the same transcript — and any agent can audit any other's work.

![huddle demo](demo/demo.gif)

```text
you:     @codex what does add(2,3) in calc.ts return? Just the value.
codex:   5
you:     @gemini check what codex did — was it right?
gemini:  VERDICT: ON-SPEC — add(2,3) returns 5, matching the request exactly
```

That second exchange is the point of huddle: **AI watches AI**. A supervisor agent audits a worker's run against your task and returns a verdict with findings — not vibes.

## Install

```bash
huddle init --host opencode --guests codex,gemini
```

Detects your installed agents, writes the MCP config into your host, drops the routing skill into your project. Then just start your host and `@mention` a guest.

**Requires:** Node ≥ 22 (native TypeScript + SQLite, **zero npm dependencies**) and one MCP-capable host (opencode). Guests just need their CLIs installed and logged in — huddle never touches your auth or billing.

## Any agent. Any model. Your combo.

- **Guests:** any agent with a terminal CLI — ships with codex, gemini and opencode adapters; anything else is a 15-line JSON manifest ([docs/ADAPTER.md](docs/ADAPTER.md)). PR yours in.
- **Models:** per-call override — `@codex[o4-mini]`, `@gemini[gemini-3-flash]`. Free, paid, or local: it's your CLI, your keys, your choice. `models` lists every catalog with free/paid/local tiers.
- **Combos:** every user picks their own host + guests at init. No hardcoded pairs.

## The tools (MCP)

| Tool | What it does |
|---|---|
| `ask` | Hand a task to a guest — its answer returns inline |
| `review` | Peer review: one guest critiques another's last answer |
| `check` | **AI watches AI:** supervisor audits a worker's run vs the task — ON-SPEC / OFF-SPEC / PARTIAL with findings |
| `history` | Shared transcript tail — every agent sees the same conversation |
| `roster` | Who's at the table + models |
| `models` | Every agent's model catalog (free/paid/local) |

## Advise by default. Act on command.

- `@codex review this` → **advise mode**: guest reads your project with full agentic context (spawned in your working directory), answers, suggests diffs. Read-only by adapter flag.
- `@codex! fix it` → **act mode** (`!`): the guest edits files directly, sandboxed to the workspace. Git guards record the diff after every guest turn, and one command recovers:

```bash
huddle undo   # reset the working tree to HEAD — guest edits gone
```

## Security

Zero npm dependencies — Node built-ins only, nothing to audit but us. Args-array execution (never a shell), binary allowlist (only registered adapters run), secret redaction on every transcript write, per-call timeout kill, per-session spawn caps, delimited guest output. Full model in [SECURITY.md](SECURITY.md). Windows-native: npm `.cmd` shims are resolved to their underlying scripts and spawned shell-free.

## Verified working (real run, 2026-09-09)

From `huddle history` — actual bus transcript, all free models:

```text
[07:41:23] codex(gpt-5.6-terra) answer: In ordinary arithmetic, yes—though programming
           languages can produce different results through overflow, floating point…
[07:45:20] gemini(gemini-3-flash) answer: I agree with codex because dynamic type
           coercion (such as '2' + 2 evaluating to '22')…
[07:46:11] gemini(gemini-3-flash) answer: VERDICT: ON-SPEC FINDINGS: 1. Position Provided…
[08:20:06] codex(gpt-5.6-terra) answer: 5          ← via opencode host, inline
```

## FAQ

**Does huddle itself need an agent?** The host does (opencode — anything MCP-capable). Guests just need a CLI. A standalone `huddle chat` TUI (you as the host, zero agents required) is on the v1.5 roadmap.

**Does it touch my API keys or billing?** Never. It invokes your installed CLIs; their own auth and models carry over.

**How is this different from parallel multi-agent routers?** Those dispatch tasks to agents working in parallel and synthesize one answer. Huddle is turn-based and conversational: agents share one transcript, talk in sequence, review and audit each other — a session, not a dispatch queue.

## Roadmap

- v0.3 — model pinning in config, `review` across sessions
- v1.5 — `huddle chat` standalone TUI (human host), during-run drift guard
- v2 — live interjection (supervisor course-corrects a worker mid-run)

## License

MIT