squad

Draft the best AI model for every kind of work — then cast that team into the CLI you already use, as native agents. One team, your subscriptions, $0 by default.

No single model wins everything. squad keeps an honestly-sourced benchmark board in your terminal, lets you pick a model per category of work, and then casts the team into a real project: per-category agents in your host's native format, a captain protocol with an append-only ledger, cross-vendor verification, and a second-opinion fallback — for Claude Code, Codex, or opencode.

 ◆ SQUAD v0.1.0                                           team ★ 100 · 17/17 · burn: heavy plan
 ✓ claude  ✓ chatgpt  ✓ OR                                                             1–3/6 ←→
 ──────────────────────────────────────────────────────────────────────────────────────────────
  some scores sourced >30d ago — t refreshes live rows; squad refresh lists stale static rows

   CATEGORY                 BENCHMARK                   Fable5 ?    Opus5 ?   GPT5.5 ✓
 ─ Independent index · live ────────────────────────────────────────────────────────────
   Intelligence             AA Intelligence Index          62.1     ◉ 63.1       56.3
   Coding                   AA Coding Index                76.5      ◉ 78        74.9
   Agentic work             AA Agentic Index             ◉ 56.6       59.2       47.4
 ─ Coding & agents ─────────────────────────────────────────────────────────────────────
   Agentic coding           SWE-Bench Pro                ◉ 80.3     ◦ 79.2       58.6
   Terminal / CLI           Terminal-Bench 2.1           ◉ 88.0*     no data     83.4
   Tool use                 AutomationBench                17.4     ◉ 26.0       12.9

  ◉ pick · ◦ value · ◯ provisional · * vendor · vendor data 2026-07-13

(real squad --static output, trimmed)

Quickstart

git clone https://github.com/HamadYMarafi/squadcli && cd squadcli
npm install        # builds dist/ via the prepare script
npm link           # puts `squad` on your PATH

Then:

squad

First run opens a 30-second wizard. Press ⏎ through the defaults:

1. ⏎ Best free team ($0) — drafted from what's detected on your machine (Claude plan, ChatGPT plan, OpenRouter :free models), previewed with every score's source, saved.
2. ⏎ Use it here (or the ✚ new-folder row) — casts the team into a project.
3. ⏎ Start working — opens your CLI in that folder with the team live.

Want to watch one first? squad demo streams a full squad run end to end on your Claude plan (~3 min, results go to a scratch file, never the evidence ledger). Note: the demo replays a task from the in-repo research gauntlet and expects this repo at ~/Desktop/Ai/squadcli — the one piece that assumes the author's layout.

The rule this project lives by

squad never computes, estimates, or invents a number.

• Every static cell in data/scores.json carries a source key that resolves to a URL (vendor model cards, Terminal-Bench, llm-stats, BenchLM, …) and the date it was compiled. Vendor-reported figures are flagged *.
• The "Independent index" rows are fetched live (Artificial Analysis via OpenRouter, BenchLM), cached, and shown with their fetch age.
• Staleness is always shown, never hidden: the board banners some scores sourced >30d ago, the footer prints the data date, and squad refresh lists every static row by sourced date, oldest first — the stale ones need a manual re-check. Nothing is scraped or made up.
• No published score → the cell stays blank ("no data"). A model whose exact version can't be pinned gets no scores at all.

The same rule applies to squad's own claims about itself — see Measured results below, negative findings included.

How a cast works

squad apply (or "Use it here") writes the team into a project in the host's native format — and squad unapply removes exactly what apply wrote, byte-restoring anything hand-written (a non-empty ledger is user data and survives).

host	agents	captain block	enforcement
Claude Code (default)	.claude/agents/squad-<category>.md	CLAUDE.md	enforced — hooks in .claude/settings.json
Codex	dispatch commands in the captain block	AGENTS.md	advisory — no hard hooks (probed 0.145: project hooks are silently skipped, so squad ships none)
opencode	.opencode/agent/ + opencode.json	AGENTS.md	advisory — hooks unprobed on 1.18.18; or-rail picks bill OpenRouter and are labeled so

