MCP Agent Mail: The Coordination Layer for Chaotic AI Swarms
When multiple autonomous agents work on the same codebase, they overwrite each other's work. Here is how one developer used Git hooks, SQLite, and an email metaphor to force them to collaborate.
I finally got around to making a tool I've wanted for a long time: you can basically think of it as being "like Gmail for coding agents."
- MCP Agent Mail prevents AI agents from overwriting each other by managing file access through an asynchronous email-style inbox.
- The system uses Git pre-commit hooks to strictly block any agent from committing code without a valid file lease.
- A dual-storage architecture combines SQLite for high-speed metadata searching with Git for a permanent and reversible audit trail of all agent actions.
- Deterministic names like "AzureFalcon" replace anonymous IDs to make multi-agent coordination readable for human developers.
The Collision Problem
Drop Claude Code, Cursor, and a Gemini CLI agent into the same repository, and they will work fast. But they will also step on each other's toes.
Autonomous coding agents lack peripheral vision. When two agents attempt to refactor the same module simultaneously, the result is an edit war. One agent pulls an older version into its context window, makes a change, and forcefully writes it back to disk, silently wiping out the other agent's intermediate progress. The AI industry has largely treated this "thundering herd" problem as an orchestration issue, attempting to solve it with complex neural routing or shared memory buses.
MCP Agent Mail takes a different, almost cynical approach. It assumes agents are chaotic, over-eager coworkers who cannot be trusted with shared state. Instead of building a complex neural orchestrator, it forces them to communicate through a boring, battle-tested human paradigm: an asynchronous email inbox.
Weaponizing Git Hooks Against Agents
MCP Agent Mail solves concurrency not with soft suggestions, but with hard filesystem boundaries. Before an agent can modify a file, it must request a "lease" through the Model Context Protocol (MCP) server.
In many systems, advisory locks are easily ignored by rogue processes. MCP Agent Mail prevents this by deploying a script called guard.py. This script installs a pre-commit hook directly into the local Git repository. If an agent attempts to commit code without holding a valid, unexpired lease for the modified files, the Git hook flashes red and rejects the commit entirely.
By moving the enforcement layer down to the Git binary level, the system ensures that no agent—no matter how aggressively prompted—can bypass the coordination rules.
Memorable Identities and the Inbox
To make the system legible to human overseers, agents are assigned deterministic, memorable names like "AzureFalcon" or "GreenCastle" rather than UUIDs. This simple constraint prevents role confusion in the logs and makes debugging multithreaded AI interactions significantly easier.
The FastMCP server acts as a central post office. Agents can leave GitHub-Flavored Markdown messages for each other in persistent inboxes. Because the communication is asynchronous, an agent doesn't need to be running at the exact millisecond a message is sent to receive its instructions.
The Dual-Database Approach
Under the hood, MCP Agent Mail splits its state across two distinct storage backends to balance performance with auditability.
A SQLite database, configured with Full-Text Search (FTS5) and strict WAL mode, handles the high-velocity metadata. When an agent queries its inbox to regain context, SQLite provides millisecond response times. However, SQLite is not the true system of record.
The actual message contents and file payloads are committed to the Git repository. To prevent Git lock contention when multiple agents are active, the storage.py module employs a sophisticated _CommitQueue. It buffers file changes and batches them into single Git commits. This treats Git as an immutable, human-readable database, ensuring that if an agent goes rogue, a developer can simply git revert the damage.
Asynchronous Mail vs. Real-Time State
The choice to use an asynchronous inbox rather than a real-time shared memory bus (like MACP) reflects a specific philosophy about how code is written. Development is inherently asynchronous. Forcing agents into a real-time synchronous loop often leads to token exhaustion and deadlocks.
They can also reserve access to certain files to avoid the "too many cooks" problems associated with having too many agents all working on the same project at the same time, all without dealing with git worktrees and "merge hell."
| Feature | MCP Agent Mail | MACP (Shared Bus) | Native CLI Agents |
|---|---|---|---|
| Primary Metaphor | Asynchronous Inbox | Real-time memory bus | Isolated execution |
| Concurrency Control | Git pre-commit locks | Task handoffs | Self-managed / None |
| State Persistence | Git + SQLite | Shared SQLite | Local filesystem |
| Human Observability | High (Dedicated Web UI) | Medium | Low (Terminal only) |
By leaning on proven technologies—Git for state, SQLite for search, and SMTP-style messaging for coordination—MCP Agent Mail provides a pragmatic safety net. It allows engineering teams to scale up their AI swarms without losing control of the repository.
Sources: