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.

RsCxCx
34MCP Tools
MCP Tools
34

Coordination primitives across messaging/search/reservations

Resources
20+

Agent-discoverable resource surfaces

Stress Gauntlet
10/10

Representative high-load scenarios passed

Sustained Throughput
~49 RPS

HTTP stress profile baseline (context-dependent)

10/10
Stress Test Scenarios
All 10 stress gauntlet scenarios pass with zero errors
12
Rust Crates
Modular workspace: core, db, storage, search-core, guard, share, tools, server, CLI, conformance, WASM
15
TUI Screens
Full operational dashboard: inbox, threads, reservations, agents, system health, and more
3
Search Modes
Lexical (BM25), semantic (embedding), and hybrid search across all message history
~49
Sustained RPS
Mixed workload throughput maintained over 30-second stress test windows

Why Purpose-Built 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 claim file patterns temporarily while they work, but reservations are advisory and 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.

Loading visualization...
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 with advisory reservations surfaces conflicts immediately.

Agents coordinate in real time through threaded messaging instead of accumulating silent divergence. The result: zero merge debt, zero lost work, and immediate conflict resolution.

Git Worktrees

  • Merge debt accumulates silently
  • Divergence discovered too late
  • N copies of entire repo
  • Lost work on failed merges

Agent Mail

  • Conflicts surface immediately
  • Reservations prevent collisions
  • Single shared workspace
  • Zero merge debt
Identity

Semi-Persistent Identity

Each agent gets a memorable identity (GreenCastle, BlueLake, RedHarbor) that persists for the duration of a task, but can vanish without breaking coordination state.

This matters because agents crash, get context-wiped, and disappear constantly. The identity system is designed for this reality: TTL-based expiration cleans up after departed agents, and the contact handshake protocol re-establishes trust when agents rejoin.

Loading visualization...
Communication

Targeted, Not Broadcast

A naive implementation defaults to broadcast-to-all. Agents gravitate to whatever is easiest, so they will spam every peer with irrelevant information. Imagine if your work email defaulted to reply-all on every message.

Agent Mail uses targeted messaging with subjects,threads, and explicit recipients. Agents only receive messages addressed to them. Acknowledgment tracking ensures critical messages are processed, not just delivered.

Loading visualization...
Task Intelligence

Graph-Aware Task Prioritization

With hundreds of tasks, you do not want agents randomly choosing or wasting context window tokens negotiating. There is usually a clear best-next-task for each agent.

That 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 task will unlock the most downstream work.

Graph Analysis Signals

PageRank

Structural importance

Betweenness

Bottleneck detection

Critical Path

Longest dependency chain

What-If

Cascade impact prediction

bv combines these signals to recommend which task each agent should work on next.

Proven at Scale

40-50 Agents, Zero Issues

Agent Mail runs with 40-50 concurrent agents mixing Claude Code, Codex CLI, and Gemini CLI on the same project with no issues. This is production use, not a demo.

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.

Loading visualization...
Why Agent Mail

Built Different

Agent Mail is purpose-built coordination infrastructure for AI coding agents. Identity, messaging, file reservations, and task prioritization, all backed by SQLite and Git.

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

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

Coordination Comparison

Agent Mail bakes coordination guarantees into the infrastructure layer. Features that require manual discipline with ad-hoc solutions are enforced by the architecture.

Feature
Agent Mail
Git WorktreesShared DocsNo Coordination
Agent Identity
✓Persistent, project-scoped✕None⚠Manual naming✕None
Messaging
✓Threaded + searchable✕None⚠Append-only files✕None
File Conflict Prevention
✓Advisory reservations + guard⚠Isolated branches✕None✕None
Audit Trail
✓Git + SQLite⚠Git history only⚠File history✕None
Cross-Project Coordination
✓Product bus✕None✕None✕None
Search
✓Hybrid lexical + semantic⚠Git log⚠Text search✕None
Operator Visibility
✓15-screen TUI + Web UI⚠Git log⚠File browser✕None
MCP Integration
✓34 tools + 20 resources✕None✕None✕None
Agent Discovery
✓Auto-detect + register✕Manual✕Manual✕Manual
Acknowledgments
✓Built-in ack protocol✕None✕None✕None
Build Concurrency
✓Build slot management✕None✕None✕Race conditions
Stress Tested
✓10/10 gauntlet (30 agents)✕N/A✕N/A✕N/A
Before & After

What Changes

Real scenarios that multi-agent teams face daily, and how purpose-built coordination transforms the outcome.

Two agents edit the same file

Without Agent Mail

Silent overwrite. Hours of work lost. Discovered only at commit time, if at all.

With Agent Mail

Advisory file reservations surface the conflict before either agent starts. Agents negotiate via threaded messages or pick different files.

Zero lost work from file collisions

Isolating agents with Git worktrees

Without Agent Mail

Each agent works in a separate worktree. Divergence accumulates silently. Merge conflicts pile up. Development velocity drops as you pay back the debt later.

With Agent Mail

Agents work in one shared space with advisory reservations. Conflicts surface immediately and are resolved in real time through messaging. No merge debt.

Eliminates worktree merge debt entirely

Agent crashes or context resets mid-task

Without Agent Mail

Stale locks block other agents indefinitely. Manual cleanup required. No record of what the crashed agent was working on.

With Agent Mail

TTL-based reservations expire automatically. Other agents detect stale reservations and reclaim them. Full audit trail in Git shows exactly what happened.

Self-healing, no manual intervention needed

Agents broadcasting updates to all peers