The captain is your main loop; the specialists are real agents on the models you drafted. The captain block (generated — this is a real excerpt):

## CLASSIFICATION PROTOCOL

Before each substantive task, classify it — append ONE JSON line to `.squad/ledger.jsonl` via a shell echo:

    echo '{"t":"class","task":"<short>","mode":"solo","agent":"","ts":"'"$(date -u +%Y-%m-%dT%H:%M:%SZ)"'"}' >> .squad/ledger.jsonl

- `mode` is `"solo"` or `"delegate"`; `agent` names the `squad-*` specialist for delegate, empty for solo.
- Solo is legal and the DEFAULT for trivial or deep single-shot work (cost-ladder rung 1).
- Classify BEFORE touching files: the pre-edit hook denies every edit until a class line exists in the ledger.
- Delegate for decomposable or specialist-shaped work — and then actually dispatch: the
  pre-edit hook denies edits until the DECLARED specialist has been dispatched (a different agent does not count).

On the Claude Code host three hooks enforce the protocol (python3 stdlib, fail-open — they can warn-and-allow, never brick a session): classify-before-edit, a model-pin guard (a captain passing its own model: param on a dispatch is denied — the cast binding decides), and a brief floor (thin delegation briefs are denied; every dispatch carries goal, files, constraints, done-criteria). On the other two hosts the same protocol ships as text and is honestly labeled advisory.

VERIFICATION PROTOCOL — cross-vendor review. Same-family review caught zero bugs in our measurements, so when the codex CLI is present, delegated work isn't done until an independent different-vendor reviewer (top codex-rail model by sourced coding score) has hunted it: read-only sandbox, verdict + file:line defects, maximum two rounds. The brief — task, full diff including untracked files, check output — is fed as a file on stdin, never argv: a $(…) inside reviewed code must never touch your shell, and big diffs blow ARG_MAX. No codex CLI → the section honestly says no verifier exists.

SECOND OPINION — your fallback model. When attempt A is genuinely stuck (checks still fail after a fix attempt, or verification failed round 2), the captain dispatches the model you drafted as second opinion (squad cast second-opinion) into an isolated worktree, then judges objectively: run the task's own checks in both trees, sole passer wins, no third model. Never triggered early, never auto-picked.

You stay sovereign

• Every seat is user-picked — the wizard presets, every swap, the second-opinion fallback. squad never auto-selects a paid model.
• Subscriptions and free models are the default world. Pay-as-you-go models bind only when you explicitly draft them, and every paid dispatch line in the generated protocol carries a money warning (⚠ this dispatch bills your pay-as-you-go account).
• A launch line that binds OpenRouter models prints your live OpenRouter balance on quit, next to a plain "this is real money" notice.

Measured results (the honest section)

Some research tasks ran against two private repositories. Their task definitions, seeds, checks, and the v1 result ledgers are omitted from the public tree; the pre-registered verdicts and the complete v2 result rows ship here in full.

This project killed its own v1 hypothesis and keeps the corpse in the repo as evidence. Every number below is in a committed file.

v1 — same-family squads LOSE to a strong solo. A pre-registered gauntlet (20 tasks × 5 configs, 100 clean rows) ended in a KILL verdict by its own pre-registered gates: squad won 3/8 decomposable tasks (at/under the 40% kill line), the verification config caught zero failures no solo caught, and delegation cost 1.48× wall time for zero pass-rate gain on ordinary tasks. One real parallelism win existed (2.1× on the cleanest decomposable task). Frozen in gauntlet/VERDICT.md.

v2 — the shipped product (this cast + protocol + hooks) vs the best solo. Config B is the strongest solo arm: same top model plus a forced second self-review pass (gauntlet/run.sh). Head-to-head, four benchmark tasks, sub rail (gauntlet/results-v2smoke.jsonl, 2026-08-15):

