banditAI agents do the work.
The factory makes it evidence.
bandit runs your existing coding agents — opencode, Claude Code, Codex, pi — on a kanban board with a mechanical verify gate, a consult thread that argues before it executes, and a ledger that remembers what actually worked.
01 / AGENT INSTALL (RECOMMENDED)
Let the agent install it.
Setup involves harness selection, model routing, and loop verification — an agent reads the full guide and walks every step without fat-fingering paths. Paste this into Claude Code, opencode, Codex, or any agent session:
Install and configure bandit by following the instructions here: https://raw.githubusercontent.com/wisbech/bandit/main/docs/installation.md # the guide's For-LLM-Agents section then walks the agent through: # step 0 ask you: local ollama, cloud harness, or verify an existing .bandit/ # step 1 check prerequisites (bun, opencode, ollama reachability) # step 2 clone, build, put bin/ on PATH # step 3 bandit init + bandit doctor (exit 1 on any failed check — the agent # fixes the failing check's note and re-runs; every fix is idempotent) # step 4 write .bandit/config.json (transport, model, maxRetries) # step 5 seed a hello-world card, bandit start --once, read the dossier back # step 6 hand you the command list — board / card / watch / chat / events
Why delegate the install
Subscription detection, model selection across agents and categories, provider auth, config migration — humans fat-finger these; the agent verifies with bandit doctor after each step.
Local models, zero cloud tokens
The default config drives opencode through ollama (ollama/glm-5.3-flash:cloud). The full loop — actor, gate, grader, consults — runs without a single API key. Or point the transport at Claude/Codex via ACP and use your existing login.
02 / MANUAL INSTALL
Five commands, one dependency.
Bun ≥ 1.4 is the only requirement. Your agents bring their own auth — bandit never sees or stores provider keys.
git clone https://github.com/wisbech/bandit.git && cd bandit && bun install && bun run buildsudo ln -sf $PWD/bin/bandit.js /usr/local/bin/banditcd your-project && bandit initbandit task "write a hello world module" --accept "module prints HELLO_WORLD"bandit start --oncebandit doctor && bandit watchLocal models, zero cloud tokens
The default config drives opencode through ollama (ollama/glm-5.3-flash:cloud). The full loop — actor, gate, grader, consults — runs without a single API key.
Or your existing subscriptions
Point the transport at Claude Code or Codex via ACP profiles; they use their own logins. bandit harnesses add registers any Anthropic-protocol endpoint (LiteLLM, gateways, ollama).
03 / WHY
Agents are powerful and unmanaged.
You babysit one session at a time, paste context by hand, and trust output nobody verified. bandit is the management layer: work becomes cards, claims become measurements, arguments become a record.
Cards instead of conversations
Every task has acceptance criteria and a budget. Done means the criteria were demonstrated — not that the agent said so.
Why: chat sessions lose the thread; cards are the thread.
The gate doesn't negotiate
The harness re-runs the actor's reported verification command and uses the actual exit code. Self-graded success is recorded as fiction when the gate disagrees.
Why: agents report exit code 0 optimistically; the machine that says done must not be the machine that did the work.
Arguments before tokens
Non-trivial cards get a consult: the critic argues the plan, the master decides, bad plans die before execution. Stuck cards get a "same wall or different wall?" conversation instead of a blind retry.
Why: the cheapest failure is one that never spent the compute.
A memory with provenance
The confidence ledger tracks which levers moved which measures, corroborated by independent evidence — Holland's bucket brigade running as credit assignment. Established means posterior probability (Thompson sampling when instruments converge) — not vibes, not folklore.
Why: "it worked last time" is not a number.
04 / HOW IT WORKS
Three organs, one boundary.
Measure, argue, decide — held by different organs so none can grade its own homework. The boundary exists because of Goodhart's law in RL: optimization pressure corrupts whatever it can reshape.
| Organ | Role | Hard rule |
|---|---|---|
| Grader seat | One cheap call, criterion-by-criterion. Track record in .bandit/grading/. | Never joins the room it grades; can't touch the gate. |
| Critic (peer) | Argues free text in the consult thread at plan time, on stagnation, and at routing. Ends with one DECISION: line. | Read-only. May SUMMON: a researcher or architect — spawned as a real child serf, audit in the registry. |
| Master | Owns the conversation and routing: retry, specialist, escalate. | Decides with the thread in front of it; the thread is the receipt. |
| The gate | Re-executes the actor's verification command; fingerprints repeated failures. | Outside every conversation. No consult turns a red gate green. |
# the consult thread is part of the deliverable — read the argument: $ bandit card 010-replay-harness 01 / TIMELINE card.created → round 1 → gate red → grader contradiction ⚠ 02 / CONSULT master> … critic> … DECISION: amend 03 / GRADER round 1: fail (0.9) → round 2: pass (0.82) 04 / ARTIFACTS outputs/ 14 files · gates.json · verification-output.log
05 / DAILY USE
The commands you'll actually type.
| Command | What it does | When |
|---|---|---|
bandit watch | Live wave view — subscribes to the event stream, renders on append. Stage/role/gate per card, consult exchanges live, summoned voices in magenta. | Always, in a second terminal |
bandit card <id> | The dossier: what happened and why — timeline, consult, verdicts, artifacts. | When anything surprises you |
bandit serf <name> --role researcher | Spawn a serf by hand (mission, card binding). Loop-spawned specialists land in the same registry — hand-spawns are first-class crew. | When the factory lacks a voice |
bandit chat master | Walk into the master's pane and talk. Panes are telemetry; the master is the conversation. | When you want to steer, not watch |
bandit events | The append-only truth. Everything above is a projection of this. | Forensics |
bandit doctor | Board, events, serfs, transport, binary, lock, decisions port, budgets, event flow. | After any config change; in CI |
The factory improves itself — with evidence gates
After the board drains, the refiner reads failure signatures from the event log and proposes edits to serf prompts and memory — snapshot first, reversible via bandit refine --rollback. A factory that can't audit itself isn't running.
It ran on itself first
bandit's own board processed the features you're reading about. In production it found and fixed three of its own defects (a dead-end amend route, a false-red backtick bug, a blind stall-killer) — flagged a grading blind spot for a human, and the dossier narrated every round.
06 / LINEAGE
What bandit steals from, and gives back.
bandit is third-generation: two prior serf harnesses ran in daily production for years before it. The rest is cited appropriation — read the research, take the mechanism, name the source.
| Source | What was taken | What bandit adds |
|---|---|---|
| OmO (senpi/pi) | Monitors-not-polling, the wave layout, kibitzer pattern (frozen until measured) | The factory layer OmO doesn't have: cards, gate, ledger, tree |
| DeerFlow / LLM Space | "Sub-agents are an optimization, not the default" · inspect-every-step, replay, files-are-the-state | Events-as-truth with replay repair; the dossier is the reader LLM Space builds a whole app for |
| Brigade | Thin-clients-over-state, room streaming shape, guard vocabulary (leases, budgets, "never the agent judging itself") | Files are the broadcast — fs.watch is the subscription, no gateway daemon |
| Karwowski et al. 2023 · Kwa et al. 2024 | Goodhart divergence thresholds; why capping + monitoring beats KL regularization | The divergence monitor + reward capping design in the governor spec |
| CARMO 2025 · DORB 2020 | Dynamic criteria generation; meta-bandit over which metric to optimize | Criterion retirement flow — generator (critic+refiner) kept structurally independent of the policy |
| Féraud et al. 2016 · Tekin & Turgay 2018 | Bandit Forests for contextual reward surfaces; dominant-objective (floors-as-feasibility) framing | Floors are never learnable by the optimizing organ — the self-grading loophole, closed by construction |
| ArmoRM 2024 · Q-decomposition 2003 | MoE gating over per-objective scores; per-criterion learners with union semantics | Lexicographic composition (floors veto → primary ranks → Pareto) as the frozen upgrade path |
| isoquant.ai (design) | The visual language: near-black surface, one accent, numbered sections, hairlines, measured weight | The same tokens mapped to ANSI for the terminal renders (style guide) — and bandit's own logo + palette |
| SoL-Pi · Holland's bucket brigade · XCS | Observation packs, evidence receipts; credit assignment; accuracy-based fitness | All documented in appropriations.md with citations |
Primary research — the papers behind the governor design (full annotated list in the harness design doc):
Goodhart's Law in RL (Karwowski et al., ICLR 2024) · Scaling Laws for Reward Overoptimization (Gao et al., ICML 2023) · Catastrophic Goodhart (Kwa et al. 2024) · CARMO (ACL 2025) · DORB (EMNLP 2020) · Evaluator Stress Tests (ACL 2026) · Random Forests for Contextual Bandits (AISTATS 2016) · Dominant-Objective MO Bandits (Tekin & Turgay, IEEE TSP 2018) · ArmoRM (EMNLP 2024) · Q-decomposition (Russell & Zimdars, ICML 2003) · XCS accuracy-based fitness (Wilson 1995) · Eligibility traces (Sutton & Barto 2018, ch. 12)
Compatibility
bandit drives opencode — OmO's host — as its default harness: run omo inside a bandit actor's workspace and the skills/kibitzer stack rides along. brigade gateways, herdr panes, and ACP adapters all attach as profiles. Complements, not competitors: OmO is a better agent; bandit is the factory that can tell you why it believes something.
Privacy
No telemetry, no accounts, no network calls of its own. Everything lives under your project's .bandit/; rm -rf .bandit deletes the factory cleanly. Your harnesses' provider traffic is between you and them.
07 / START
Keep your agents. Change the factory.
bandit wraps whatever harness answers the prompt — local ollama at zero cost, or your existing Claude/opencode/Codex login.
cd your-project && bandit initbandit task "write a hello world module" --accept "module prints HELLO_WORLD"bandit start --oncebandit doctorbandit card <id>bandit watch