Agent Mail
A Communication Protocol for AI Agents
Multiple AI agents across multiple projects — and no way to coordinate. So I designed a decentralized protocol where agents independently check inboxes, act on messages, and reply. Git is the mail server. Markdown is the message format. Coordination emerges from protocol, not from a coordinator.
application servers
databases
APIs
the entire infrastructure
The Short Version
AI agents are powerful in isolation. The isolation is also the limitation.
I run multiple AI agents across different projects — font design, life management, desktop apps, this website. Some are Claude Code sessions, some are semi-autonomous API-based agents, and soon some will run on local models. Each operates in its own context, with its own goals. When one agent discovers something relevant to another agent's work, the only communication channel is me — copying information between sessions, relaying context, becoming the human bottleneck in what should be an automated system.
So I designed Agent Mail: a protocol where agents independently check their inboxes at session start, act on messages, reply, and push. The system is live, growing, and self-updating — agents check for protocol changes and update their own instructions without human intervention.
No application server. No database. No API. No message queue. The infrastructure is a GitHub repository.
The Problem
The human operator as a message bus.
Here's the scenario: an agent managing my life roadmap surfaces an observation — career stress is amplifying financial anxiety. That observation is directly relevant to another agent tracking career development. But the agents don't know each other exists. They can't send messages. They can't flag correlations.
The only way that information moves between systems is if I notice it, remember it, switch to the other session, and relay it manually. Multiply that across five or six concurrent projects, each with its own agent session.
This is the same problem that motivated message queues, event buses, and pub/sub systems in distributed software. Multiple independent processes that need to coordinate but can't share memory. The solution in software is infrastructure — a communication layer between the processes.
The coordination tax
The existing infrastructure doesn't fit.
Kafka is overkill. RabbitMQ assumes always-on consumers. REST APIs require a running server. These are all built for processes that are continuously running.
AI agent sessions are ephemeral — they start, they work, they end. The communication infrastructure needs to match that reality.
Design Decisions
Every constraint was an opportunity to simplify.
Git as the mail server.
The insight that unlocked the design: Git already does everything a mail server needs to do. Sending is a push. Receiving is a pull. The audit trail is git log. Conflict resolution is built in. Authentication is handled by SSH keys. Distribution is handled by GitHub.
Every AI coding agent already knows how to git pull and git push. The infrastructure already existed — it just hadn't been framed that way.
Messages as Markdown files.
YAML frontmatter for metadata, Markdown body for content. No serialization layer, no schema validation, no format negotiation. A human can read the raw file and understand it completely. An agent can parse the frontmatter and act on it programmatically.
The filename encodes the metadata: timestamp, sender, and thread ID. You can sort messages chronologically just by listing the directory. No parsing required for basic triage.
And YAML frontmatter is extensible by design — new fields can be added without requiring a complete refactoring of the message format or the agents that consume it.
Directory structure as architecture.
There's no routing logic. There's no message broker. An agent checks its inbox by reading a directory. It processes a message by acting on the content and moving the file to read/. It replies by creating a new file in the recipient's inbox.
The protocol can be understood completely by looking at the folder structure. The design is self-documenting.
Conflict-resistant by construction.
Every message filename is unique — the combination of timestamp, sender ID, and thread ID means two agents can never create the same filename. Two agents pushing concurrently will never collide on the same file.
This eliminates locking, queuing, and coordination. The constraint is in the schema, not in the logic.
Protocol Architecture
The directory layout is the entire system.
agent-mail/
├── inbox/
├── life-roadmap/
├── site-architect/
└── operator/
├── read/
└── {agent-name}/
├── history/
└── {agent-name}/
├── maillog/
└── {agent-name}.md
├── agents.md
└── CHANGELOG.md
Unread messages organized by recipient. An agent reads this directory to check for new mail.
Processed messages moved here after handling. Never deleted — the flow is inbox → read → history.
Complete archive of all messages each agent has ever sent. Immutable audit trail.
Per-agent session logs. What was received, what action was taken, what was sent.
Self-Updating Protocol
The agents update themselves.
How do you update a distributed system where the nodes are ephemeral AI sessions? You can't push updates to agents that don't exist yet. You can't assume they're running when the update ships.
Instead, you make the update available at a known location — CHANGELOG.md — and make checking that location part of the session startup procedure. The protocol evolves. The agents adapt. No manual reconfiguration.
Session protocol — 8 steps
Context Isolation
No staining.
When an agent visits the repository to check its inbox, it reads the protocol from the repo-level instructions — not the operator's personal configuration. This separation means an agent that visits to check messages doesn't inherit the operator's role, preferences, or context.
Each agent maintains its own identity and its own instructions. The protocol is shared. The identity is not. An agent sees the mail protocol. It doesn't see another agent's priorities, tone preferences, or project-specific conventions.
Append-only, no deletion
Messages are never deleted. They flow from inbox/ to read/ to history/. Every message that has ever been sent still exists in the repository. Combined with Git's version history, this creates a complete, immutable record of all agent communication.
When an agent makes a decision based on information from another agent, you can trace exactly what information it received, when it received it, and what it did in response. The audit trail is structural, not bolted on.
What Makes This Different
Protocol, not platform.
No central authority
The instinct when you need agent coordination is to build a platform — an API, a dashboard, an orchestration layer. Agent Mail does none of that. Each agent independently follows the protocol: pull, check inbox, act, reply, push. If an agent doesn't check in for a week, nothing breaks. If a new agent registers, nothing needs to be reconfigured.
The user isn't a human
Every other system I've built has a human as the end user. Agent Mail inverts this. The primary users are AI agents. The Markdown format, the directory structure, the YAML frontmatter — these are designed for AI agent consumption first, human readability second. The protocol decisions — append-only, unique filenames, self-updating versions — are designed around AI agent behavior: ephemeral sessions, no persistent memory, concurrent operation without coordination.
Scales by adding directories
A centralized platform creates a single point of failure and a bottleneck. A protocol creates a shared language. The system scales by adding directories, not by updating configuration. The internet isn't managed by a central router — it's a protocol that independent networks implement. Agent Mail applies the same principle at a smaller scale.
The mail metaphor isn't an accident
Email is the original asynchronous, protocol-based, decentralized communication system. It works because the protocol is simple, the format is universal, and no single server controls it. Agent Mail applies the same principles to a new kind of communicator. The messages are structured for machines. The transport is Git instead of SMTP. But the design philosophy is identical.
Hindsight
What I'd do differently.
The threading model needs work — but may not need what I think.
The current thread ID system works for point-to-point conversations. Multi-agent threads create branching structures that the flat file model handles awkwardly. But unlike human email, agents can multi-thread within sessions and find what they need contextually. The constraint may resolve itself as agent capabilities evolve. I'm watching it rather than prematurely engineering a solution.
Agent health monitoring is on the roadmap.
The system currently relies on me noticing when an agent hasn't checked in. A heartbeat-file mechanism — each agent writes on check-in, an alert fires if stale — would catch silent failures. The infrastructure is trivial. It's just not the bottleneck right now, and I'd rather build what's needed when it's needed than engineer for theoretical scale.
Message volume will eventually need managing.
With a handful of agents, flat inbox directories are manageable and human-readable. At scale, an Archivist agent (a pattern I've already engineered elsewhere) would manage the historical record, with a Librarian agent providing RAG-based retrieval when needed. The load on historical messages will be low — they're rarely needed — so the current design buys simplicity today without closing the door on sophistication later.
The Design Insight
Coordination through protocol, not orchestration.
The conventional approach to AI agent coordination is orchestration — a central system that assigns tasks, routes information, and manages state. This works when you have a fixed set of agents doing predictable work. It breaks when agents are ephemeral, when the work is unpredictable, and when the system needs to grow without reconfiguration.
Agent Mail takes the opposite approach: coordination through protocol. No central authority decides what information goes where. Instead, the protocol defines how agents communicate, and coordination emerges from independent agents following that protocol. The system doesn't need to know how many agents exist or what they're doing. It just needs to ensure the protocol is followed.
This is the same architectural insight behind the internet, behind Git itself, behind any distributed system that scales without central coordination. AI agents are going to be the next thing that needs to coordinate at scale — and the orchestration-first approach that most organizations are reaching for is going to hit the same ceiling that centralized architectures always hit.
At its core, Agent Mail is cognitive offloading — removing myself as the bottleneck so the agents can coordinate directly and I can focus on the work that actually needs a human. The same architectural instinct behind every system I build: remove friction, externalize coordination, free up bandwidth for the things that matter.
Technical Stack
More case studies
See how I approach different kinds of problems — from AI-governed development to enterprise platform architecture.