task	squad v2	best solo (B)	quality	speed
G12 rename-across-repo	✅ 54s	✅ 128s	tie	v2 2.4× faster
H03 14-module ops-audit suite	✅ 523s	✅ 628s	tie	v2 faster
H01 CLI stats tool	❌ 385s	❌ 697s	tie (both fail)	v2 faster
H13 dual-venue tape kit	✅ 1806s	✅ 2539s*	tie	v2 faster

Quality 3/4 vs 3/4 — a tie. Wall clock: v2 faster on all four pairs. (*B's better of two H13 runs; its other hit max-turns at 3429s before passing on a second pass.)

A replication pass (results-v2verify.jsonl) repeated the 3/4 pass pattern — G12 and H13 again faster, the H01 fail slower this time (773s), and H03 much slower (1285s) for the best possible reason:

The cross-vendor verifier caught a real money-math bug the benchmark's own checker missed. In that H03 run the codex-rail reviewer returned VERDICT: FAIL twice, flagging a P&L average-cost guard in ledger_audit.py that returned 333.33 where the spec computes 166.67 — an adversarial sequence the task's own checks never probe. The row still "passed" the benchmark; the verifier was right anyway. Ledger and verdict output are preserved in that run's workdir (path recorded in the results row).

What stayed unbeaten. H01 and H02 have never passed for any config — solo or squad, v1 or v2, including three dedicated crack attempts (results-v2crack.jsonl). Both are spec-interpretation failures (H01: the checker wants ▁ for zero sparkline bins; every model ever tested rendered them another way) — invisible from inside a session, which no amount of same-session verification fixes. That analysis is why the roadmap has rejection-triggered second opinions and a pre-implementation spec audit.

Pay-as-you-go routing (bring your own router)

Drafting an OpenRouter model prints a launch line that binds each non-subscription pick onto Claude Code's own standard model resolver:

ANTHROPIC_BASE_URL=<your proxy> ANTHROPIC_DEFAULT_SONNET_MODEL=x-ai/grok-4.5 claude

The ANTHROPIC_DEFAULT_*_MODEL vars are Claude Code's built-in tier resolver — squad just fills them with your drafted slugs. The one piece you bring is ANTHROPIC_BASE_URL: any OpenRouter-compatible proxy that speaks the Anthropic API on the front and OpenRouter on the back (several open-source ones exist). squad prints the tier→model table, gates every candidate through live eligibility checks (squad doctor probes the wiring), and warns about money — it never ships a proxy and never auto-selects a paid model.

Requirements

• macOS or Linux. macOS is what's battle-tested — every measurement above ran there. Linux should work and is honestly untested.
• Node ≥ 22, python3 (the enforcement hook, stdlib only).
• claude CLI (Claude Code) — the default host.
• codex CLI (optional) — unlocks the Codex host and the cross-vendor verifier.
• opencode CLI (optional) — unlocks the opencode host.
• OPENROUTER_API_KEY (optional) — live independent score rows, live prices, free-model eligibility. jq + git for squad demo.

Commands

squad                 home screen: board, use-it-here, swap, doctor, bench, refresh,
                      wizard, demo (first run opens the wizard)
squad board           straight to the draft board
squad apply [dir]     cast the squad into a project (--host codex|opencode)
squad unapply [dir]   remove exactly what apply wrote
squad cast <category> 3-second single-role swap; `squad cast second-opinion` sets your fallback
squad bench [rail]    the cost ladder + what delegating MEASURABLY cost (says so when it can't)
squad doctor          probe every external coupling live
squad refresh         refresh live caches, list stale static rows oldest first
squad demo            watch one squad run end to end (~3 min)

Roadmap

• Local models — ollama / LM Studio seats via the opencode host.
• Rejection-triggered attempt B — a rejected result auto-offers the second opinion.
• Spec audit — a pre-implementation pass targeting the H01/H02 failure class.
• Gemini rail, npm publish.

License

MIT © 2026 Hamad Marafi