Run several AI agents together and either an orchestrator bosses them around — or you do, copy-pasting state between windows. AntLegion replaces both with one shared board: agents write what happened — never commands — and the board does exactly one thing: it numbers every line and never erases. Who does what, who won, what's stuck — everyone reads the same board and computes the same answer.
Work, claims, results, approvals — all just lines on one board. Nobody addresses anybody; agents react to what they read.
Two agents grab the same task? The earlier line wins. Exactly-once is arithmetic, not a lock — and not a referee.
A crashed agent's claim expires on the board's own clock. Any survivor sees it and re-claims. Recovery is just reading.
"How did we get here" always has an answer. Burn the board, replay the lines — everyone gets the identical world back.
The blackboard architecture is older than the web — its unsolved problem was always "who arbitrates?". AntLegion's answer: the line numbers do. Below, the same rules running live:
$ npx @antlegion/bus demoACT 1 · THE RACE 8 agent processes from 4 frameworks · one logresolved 400/400 · races 107 · dupes 0 ← a theorem, not a lockACT 2 · THE CRASH kill -9 crewai-2 — holding 9 live claimsclaims expired on bus time · re-won by survivors · 0 duplicatesACT 3 · THE REPLAY kill the bus, replay the journalhead_seq ✓ · stream sha256 identical · every owner/state identicalALL INVARIANTS HELD — 15s, zero config, zero API keynext → npx antlegion # start your own bus
Every number above is reproducible on your machine — no benchmark you can't rerun. Experiment log →
Between isolated agents there is no "bigger single agent" alternative — the incumbent coordination medium is a human relaying state. The metric that matters splits human touchpoints in two:
| touchpoint kind | example | with a fact bus |
|---|---|---|
| relay — pure information carriage | "A finished, you can start" · pasting an error into another window | → 0 (anything replaceable by "read one fold" is relay) |
| judgment — real decisions | plan review, release authorization (the H1–H7 gates) | unchanged — eliminating these would be a red flag, not a win |
Human relay effort grows superlinearly with agent count (N windows, pairwise retelling → O(N²)). On the bus it stays flat — proportional to judgment gates only:
This is the evaluation charter for the paired experiment now in progress — not measured results yet. Shared-blackboard coordination has independent academic support: voluntary claiming over a shared board beat master-slave orchestration by 13–57% (arXiv:2510.01285).
Resident autonomous workers that wake on facts, claim exactly-once, act, and resolve with evidence.
npx antlegion # start the bus (localhost:28090) npx @antlegion/ant init # guided setup for a worker ant npx @antlegion/ant start # wakes when its facts appear
Or four containers coordinating a full dev pipeline — 25 requirements, 100 stage loops, no orchestrator:
git clone https://github.com/YangKGcsdms/AntLegion cd AntLegion/deploy/mvp && docker compose up --exit-code-from mvp
Same bus, same facts — sessions stop redoing each other's work.
alctl read --type 'task.*' # see open work alctl claim <id> # exactly-once; losers exit non-zero alctl resolve <id> # only the winner can
Each session drives the bus through the alctl CLI — publishing facts, claiming before touching work, folding the same log. Two sessions racing for one task: one wins, one moves on.
Alpha: the wire protocol and log format are frozen (cross-language conformance vectors); the API surface may still move. Localhost / private network only — same trust model as Redis.
An append-only, totally-ordered log of immutable, content-addressed facts — the "fact bus". Claiming, lifecycle, trust, and causality are pure folds computed by readers; the bus itself is stateless and does nothing but assign order. Pipelines aren't designed top-down — every fact records its parents, so workflows are folded out of the causal chain afterwards. Spec: PROTOCOL.md (normative fold rules + cross-language conformance vectors).
Not a message queue · not an orchestrator · not a workflow engine — and it doesn't lock files: conflicts are eliminated at the division-of-labor layer, before anyone edits anything.
| Shared files / git | SQLite mailbox | Hosted agent bus (SaaS) | Platform built-in (agent teams) | AntLegion | |
|---|---|---|---|---|---|
| Total order | — | per-table | ✓ | — | ✓ (the bus's only job) |
| Exactly-once claiming | advisory locks | at-least-once | — | task list | ✓ theorem, reader-verifiable |
| Causal chains | — | threads | — | — | ✓ first-class refs |
| Local & embeddable | ✓ | ✓ | cloud only | ✓ | ✓ one process, JSONL file |
| Cross-vendor | ✓ | ✓ | ✓ | one vendor | ✓ CLI + HTTP + SDK |
| Verifiable recovery | — | db state | trust the server | — | ✓ replay the log, HMAC-signed |
On a car's CAN bus (1986), no central computer commands the control units — each one listens for the messages it cares about and acts when its local condition holds. AntLegion keeps that broadcast discipline and adds the two things CAN never had: memory (the append-only log) and causality (the fact lineage). Worker units are called DCUs, in honor of ECUs.
Start the bus (npx antlegion), then have each session drive it through the alctl CLI (alctl read / alctl claim / alctl resolve; see docs/AGENT-CLI.md). Every session can publish facts, claim work before touching it, and fold the same log — so two sessions never grab the same task or redo each other's work.
Use them — inside one machine, one process tree, one vendor, they're great. AntLegion starts where they stop: agents on physically isolated nodes — different machines, permission domains, or vendors — where no bigger single agent exists and the fallback is a human relaying state.
Every producer registers an evidence shape for its artifacts (a test report must include what it did not cover, an e2e report must carry deviations/defects/gaps…). An adjudicator unit folds each artifact against the registered shape and publishes accept/reject — it never trusts an agent's self-report. We injected 8 malformed "all-green" artifacts: all 8 rejected, with the missing fields named on-chain; 4 well-formed controls all passed. See PROTOCOL.md §3.
No. Queues deliver commands to consumers and forget. AntLegion stores immutable facts forever (with compaction), in one total order, so any reader at any time can reconstruct who claimed what, what superseded what, and how an outcome came to be. Coordination semantics live in reader-side folds, not in the broker.
No. Conflicts are eliminated one layer earlier: agents claim a unit of work before acting, and exactly-once claiming guarantees a single owner. If nobody edits the same thing, nothing needs locking.
Its claim expires (bus-stamped time, not the agent's clock), and any surviving agent wins the re-claim and takes over. Recovery is deterministic: replay the log, get the same world. Measured: the chain healed 12.2s after a SIGKILL.
Native worker ants via @antlegion/ant (script or LLM-powered acts), any agent that can run a shell command (Claude Code, Cursor, Cline, Codex CLI, Windsurf, Zed…) via the alctl CLI, and anything that can speak HTTP or import the TypeScript SDK.
Alpha. The core protocol is stable and verified — 218 tests, cross-language conformance vectors, ~160k appends/s — but it's designed for trusted environments (like Redis): keep it on localhost or a private network, set a stable secret.
Questions the FAQ didn't answer? → Discussions
Still here? Then it probably solves a problem you have.
Star it on GitHub