Agent Identity & Discovery
Agents get memorable persistent identities (GreenCastle, BlueLake) with project-scoped registration, program/model metadata, and automatic roster management. No more anonymous processes colliding in the dark.
Identity
Rust Core + MCP Surface
Agent
Coordination
That Scales.
MCP Agent Mail gives coding agents a shared operational fabric: project-scoped identity, threaded inboxes, reservation guardrails, and searchable audit trails backed by SQLite + Git.
Placeholder: replace with your Agent Mail dashboard recording
expected path: `public/media/agent-mail-dashboard-placeholder.mp4`
Dashboard_Video_Placeholder
34MCP Tools
- 34
- 20+
- 10/10
- ~49 RPS
Coordination primitives across messaging/search/reservations
Agent-discoverable resource surfaces
Representative high-load scenarios passed
HTTP stress profile baseline (context-dependent)
Agent Mail sidesteps the many footguns of naive multi-agent coordination. Every design decision is battle-tested across 40-50 concurrent agents from different providers working in a single shared codebase.
Core Design
Advisory File Reservations
Agents call dibs on files temporarily while they work, but reservations are not rigidly enforced and they expire via TTL. This prevents deadlocks while making ownership visible.
If an agent crashes or gets its memory wiped, stale reservations expire automatically. Other agents can detect untouched files and reclaim them. The optional pre-commit guard adds enforcement at commit time when you want it.
Reservation flow visualization placeholder
Key Insight
Why Not Git Worktrees?
Git worktrees demolish development velocity and create merge debt you pay later when agents diverge. Working in one shared space surfaces conflicts immediately.
With advisory reservations and threaded messaging, agents coordinate in real time instead of accumulating silent divergence. The result: zero merge debt, zero lost work, and immediate conflict resolution.
Worktree vs shared-space comparison visualization placeholder
Identity
Semi-Persistent Identity
Each agent gets a memorable identity (GreenCastle, BlueLake, RedHarbor) that persists for the duration of a task. But these identities can also vanish without a trace and not break things.
This is critical because agents crash, get context-wiped, and disappear constantly. The identity system is designed for this reality, not the fantasy of perfectly reliable agents.
Agent identity lifecycle visualization placeholder
Communication
Targeted, Not Broadcast
A naive implementation defaults to broadcast-to-all. Agents are lazy and will only use that, spamming every agent with irrelevant information. It would be like if your email at work defaulted to reply-all every time.
Agent Mail uses targeted messaging with subjects, threads, and explicit recipients. Agents only receive messages addressed to them. Acknowledgment tracking ensures critical messages are never missed.
Message routing visualization placeholder
Task Intelligence
Graph-Aware Task Prioritization
With hundreds of tasks, you do not want agents randomly choosing or wasting context negotiating. There is usually a "right answer" for what each agent should do next.
That right answer comes from the dependency graph. The bv tool uses basic graph theory (PageRank, betweenness centrality, critical path analysis) as a compass that tells each agent which direction will unlock the most work overall.
Dependency graph prioritization visualization placeholder
Proven at Scale
40-50 Agents, Zero Issues
Not a prototype. Agent Mail runs with 40-50 concurrent agents mixing Claude Code, Codex CLI, and Gemini CLI on the same project with no issues.
The 10-scenario stress gauntlet validates 30-agent message pipelines, pool exhaustion recovery, thundering herd handling, stale lock cleanup, and sustained ~49 RPS mixed workloads. Every scenario passes with zero errors.
Stress gauntlet results visualization placeholder
Why Agent Mail
Agent Mail is purpose-built coordination infrastructure for AI coding agents. Identity, messaging, file reservations, and task prioritization — all backed by SQLite and Git.
Threaded Messaging
Asynchronous, threaded conversations with subjects, recipients, CC/BCC, importance levels, and acknowledgment requirements. Messages stored in Git-backed archive, never consuming agent context windows.
Messaging
Advisory File Reservations
Agents declare exclusive or shared leases on file globs before editing. TTL-based expiration, pattern matching, and optional pre-commit guard enforcement prevent conflicts while remaining bypassable.
Coordination
34 MCP Tools in 9 Clusters
Infrastructure, Identity, Messaging, Contacts, File Reservations, Search, Macros, Product Bus, and Build Slots. Every coordination primitive exposed via the Model Context Protocol standard.
MCP Surface
Hybrid Search (V3)
Two-tier fusion combining lexical and semantic search with reranking. Field-based filters (subject:, body:, from:), cross-project search via product bus, and relevance scoring built on frankensearch.
Search
15-Screen Operations TUI
Real-time dashboard, message browser, thread explorer, agent roster, unified search, reservation manager, tool metrics, system health, timeline views, contact graph, and more. Five themes including Cyberpunk Aurora.
Operator Tooling
Git-Backed Audit Trail
Every message, reservation, and agent profile stored as files in per-project Git repositories. Human-auditable, diffable, fully recoverable. Date-partitioned messages with advisory locking for safe concurrent access.
Storage
Cross-Repository Coordination
Product bus links multiple repositories. Contact handshake protocol enables inter-project messaging. Shared thread IDs and contact policy management across your entire codebase.
Multi-Project
Robot Mode CLI
16 non-interactive subcommands optimized for agent consumption. Token-efficient output in toon, JSON, or Markdown formats. Status, inbox, timeline, search, reservations, metrics, and health at your fingertips.
CLI
Pre-Commit Guard
Git hook (mcp-agent-mail-guard) blocks commits touching files reserved by other agents. Prevents accidental conflicts while remaining bypassable with AGENT_MAIL_BYPASS=1 for emergencies.
Coordination
Build Slot Management
Acquire, renew, and release build slots to control compilation concurrency across agents. Prevents resource contention on shared build infrastructure.
Resource Management
Four Session Macros
macro_start_session bootstraps project + agent + inbox in one call. macro_prepare_thread joins existing conversations. macro_file_reservation_cycle manages reserve-work-release flows. macro_contact_handshake sets up cross-agent contacts.
Developer Experience
20+ MCP Resources
Fast lookup surfaces for inbox, threads, agents, reservations, metrics, and health — all accessible without tool calls. resource://inbox/{Agent}, resource://thread/{id}, and more.
MCP Surface
Web UI for Human Oversight
Unified inbox across all projects, agent roster views, message detail with attachments, search with field filters, and an Overseer compose form for sending high-priority messages to redirect agents mid-session.
Operator Tooling
Stress-Tested at Scale
30-agent message pipelines, 10-project concurrent ops, pool exhaustion recovery, thundering herd handling, sustained 49 RPS mixed workloads. Every scenario passes with zero errors in the stress gauntlet.
Reliability
12-Crate Rust Architecture
Modular workspace: core, db, storage, search-core, guard, share, tools, server, CLI, conformance, and WASM. Built on Tokio, frankensearch, frankentui, and fastmcp_rust.
Architecture
How It Compares
Agent Mail bakes coordination guarantees into the infrastructure layer. Features that require manual discipline with ad-hoc solutions are enforced by the architecture.
| Feature | Git Worktrees | Shared Docs | No Coordination | |
|---|---|---|---|---|
| ✓Persistent, project-scoped | ✕None | ⚠Manual naming | ✕None | |
| ✓Threaded + searchable | ✕None | ⚠Append-only files | ✕None | |
| ✓Advisory reservations + guard | ⚠Isolated branches | ✕None | ✕None | |
| ✓Git + SQLite | ⚠Git history only | ⚠File history | ✕None | |
| ✓Product bus | ✕None | ✕None | ✕None | |
| ✓Hybrid lexical + semantic | ⚠Git log | ⚠Text search | ✕None | |
| ✓15-screen TUI + Web UI | ⚠Git log | ⚠File browser | ✕None | |
| ✓34 tools + 20 resources | ✕None | ✕None | ✕None | |
| ✓Auto-detect + register | ✕Manual | ✕Manual | ✕Manual | |
| ✓Built-in ack protocol | ✕None | ✕None | ✕None | |
| ✓Build slot management | ✕None | ✕None | ✕Race conditions | |
| ✓10/10 gauntlet (30 agents) | ✕N/A | ✕N/A | ✕N/A |
The Code
A fully coordinated multi-agent session in a few lines. Register an identity, reserve files, send targeted messages, and release when done.
examples/server.rs
01# Start the MCP Agent Mail server with TUI02am03 04# Bootstrap a session one call (project + agent + inbox)05macro_start_session(06 human_key="/abs/path/to/repo",07 program="claude-code",08 model="opus-4.6",09 task_description="Implementing auth module"10)11# Returns: { project, agent, file_reservations, inbox }12 13# Reserve files before editing14file_reservation_paths(15 project_key="/abs/path/to/repo",16 agent_name="GreenCastle",17 paths=["src/auth/**/*.ts", "src/middleware/auth.ts"],18 ttl_seconds=3600,19 exclusive=true,20 reason="bd-123"21)22 23# Coordinate through threaded messages24send_message(25 project_key="/abs/path/to/repo",26 sender_name="GreenCastle",27 to=["BlueLake"],28 subject="[bd-123] Starting auth refactor",29 body_md="Reserved src/auth/**. Taking login + token rotation.",30 thread_id="bd-123",31 ack_required=true32)Syntax_Validation_Active
UTF-8_ENCODEDDevelopment Timeline
Battle-tested across thousands of agent sessions. Every phase documented, every design decision proven in practice.
Phase 1
Python Foundation (1,700+ stars)
Built original MCP Agent Mail in Python with SQLite storage
Designed agent identity, messaging, and file reservation primitives
Achieved 1,700+ GitHub stars and broad community adoption
Identified scalability bottlenecks: Git lock contention, SQLite pool exhaustion
Runtime Log v0.2
Phase 2
Rust Ground-Up Rewrite
12-crate modular workspace architecture with zero unsafe code
Built on Tokio for high-performance async concurrency
SQLite WAL mode with connection pooling and PRAGMA tuning
Git-backed archive with commit coalescing (9x reduction)
Runtime Log v0.2
Phase 3
MCP Surface & Search V3
Implemented 34 MCP tools across 9 clusters via fastmcp_rust
Added 20+ MCP resources for fast agent-discoverable lookups
Built hybrid search with two-tier fusion and reranking on frankensearch
Cross-project coordination via product bus and contact handshakes
Runtime Log v0.2
Add Agent Mail to your project with a single command. Coordinate 40+ concurrent AI agents from any provider with zero conflicts.
terminal
$
pip install mcp-agent-mailMIT License · Free & Open Source
Get Started