Without Agent Mail

Every agent receives every message. Context windows fill with irrelevant information. Token costs spike. Signal-to-noise ratio collapses.

With Agent Mail

Targeted messaging with subjects, threads, and recipients. Agents only receive messages addressed to them. Acknowledgment tracking ensures nothing is missed.

Up to 10x reduction in coordination token waste

Scaling from 3 to 30+ concurrent agents

Without Agent Mail

Informal coordination breaks down completely. File conflicts multiply quadratically. No one knows who is doing what.

With Agent Mail

Agent roster shows all active agents and their tasks. File reservations prevent conflicts at any scale. Graph-aware task prioritization (bv) ensures each agent works on the highest-impact task.

Tested with 40-50 concurrent agents across providers
The Code

Clean API, Battle-Tested

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 
in
 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_ENCODED
Proven Reliability

Battle-Tested Numbers

Every claim is backed by reproducible benchmarks from the 10-scenario stress gauntlet and real-world multi-agent deployments.

Production-ready at scale

10-scenario stress gauntlet covering 30-agent message pipelines, pool exhaustion, thundering herd, stale lock recovery, and sustained mixed workloads.

10/10 scenarios pass with zero errors

Low-latency coordination

HTTP stress profile sustains ~49 RPS with 1,494 operations in 30 seconds of mixed workloads including messaging, search, and reservations.

~49 RPS sustained throughput

Minimal Git overhead

Commit coalescer batches multiple storage writes into fewer Git commits, reducing write amplification.

9.1x write reduction (100 writes to 11 commits)

Works with any MCP-capable agent

First open-source coordination system that works across providers. Battle-tested with Claude Code, Codex CLI, and Gemini CLI running simultaneously on the same project.

40-50 agents concurrently, mixed providers

Robust to agent failures

TTL-based reservation expiration, stale lock detection, and automatic cleanup. Designed for the reality that agents crash, context-reset, and disappear without notice.

Zero manual intervention for crashed agents
Development Timeline

From Prototype to Production

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
View Full Architecture

Built for How You Work

Whether you run solo or manage a fleet of agents, Agent Mail fits your workflow.

Solo developers running multiple AI agents

Stop watching agents fight over files

Advisory reservations and TTL expiration mean your agents coordinate instead of collide, even when they crash.

Get Started Free
Team leads managing AI-assisted development

See what every agent is doing, in real time

15-screen TUI, web dashboard, and robot mode CLI give you full visibility. Human Overseer lets you intervene when needed.

View Dashboard Demo
Platform engineers building agent infrastructure

The coordination layer your agent platform is missing

34 MCP tools, cross-provider compatibility, and a stress gauntlet proving 40+ concurrent agents. MIT licensed.

Explore Architecture
Common Objections

Honest Answers

We have heard every reason not to adopt a coordination layer. Here is why each one is wrong.

“We already use Git branches for isolation”

Branches isolate code but not communication. When Agent A needs to tell Agent B it changed an API, branches have no mechanism for that. Agent Mail adds the coordination layer that Git lacks.

The comparison table shows 12 capabilities where Git worktrees have gaps in messaging, identity, search, and operator visibility.

“This adds too much complexity to our workflow”

Agent Mail is a single binary (am) with a one-line install. The macro_start_session call bootstraps everything in one step. You do not need to configure databases, message brokers, or cloud services.

Install: curl | bash. Start: am. Bootstrap: one tool call. The getting-started path is under 60 seconds.

“Advisory locks will not work at scale”

The stress gauntlet runs 30 concurrent agents across 10 projects with mixed workloads. Advisory reservations with TTL expiration prevent deadlocks while the guard hook provides enforcement when needed.

10/10 stress gauntlet scenarios pass: 1,494 ops in 30s, pool exhaustion recovery, thundering herd handling.

“I do not want to depend on another tool”

Agent Mail is open source (MIT), local-first, and stores everything in Git + SQLite. There are no cloud dependencies, no API keys, no accounts. If you stop using it, your data is still in standard formats.

MIT license, all data in Git repos and SQLite databases, no network calls required for core functionality.

“Our agents work fine without coordination”

They work fine until they do not. The first time two agents edit the same file, you lose hours of work. Agent Mail prevents that failure mode while adding structured communication that makes multi-agent workflows more productive.

Every team that has run 3+ concurrent agents has hit file collision issues. Reservations make these impossible.

From the Creator

Design Philosophy

“Worktrees suck and just kick the can down the road. Advisory file reservations and messaging ftw.”

On running 40-50 agents simultaneously with no issues, mixing Claude Code, Codex, and Gemini CLI.

“It does exactly what they want and much more, while sidestepping all the many footguns that a naive implementation would fall prey to.”

On why purpose-built coordination beats ad-hoc solutions.

“You want semi-persistent identity. An identity that can last for the duration of a discrete task, but one that can also vanish without a trace and not break things.”

On designing identity systems robust to agent crashes and context resets.

“It's like a compass that each agent can use to tell them which direction will unlock the most work overall.”

On how bv uses dependency graph analysis to prioritize agent work.

“You're going to be hearing about a lot of agent communication systems soon because it's such an obviously good idea, but mine was the first open-source system that works across providers, and still has the best design.”

On Agent Mail's position as the first cross-provider coordination system.

Ready to Build?

Add Agent Mail to your project with a single command. Coordinate 40+ concurrent AI agents from any provider with zero conflicts.

terminal
$cargo install mcp_agent_mail_rust
MIT License · Free & Open Source
Get Started
Loading visualization...