MCP Agent Mail: A Shared Inbox for Your Coding Agents

⬅️ Back to Tools

MCP Agent Mail: A Shared Inbox for Your Coding Agents

Run two coding agents on the same repo and eventually they edit the same file at the same time, and you find out at commit time, if at all. MCP Agent Mail is Jeffrey Emanuel’s answer: a mail-like layer where every agent gets an identity like GreenCastle or BlueLake, an inbox, and a way to claim files before touching them. It is the Rust rewrite of his Python original, which collected 1,700+ stars.

1. The core primitive is the advisory file reservation. Before editing, an agent claims a glob like src/auth/** for a TTL, one hour by default. Other agents see the claim and can route around it. Because reservations are leases rather than locks, a crashed agent’s claim expires on its own instead of holding files hostage.

2. Enforcement is opt-in at exactly the right place. An optional pre-commit guard installs as a Git hook and blocks commits that touch files another agent has reserved, bypassable with AGENT_MAIL_BYPASS=1 when you know better. Conflicts get caught without deadlocks becoming possible.

3. The contrarian bet is no worktrees. Instead of N copies of the repo diverging silently until merge day, all agents work in one shared space and negotiate through messages. Emanuel is blunt about it: “Worktrees suck and just kick the can down the road.” Conflicts surface immediately instead of accumulating as merge debt.

4. Messaging is targeted, never broadcast. Agents send mail with subjects, recipients, threads, and importance levels; thread IDs usually map to issue IDs like FEAT-123. Messages live in a per-project Git archive rather than burning context window, and ack_required makes recipients confirm receipt so critical notes do not just get delivered but processed.

5. It has been proven at uncomfortable scale. Emanuel reports running 40-50 concurrent agents mixing Claude Code, Codex CLI, and Gemini CLI on one project. The published stress gauntlet passes all ten scenarios: 30-agent message pipelines with zero errors, pool exhaustion recovery at four times oversubscription, thundering herd handling, and ~49 RPS sustained mixed load for 30 seconds.

6. The Rust rewrite fixed specific Python failures, testably. Git lock contention from rapid-fire writes is gone via a commit coalescer that batches 100 writes into roughly 11 commits, a 9.1x reduction. SQLite pool exhaustion and stale lock recovery each have dedicated passing tests. The README documents every failure mode against its fix.

7. Operators get real dashboards. A 16-screen TUI covers messages, threads, reservations, tool metrics, analytics, and even a two-pane browser into the Git archive. There is a web UI with an Overseer compose form for redirecting agents mid-session, and an 18-subcommand robot mode CLI with token-efficient toon, JSON, or Markdown output.

8. Honest limits. Reservations are advisory by design, so nothing physically stops a rogue agent from ignoring them. Building from source requires Rust nightly plus eight locally patched sibling repositories, which rules out casual source builds; use the installer binaries. The semantic tier of hybrid search sits behind a feature flag. And if you only ever run one agent, this is infrastructure you do not need yet.

Install & first run

curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/mcp_agent_mail_rust/main/install.sh?$(date +%s)" | bash

The installer detects your platform, drops the binary in ~/.local/bin, and auto-configures detected Codex CLI installs. Then:

am

One command: it finds your installed agents, refreshes their MCP configuration, starts the HTTP server on 127.0.0.1:8765, and opens the TUI. Agents bootstrap with a single macro_start_session call, reserve globs, and start mailing each other. There is also cargo install mcp_agent_mail_rust if you prefer cargo, and a 23-minute walkthrough video showing seven agents exchanging over 1,000 messages across a two-day build.

Worth your time if: you run multiple coding agents against one repo and have already lost work to a silent overwrite. Single-agent workflows will not miss it yet.

Related TMFNK Content

• Context Hub Another piece of agent-native infrastructure: curated, self-improving documentation your agents can actually find.
• CLI-Anything The same thesis from the other direction: making existing software legible to agents.
• Superpowers An agentic skills framework that pairs naturally with a coordination layer.

Crepi il lupo! 🐺