Running multiple AI agents on a shared project is easy.
Coordinating them isn't.

agentchute is a small Markdown protocol that lets AI agents message each other, request review, and hand off work without a human acting as the relay. 

curl -fsSL https://raw.githubusercontent.com/agentchute/agentchute/main/install.sh | sh

The installer auto-runs agentchute setup to wire lifecycle hooks and launcher shims, so the tools you already use — claude, codex, gemini — start coordinating through their own inboxes. Or skip the binary and just drop AGENTCHUTE.md into your project.

Three agents coordinating in tmux — thumbnail for the launch video
Three agents coordinating during a real working session. tmux is one wake adapter; v0.3 also ships a launcher-shim runner for terminals without tmux. 24x speedup, no staged prompts, no human ferrying messages. Watch on YouTube (62 seconds).

Latest from the blog

v0.3.5: tmux teams, worktrees, and contextual identity

The tmux reference path now handles worktrees and same-folder agents with contextual IDs, safer enrollment refreshes, and hook templates that no longer hardcode identities.

What's actually in the protocol

The protocol is a small set of implementation-agnostic primitives. Conforming implementations are free to choose any inbox medium, any transport between sender and inbox, and any wake mechanism — those are outside the protocol.

  • Per-recipient inbox. Each agent owns an ordered message stream. Senders deliver into the recipient's inbox; the recipient owns consumption. The inbox medium is implementation-specific.
  • Ordered, identified messages. Each carries a unique (timestamp, sender, nonce) identity tuple; receivers process oldest-first by timestamp with deterministic tie-breaking. The reference CLI realizes this as lexicographic-sorted filenames.
  • No-overwrite delivery. Delivery never silently clobbers an existing entry. Same-identity collisions retry with a fresh nonce. Sender-to-inbox transport is implementation-specific.
  • Recipient-owned consumption. Only the recipient reads its own message bodies. Liveness checks use inbox metadata only.
  • Optional wake. Senders MAY signal a recipient via a pluggable wake adapter. Per §8.2, recipient-side polling is the correctness mechanism; wake is a latency hint. The wake mechanism is implementation-specific.
  • Self-registration. Each agent publishes a small record naming itself, its wake method/target (if any), and operational metadata.

The reference CLI: filesystem inboxes, optional wake

The CLI in this repo picks one concrete answer for each implementation-specific axis. It's not the protocol — it's the implementation we used while building the protocol, and it worked well enough to be the exclusive coordination layer for the team that shipped it. tmux remains the fastest local wake path when all agents live in one terminal multiplexer. v0.3 ships the other path as a first-class peer too: a launcher-shim runner registers a Unix-socket wake target, polls the inbox, and injects the wake prompt without tmux. Recipients can also self-poll on a cadence and let a scheduler launch the wrapper only when work exists.

  • Inbox medium: plain .md files on a shared filesystem, organized under .<vendor>/loop/inbox/<agent>/.
  • Transport: atomic create-temp + rename (the local-filesystem realization of no-overwrite delivery).
  • Peer wake adapter: tmux send-keys injects [agentchute:tmux] check inbox into an addressable recipient pane. The bracketed prefix is machine metadata; the model-facing instruction is still to check the inbox. See the tmux starter kit for the 5-minute local setup.
  • Runner socket: the launcher-shim runner (agentchute run --as codex --vendor openai -- codex, installed by setup) launches the wrapper under a PTY, registers a Unix-socket wake target, polls the inbox, and injects [agentchute:run] check inbox when mail arrives. Works without tmux.
  • Recipient polling: self-poll is the read-only "should I wake the wrapper?" helper for schedulers and launch prompts.
  • Generated schedulers: doctor --generate-service emits launchd, systemd, or portable shell-loop units that run self-poll and then launch the wrapper, not bare check.
  • Lifecycle catchup: gate --before continue lets already-awake wrappers catch mail that arrived during a turn.

Alternate inbox media (Redis/NATS queues, S3-prefixed inboxes, HTTP endpoints, git-backed) are protocol-compatible — see EXTENSIONS.md.

The Handoff: simple two-agent message flow

The simplest case: alice sends; bob discovers the inbox entry by wake hint or polling; bob's model runs agentchute check; bob replies.

step 1 / 4

The Review: multi-agent coordination with liveness sidecar

Three peers plus a watchdog. claude-code requests review, codex and gemini-cli send findings back, claude-code consolidates and asks for sign-off. The watchdog runs as a metadata-only liveness sidecar — it only wakes a peer with a stale unread inbox. Same protocol; same shared inbox; no central broker.

step 1 / 5

What it isn't

agentchute is not a multi-agent framework. No task graphs, no retries, no role election, no central broker, no SDK, no SaaS pricing tier.

  • Not a message broker with delivery guarantees. No retries, no acknowledgments, no exactly-once. If you need queues, use a queue.
  • Not an identity/auth system. Messages are unsigned plain-text. If you don't trust your peers, don't run them on your machine.
  • Not a router or task-assignment engine. Agents are peers; senders pick recipients explicitly. No wildcard, no broadcast, no role election.
  • Not an audit log. Archives are local and gitignored by default. Loop messages are a transient operational trace.
  • Not a distributed transport with cryptographic guarantees. The reference CLI runs over a shared filesystem and provides no signing, no acks, no exactly-once. The protocol itself is medium-agnostic — alternate inbox transports are compatible — but the CLI ships only the local, unsigned, cooperative-trust implementation. For cryptographic audit, use a signed-envelope coordination protocol.

If you wanted any of those, this is the wrong tool, and that's fine.

Quickstart — no binary

The protocol-only path: drop AGENTCHUTE.md into your project and follow §3 (layout) + §5 (registration) + §6 (messaging). No agentchute binary required; sending and checking are mv plus an optional wake poke. The CLI and the hand protocol share the same files, so you can mix them in the same pool.

The reference CLI

~4000 lines of stdlib Go, no third-party dependencies. The CLI and the hand protocol interoperate because both write the same files.

curl -fsSL https://raw.githubusercontent.com/agentchute/agentchute/main/install.sh | sh

Or if you'd rather build from source: go install github.com/agentchute/agentchute@latest, then run agentchute setup in your control repo.

The four commands a new user actually needs:

  • agentchute setup — one-command repo wiring. Prompts for tmux / runner / both wake path; installs lifecycle hooks; installs launcher shims for runner/both modes; updates PATH when needed.
  • agentchute doctor --as codex — health check. Validates registration, wake-target reachability, hook templates, and no-tmux liveness coverage. Run this after setup.
  • agentchute send --from claude-code --to codex --task "review diff" — writes the message file and attempts a best-effort recipient wake.
  • agentchute check --as codex — reads + archives the agent's own inbox, records reply obligations, quarantines malformed mail per §11, and cooperative-wakes peers per §10.5.

The full surface (init, register, self-poll, gate, run, poller, watchdog, hook helpers) is documented in AGENTCHUTE.md and the wrapper enrollment templates. Most users only call setup + doctor directly; the rest are invoked by lifecycle hooks and launcher shims.