protocol v2.5 · reference cli 1.5
Stop being the message busfor your agents.
Running agents is easy — coordinating them isn't. agentchute gives every AI agent an inbox. They hand off work, request review, and message each other — no human relaying every step, no broker, just plain files.
That's the reference CLI. The protocol is just files — bring your own implementation and the vectors prove it conforms.
Every agent has an inbox — a directory. A message is a Markdown file dropped in it. The recipient reads its own inbox, on its own schedule. Best-effort delivery, no server, no SDK — and it works with any terminal-based agent, not a fixed list.
what changed in v2.5
We broke it on purpose.
We stopped using our own agents for three weeks. When we came back, one had a message waiting that had been unread for twenty-three days. Nothing had failed — the message was delivered exactly as designed, sitting intact in the right inbox. That was the problem. We had built a mailbox that accepted letters for people who had moved out, and never mentioned it to anyone.
So v2.5 makes absence visible. When an agent's supervisor stops heartbeating, its registration goes stale — about an hour by default — and sending to it fails right away instead of disappearing into a mailbox nobody will open. Long jobs are fine: the supervisor keeps heartbeating whether the model is busy or idle. Message names changed with the break too — timestamps instead of per-pair counters.
It is a real break. A v2.5 agent still reads normal v2 mail; a v2 agent cannot read v2.5 names — so every agent sharing a pool moves together. At 1.0 we said this would only happen through a deprecation process. It didn't, and we would rather say so here than let you find out from a stack trace.
what's in the protocol
Five primitives. The rest is your choice.
per-recipient inbox
Each agent owns an ordered message stream. Senders deliver into it; the recipient owns consumption.
identified messages
Every message has a durable identity — a timestamp and a random suffix. A sender's messages stay in order through a durable timestamp floor; replies carry the thread.
no-overwrite delivery
A sender never clobbers an existing message. A collision is refused and retried under a fresh identity — delivery is at-most-once, not deduped.
recipient reads its own inbox
Pull, not push. Senders write and walk away; the message waits until the recipient reads it.
self-registration + presence
Each agent publishes a small record and a liveness heartbeat, read on demand.
…pinned by vectors
Conformance is a set of language-neutral vectors. Pass them in any language and you're on the wire.
code, but not the protocol
A real implementation — that you're free to replace.
agentchute ships a faithful reference implementation: a small Go CLI and a per-agent supervisor that handle delivery, registration, presence, and ordering for you. It is not the protocol. The protocol is the spec — a directory layout and a filename grammar — and anyone is welcome to write another implementation, in any language, over any transport. The conformance vectors are how you prove yours; ours and yours interoperate because both just read and write the same files.
honest scope
What it isn't
agentchute is not a multi-agent framework. No task graphs, no role election, no central broker, no SDK, no SaaS tier. If you wanted those, this is the wrong tool — and that's fine.
- Not a delivery broker. Delivery is best-effort and at-most-once; the recipient reads on its own cadence. Need retries and exactly-once? Use a queue.
- Not an auth system. Messages are unsigned plain text. If you don't trust your peers, don't run them on your machine.
- Not a router. Agents are peers; senders pick recipients explicitly. No wildcard, no broadcast, no role election.
- Not a product. A protocol and a faithful reference implementation, maintained for spec fidelity. Alternates welcome — the vectors prove them.
get started
Two ways to start.
Use the reference CLI
One small Go binary plus a per-agent supervisor. Install, wire your repo once, start your agents.
$ agentchute setup
$ ac serve claude # per-agent runner (new shell; blocks)
$ agentchute doctor --as claude-code # from another shell
Or your own — it's just files
Write any implementation against the spec, prove it with the vectors, or drive the protocol by hand.
$ cp AGENTCHUTE.md ./your-repo/
$ mv msg.md loop/inbox/codex/
Already running v2? v2.5 reads v2 mail, but v2 cannot read v2.5 messages — so every agent sharing a pool moves together. Freeze sends first, and never use --no-resync for this upgrade.
$ agentchute status --as <agent-id> # twice, 15s apart — old last_seen must not advance
$ ac --as <agent-id> serve <wrapper> # relaunch each lane under its EXISTING id
$ agentchute doctor --as <agent-id> # from another shell, until clean