Explore Agent Mail's key concepts through interactive visualizations.
Watch five AI agents coordinate in real time. Messages flow as particles, files get reserved as colored territories, tasks complete and conflicts get caught, all without a human in the loop.
This simulation models the steady-state of a real Agent MailAgent MailCoordination infrastructure for AI coding agentsMCP Agent Mail provides the full operational fabric for multi-agent coding: identities, threaded messaging, file reservations, search, audit trails, and operator tooling, all backed by SQLite + Git. deployment. Five agents with persistent identitiesAgent IdentityMemorable persistent name for an agentEach agent gets an adjective+noun identity (GreenCastle, BlueLake, RedHarbor) that persists across sessions. Identities are project-scoped and carry program/model metadata for context. (GreenCastle, BlueLake, RedHarbor, GoldPeak, CoralBay) work on a shared codebase simultaneously. Each tick, agents send messages, claim file reservationsFile ReservationAdvisory lease on file pathsAn agent declares intent to edit specific file patterns (globs like src/auth/**/*.ts) for a given TTL. Other agents see the reservation and can coordinate accordingly. Conflicts are surfaced but not hard-blocked., complete tasks, and occasionally collide. Conflicts are caught instantly instead of discovered hours later in a merge.
The constellation layout shows the social topology: agents are nodes, messages are particles traveling between them. The reservation bar below shows which agent holds which glob patternsGlob PatternWildcard file path matcherA pattern like src/auth/**/*.ts that matches files using wildcards. Agents reserve glob patterns rather than individual files, so a single reservation can cover an entire directory tree., with real-time ownership tracking. The event feed on the right captures every coordination action as it happens.
Notice that no central coordinator directs the swarm. Each agent makes local decisions using the same MCPMCPModel Context ProtocolAn open standard for connecting AI models to external tools and data sources. Agent Mail exposes its 34 tools and 20+ resources via MCP, making it compatible with any MCP-capable coding agent. tools, and shared coordination state in Agent MailAgent MailCoordination infrastructure for AI coding agentsMCP Agent Mail provides the full operational fabric for multi-agent coding: identities, threaded messaging, file reservations, search, audit trails, and operator tooling, all backed by SQLite + Git. keeps them aligned. Scale this pattern from five agents to fifty and the same guarantees hold, because safety comes from the protocol, not from any single agent's context windowContext WindowToken budget available to an LLMThe fixed-size buffer of tokens an LLM can process in a single session. Coordination chatter (status updates, broadcasts, trace dumps) consumes context window space that would otherwise be available for reasoning and code generation..
Without coordination, multiple agents silently overwrite each other's work. With Agent Mail, file reservations prevent conflicts before they happen.
The left panel shows what happens without coordination: agents blindly edit the same files, and later agents silently overwrite earlier work. The result is wasted compute, lost changes, and humans spending hours diagnosing merge conflicts that could have been prevented entirely.
The right panel shows the same workload with Agent MailAgent MailCoordination infrastructure for AI coding agentsMCP Agent Mail provides the full operational fabric for multi-agent coding: identities, threaded messaging, file reservations, search, audit trails, and operator tooling, all backed by SQLite + Git.. Before editing, each agent reserves its file patternsGlob PatternWildcard file path matcherA pattern like src/auth/**/*.ts that matches files using wildcards. Agents reserve glob patterns rather than individual files, so a single reservation can cover an entire directory tree.. Overlapping claims are blocked immediately with a clear conflict message naming the holder. Agents self-organize into non-overlapping territories, and all six files get edited in parallel with zero wasted work.
This difference compounds with scale. Two agents might survive without coordination through luck; ten will not. File reservationsFile ReservationAdvisory lease on file pathsAn agent declares intent to edit specific file patterns (globs like src/auth/**/*.ts) for a given TTL. Other agents see the reservation and can coordinate accordingly. Conflicts are surfaced but not hard-blocked. make collision impossible rather than merely unlikely, and the pre-commit guardPre-Commit GuardGit hook enforcing file reservationsThe mcp-agent-mail-guard binary installs as a Git pre-commit hook. It checks whether committed files overlap with another agent’s active reservations and blocks the commit if so. Bypassable with AGENT_MAIL_BYPASS=1. catches any accidental boundary violations at commit time as a second line of defense.
Chat-based coordination burns context windowContext WindowToken budget available to an LLMThe fixed-size buffer of tokens an LLM can process in a single session. Coordination chatter (status updates, broadcasts, trace dumps) consumes context window space that would otherwise be available for reasoning and code generation. tokens. Agent Mail keeps coordination off the token budget entirely.
Every token spent on coordination is a token not spent on actual coding. When agents coordinate through chat (pasting status updates, sharing traces, broadcasting to all), the context windowContext WindowToken budget available to an LLMThe fixed-size buffer of tokens an LLM can process in a single session. Coordination chatter (status updates, broadcasts, trace dumps) consumes context window space that would otherwise be available for reasoning and code generation. fills fast. By step 10, the chat-based approach has burned over 60% of its budget on overhead alone.
Agent MailAgent MailCoordination infrastructure for AI coding agentsMCP Agent Mail provides the full operational fabric for multi-agent coding: identities, threaded messaging, file reservations, search, audit trails, and operator tooling, all backed by SQLite + Git. stores all messages, threads, and search indices externally in a Git-backed archive with SQLite FTS5FTS5SQLite full-text search engineThe full-text search extension built into SQLite. Agent Mail uses FTS5 to index message subjects, bodies, and metadata, enabling sub-millisecond keyword search across the entire message archive without external search infrastructure. indexing. Tool calls like send_message and fetch_inbox cost only a few hundred tokens each. The context windowContext WindowToken budget available to an LLMThe fixed-size buffer of tokens an LLM can process in a single session. Coordination chatter (status updates, broadcasts, trace dumps) consumes context window space that would otherwise be available for reasoning and code generation. stays free for reasoning and code generation.
Toggle between the two approaches in the visualization to see the divergence over time. The gap widens with each coordination step because chat-based overhead is cumulative: every past message stays in context, while MCPMCPModel Context ProtocolAn open standard for connecting AI models to external tools and data sources. Agent Mail exposes its 34 tools and 20+ resources via MCP, making it compatible with any MCP-capable coding agent. tool calls are stateless requests against external storage.
The Python version failed under load because of git lock contention. The Rust rewrite batches rapid-fire writes into far fewer commits, achieving a 9.1x compression ratio.
When 30 agents send messages simultaneously, each message triggers a Git commit to the archive. Without batching, this creates massive lock contention on Git's index.lock file. This was the exact failure mode that plagued the Python implementation under real-world load.
The commit coalescerCommit CoalescerBatches Git commits for efficiencyInstead of creating a Git commit for every write operation, the storage layer batches multiple writes into fewer commits. Stress tests show a 9.1x reduction (100 writes → 11 commits). uses a write-behind queueWrite-Behind QueueBuffered async write pipelineA queue that accumulates rapid-fire write operations and flushes them as batch commits on a configurable interval. Decouples write latency from archive durability, allowing the system to acknowledge writes instantly while persisting them in the background. that accumulates rapid writes and flushes them as a single batch commit. In stress tests, 100 concurrent writes collapse into just 11 commits: a 9.1x reduction with zero lock errors, zero timeouts, and zero data loss.
The pipeline visualization shows writes entering the buffer, coalescing, and emerging as compact batch commits. Adjust the message rate to see how the coalescer adapts; higher throughput produces larger batches, and the compression ratio improves with load rather than degrading.
See file ownershipFile ReservationAdvisory lease on file pathsAn agent declares intent to edit specific file patterns (globs like src/auth/**/*.ts) for a given TTL. Other agents see the reservation and can coordinate accordingly. Conflicts are surfaced but not hard-blocked. as a spatial map. Agents claim glob patternsGlob PatternWildcard file path matcherA pattern like src/auth/**/*.ts that matches files using wildcards. Agents reserve glob patterns rather than individual files, so a single reservation can cover an entire directory tree., territories light up, conflicts flash red, and TTLTTLTime-to-live for reservationsFile reservations and build slots expire after their TTL (default 3600 seconds). Agents can renew before expiration. Expired reservations are automatically cleaned up, preventing stale locks.-based expiry prevents deadlocks from crashed agents.
File reservationsFile ReservationAdvisory lease on file pathsAn agent declares intent to edit specific file patterns (globs like src/auth/**/*.ts) for a given TTL. Other agents see the reservation and can coordinate accordingly. Conflicts are surfaced but not hard-blocked. are advisory, TTL-based leasesAdvisory LockNon-blocking coordination signalFile reservations in Agent Mail are advisory: they surface conflicts and enable the pre-commit guard, but they can always be bypassed. This prevents deadlocks while still making ownership visible., not hard locks. This treemap renders a project's file structure as a spatial layout. When an agent reserves a glob patternGlob PatternWildcard file path matcherA pattern like src/auth/**/*.ts that matches files using wildcards. Agents reserve glob patterns rather than individual files, so a single reservation can cover an entire directory tree. like src/auth/**, matching files light up in that agent's color.
Watch the scenario unfold: four agents claim non-overlapping territories, a fifth agent tries to claim an occupied zone and gets blocked, then the original holder releases. Reservations expire on TTLTTLTime-to-live for reservationsFile reservations and build slots expire after their TTL (default 3600 seconds). Agents can renew before expiration. Expired reservations are automatically cleaned up, preventing stale locks., so a crashed agent never holds files hostage indefinitely.
The pre-commit guardPre-Commit GuardGit hook enforcing file reservationsThe mcp-agent-mail-guard binary installs as a Git pre-commit hook. It checks whether committed files overlap with another agent’s active reservations and blocks the commit if so. Bypassable with AGENT_MAIL_BYPASS=1. enforces these boundaries at commit time, catching accidental edits to reserved files before they reach the repository. This two-layer approach (advisory visibility first, enforcement second) gives agents maximum flexibility while preventing the conflict scenarios that make multi-agent coding fragile.
A live split-screen race showing how the Rust write-behind queueWrite-Behind QueueBuffered async write pipelineA queue that accumulates rapid-fire write operations and flushes them as batch commits on a configurable interval. Decouples write latency from archive durability, allowing the system to acknowledge writes instantly while persisting them in the background. eliminates Git lock contention that plagued the Python implementation.
The Python implementation committed every message individually to the Git archive. Under 30-agent load, this created massive index.lock contention, the failure mode that prompted the Rust rewrite.
The Rust side uses a write-behind queueWrite-Behind QueueBuffered async write pipelineA queue that accumulates rapid-fire write operations and flushes them as batch commits on a configurable interval. Decouples write latency from archive durability, allowing the system to acknowledge writes instantly while persisting them in the background. that accumulates rapid-fire messages and flushes them as batch commits. In the 10-test stress gauntletStress Gauntlet10-scenario production readiness test suiteA comprehensive stress test suite covering: 30-agent message pipelines, 10-project concurrent ops, commit coalescer batching, stale lock recovery, mixed reservations + messages, pool exhaustion, sustained throughput, thundering herd, and inbox reads during storms., 100 concurrent writes collapsed into just 11 commits: a 9.1x reduction. Lock-free Git plumbing commits avoid index.lock entirely.
Adjust the message rate and batch window to see how throughput changes. The split-screen layout makes the performance difference visceral: the Python side accumulates errors while the Rust side processes the same workload cleanly. This is the kind of regression that only surfaces under real multi-agent load, which is exactly what the stress gauntletStress Gauntlet10-scenario production readiness test suiteA comprehensive stress test suite covering: 30-agent message pipelines, 10-project concurrent ops, commit coalescer batching, stale lock recovery, mixed reservations + messages, pool exhaustion, sustained throughput, thundering herd, and inbox reads during storms. is designed to catch.
Every message flows through two parallel paths simultaneously: SQLite for sub-millisecond queries, and Git for a human-auditable, diffable archive.
Neither SQLite nor Git is sufficient alone. SQLite gives sub-millisecond FTS5FTS5SQLite full-text search engineThe full-text search extension built into SQLite. Agent Mail uses FTS5 to index message subjects, bodies, and metadata, enabling sub-millisecond keyword search across the entire message archive without external search infrastructure. full-text search and structured queries, but it is opaque to humans and hard to diff. Git gives a human-readable, diffable audit trail, but it is too slow for real-time agent queries.
Watch the split point: each send_message call spawns two parallel data flows. The SQLite path completes in microseconds. The Git path accumulates in the write-behind queueWrite-Behind QueueBuffered async write pipelineA queue that accumulates rapid-fire write operations and flushes them as batch commits on a configurable interval. Decouples write latency from archive durability, allowing the system to acknowledge writes instantly while persisting them in the background. and flushes as batch commits via the commit coalescerCommit CoalescerBatches Git commits for efficiencyInstead of creating a Git commit for every write operation, the storage layer batches multiple writes into fewer commits. Stress tests show a 9.1x reduction (100 writes → 11 commits)., decoupling write latency from archive durability.
Toggle "Show Read Paths" to see how each store serves different consumers. Agents query SQLite for speed; operators browse the Git archive for auditing. Both stores contain the same data, but optimized for their respective access patterns. The dual-write design means neither store is a single point of failure: if SQLite is corrupted, the Git archive can reconstruct it.
The system continuously monitors pool utilization, WBQWrite-Behind QueueBuffered async write pipelineA queue that accumulates rapid-fire write operations and flushes them as batch commits on a configurable interval. Decouples write latency from archive durability, allowing the system to acknowledge writes instantly while persisting them in the background. depth, and commit queue pressure. Under overload, backpressureBackpressureFlow control under overloadWhen incoming request rate exceeds processing capacity, the system applies backpressure by shedding low-priority work (maintenance tools like archive_repair) while always admitting high-priority operations (send_message, fetch_inbox). This prevents cascading failure under load spikes. sheds low-priority maintenance while high-priority messaging always flows.
Agent MailAgent MailCoordination infrastructure for AI coding agentsMCP Agent Mail provides the full operational fabric for multi-agent coding: identities, threaded messaging, file reservations, search, audit trails, and operator tooling, all backed by SQLite + Git. tracks four health signals in real time: connection pool utilization, pool acquire P95 latency, write-behind queueWrite-Behind QueueBuffered async write pipelineA queue that accumulates rapid-fire write operations and flushes them as batch commits on a configurable interval. Decouples write latency from archive durability, allowing the system to acknowledge writes instantly while persisting them in the background. depth, and commit queue pending count. When any signal crosses a threshold, the system transitions from Green to Yellow to Red.
Under Red, backpressureBackpressureFlow control under overloadWhen incoming request rate exceeds processing capacity, the system applies backpressure by shedding low-priority work (maintenance tools like archive_repair) while always admitting high-priority operations (send_message, fetch_inbox). This prevents cascading failure under load spikes. kicks in: low-priority tools like archive_repair and compact_index are rejected immediately. High-priority tools like fetch_inbox and send_message are never shed. Agent communication always flows, even under extreme load.
Drag the load slider to see backpressureBackpressureFlow control under overloadWhen incoming request rate exceeds processing capacity, the system applies backpressure by shedding low-priority work (maintenance tools like archive_repair) while always admitting high-priority operations (send_message, fetch_inbox). This prevents cascading failure under load spikes. in action. The priority distinction matters because maintenance can always be retried later, but an agent blocked on its inbox is an agent burning tokens while waiting. Shedding the right work under pressure keeps the system responsive where it counts.
Every commit runs a battery of 10 concurrent stress tests that validate the system under extreme multi-agent conditions, from 50-thread thundering herds to 30-second sustained loads.
The Python implementation failed under real-world multi-agent load due to three root causes: Git lock contention, SQLite pool exhaustion, and cascading failures when agents stormed the system simultaneously. The Rust rewrite eliminates all three and proves it with a 10-test gauntletStress Gauntlet10-scenario production readiness test suiteA comprehensive stress test suite covering: 30-agent message pipelines, 10-project concurrent ops, commit coalescer batching, stale lock recovery, mixed reservations + messages, pool exhaustion, sustained throughput, thundering herd, and inbox reads during storms..
Click "Run Gauntlet" to watch all 10 tests execute sequentially. Each test targets a specific failure mode: pool warmup validates zero SQLITE_BUSY errors, thundering herd proves idempotent agent registration, WBQWrite-Behind QueueBuffered async write pipelineA queue that accumulates rapid-fire write operations and flushes them as batch commits on a configurable interval. Decouples write latency from archive durability, allowing the system to acknowledge writes instantly while persisting them in the background. saturation confirms zero fallbacks at 2000 writes, and sustained load maintains ~50 RPS for 30 seconds with sub-3-second P99 latency.
These are not synthetic benchmarks. Every scenario models a real failure that occurred in production with the Python implementation. The gauntlet runs on every commit, so regressions in concurrency handling are caught before they ship.
Send, persist, deliver, read/ack, and thread-index events are all explicit and auditable.
This flow models Agent MailAgent MailCoordination infrastructure for AI coding agentsMCP Agent Mail provides the full operational fabric for multi-agent coding: identities, threaded messaging, file reservations, search, audit trails, and operator tooling, all backed by SQLite + Git.'s operational core. Message tool calls persist canonical rows in SQLite, fan out inboxInboxPer-agent message queueEach registered agent has a project-scoped inbox where incoming messages are delivered. Agents fetch their inbox via fetch_inbox or the resource://inbox/{agent} MCP resource./outbox artifacts to the Git archive, and keep threadThreadConversation grouping by thread_idMessages sharing the same thread_id form a conversation thread. Threads enable context-aware communication; agents can review the full conversation history before replying. Thread IDs often map to bead/issue IDs (e.g., bd-123). continuity queryable across sessions. Every state transition (sent, delivered, read, acknowledged) is an explicit, logged event.
Toggle ack_required to compare explicit acknowledgementAcknowledgmentConfirmation that a message was receivedWhen a message is sent with ack_required=true, the recipient agent must explicitly acknowledge receipt. The system tracks ack status and can surface overdue acknowledgments to operators. workflows against standard read-only delivery. With acknowledgements enabled, the sender knows exactly when the recipient processed the message. Without them, delivery is fire-and-forget, suitable for informational broadcasts.
Both paths remain searchable and replayable through threadThreadConversation grouping by thread_idMessages sharing the same thread_id form a conversation thread. Threads enable context-aware communication; agents can review the full conversation history before replying. Thread IDs often map to bead/issue IDs (e.g., bd-123). and search surfaces. This matters when a new agent joins mid-conversation: the macro_prepare_threadMacroMulti-step MCP operation in one callAgent Mail provides four macros that combine common multi-tool workflows into single calls: macro_start_session, macro_prepare_thread, macro_file_reservation_cycle, and macro_contact_handshake. call lets it catch up on the full conversation history without any participant needing to repeat context.
Agents must explicitly request and approve contact before messaging each other.
To prevent an uncoordinated swarm from spamming each other, Agent MailAgent MailCoordination infrastructure for AI coding agentsMCP Agent Mail provides the full operational fabric for multi-agent coding: identities, threaded messaging, file reservations, search, audit trails, and operator tooling, all backed by SQLite + Git. enforces a strict contact handshakeContact HandshakeProtocol for establishing cross-agent communicationBefore agents in different projects can message each other, they perform a contact handshake: request_contact sends the invitation, respond_contact accepts or denies. Contact policies can auto-accept or block by default.. Before two agents can exchange messages, one must send request_contact and the other must explicitly approve with respond_contact. Until approval, all messages between them are blocked.
The visualization includes both approval and rejection branches so you can compare downstream behavior. Watch for the state boundary where permission flips from blocked to trusted. That transition is explicit, logged, and queryable.
This consent model is critical for post-incident reasoning: if an agent sent a bad instruction to another, the contact graph shows exactly who approved that communication channel and when. For cross-project coordination via the product busProduct BusCross-repository coordination layerLinks multiple Git repositories under a single product umbrella. Enables cross-project search, unified inbox aggregation, and inter-project contact management., the handshake also establishes trust across repository boundaries.
Agents use TTLTTLTime-to-live for reservationsFile reservations and build slots expire after their TTL (default 3600 seconds). Agents can renew before expiration. Expired reservations are automatically cleaned up, preventing stale locks.-based advisory locksAdvisory LockNon-blocking coordination signalFile reservations in Agent Mail are advisory: they surface conflicts and enable the pre-commit guard, but they can always be bypassed. This prevents deadlocks while still making ownership visible. to signal intent and avoid stepping on each other's edits.
Before editing a file, an agent requests an advisory lockAdvisory LockNon-blocking coordination signalFile reservations in Agent Mail are advisory: they surface conflicts and enable the pre-commit guard, but they can always be bypassed. This prevents deadlocks while still making ownership visible. via MCPMCPModel Context ProtocolAn open standard for connecting AI models to external tools and data sources. Agent Mail exposes its 34 tools and 20+ resources via MCP, making it compatible with any MCP-capable coding agent.. If another agent already holds a reservation on overlapping paths, the requester receives a conflict warning naming the holder, the held glob patternsGlob PatternWildcard file path matcherA pattern like src/auth/**/*.ts that matches files using wildcards. Agents reserve glob patterns rather than individual files, so a single reservation can cover an entire directory tree., and the remainingTTLTTLTime-to-live for reservationsFile reservations and build slots expire after their TTL (default 3600 seconds). Agents can renew before expiration. Expired reservations are automatically cleaned up, preventing stale locks..
Step through the three guardPre-Commit GuardGit hook enforcing file reservationsThe mcp-agent-mail-guard binary installs as a Git pre-commit hook. It checks whether committed files overlap with another agent’s active reservations and blocks the commit if so. Bypassable with AGENT_MAIL_BYPASS=1. modes (enforce, warn, bypass) to see how policy changes commit/push outcomes. In enforce mode, commits touching reserved files are blocked. In warn mode, they proceed with a logged warning. In bypass mode, reservations are purely informational.
The advisory design is deliberate: hard locks cause deadlocks when agents crash. With TTLTTLTime-to-live for reservationsFile reservations and build slots expire after their TTL (default 3600 seconds). Agents can renew before expiration. Expired reservations are automatically cleaned up, preventing stale locks.-based expiration, a crashed agent's reservations clear automatically. The guard adds enforcement for teams that want it, without making it mandatory for those who prefer lighter coordination.
Reservations and messages are inextricably linked to 'br' issue tracking.
A single bead ID (like br-123) threads through every coordination primitive: it becomes the thread_idThreadConversation grouping by thread_idMessages sharing the same thread_id form a conversation thread. Threads enable context-aware communication; agents can review the full conversation history before replying. Thread IDs often map to bead/issue IDs (e.g., bd-123). for messages, the reason field on file reservationsFile ReservationAdvisory lease on file pathsAn agent declares intent to edit specific file patterns (globs like src/auth/**/*.ts) for a given TTL. Other agents see the reservation and can coordinate accordingly. Conflicts are surfaced but not hard-blocked., and the subject prefix on commit messages. The entire swarm knows exactly why a file is locked and which conversation to follow for context.
Switch to "Discovered Work" mode to see what happens when an agent finds an out-of-scope bug while working on its assigned bead. Instead of silently fixing it (creating untraceable changes) or ignoring it (leaving technical debt), the agent creates a new bead linked with discovered-from:br-123, preserving the causal chain.
This linkage pattern prevents the orphan-task problem common in multi-agent workflows: tasks spawned without clear provenance that no one remembers creating. Every piece of discovered work traces back to the context that surfaced it.
The Model Context ProtocolMCPModel Context ProtocolAn open standard for connecting AI models to external tools and data sources. Agent Mail exposes its 34 tools and 20+ resources via MCP, making it compatible with any MCP-capable coding agent. connects LLM clients directly to the Rust-backed mail server.
Agent MailAgent MailCoordination infrastructure for AI coding agentsMCP Agent Mail provides the full operational fabric for multi-agent coding: identities, threaded messaging, file reservations, search, audit trails, and operator tooling, all backed by SQLite + Git. runs as an MCPMCPModel Context ProtocolAn open standard for connecting AI models to external tools and data sources. Agent Mail exposes its 34 tools and 20+ resources via MCP, making it compatible with any MCP-capable coding agent. server, accepting JSON-RPC requests over stdio (for Claude Code) or HTTP/SSE (for Cursor, Windsurf, and similar clients). A single Rust binary handles both transports, persisting everything locally to SQLite with a Git archive for durability.
Use the mode toggles to compare how messaging, reservation, and search requests traverse the same architecture. All three flows pass through the same coordination core, but they diverge at the persistence layer: messaging produces both SQLite rows and Git artifacts, reservations update SQLite state with TTL tracking, and search is a read-heavy path that mostly queries the FTS5FTS5SQLite full-text search engineThe full-text search extension built into SQLite. Agent Mail uses FTS5 to index message subjects, bodies, and metadata, enabling sub-millisecond keyword search across the entire message archive without external search infrastructure. index.
The single-binary design means there is no deployment complexity, no message broker, and no cloud dependency. The same mcp-agent-mail binary that agents connect to also serves the Web UIWeb UIBrowser-based operator interfaceServed at http://127.0.0.1:8765/mail, the web interface provides unified inbox, project overview, message details, search, file reservations, and the Human Overseer compose form for sending messages to agents. and the operator TUITUITerminal User Interface operations consoleA 15-screen interactive terminal interface built on frankentui. Provides real-time dashboards, message browsing, thread exploration, agent roster, search, reservation management, and system health monitoring..
Two-tier fusion combining lexical FTS5FTS5SQLite full-text search engineThe full-text search extension built into SQLite. Agent Mail uses FTS5 to index message subjects, bodies, and metadata, enabling sub-millisecond keyword search across the entire message archive without external search infrastructure. and semantic embedding retrieval with reciprocal rank fusion.
Search V3 parses each query into structured tokens, then routes them through two parallel tiers: FTS5FTS5SQLite full-text search engineThe full-text search extension built into SQLite. Agent Mail uses FTS5 to index message subjects, bodies, and metadata, enabling sub-millisecond keyword search across the entire message archive without external search infrastructure. lexical search for exact keyword matches and semantic embedding retrieval for conceptual similarity. Results from both tiers are fused via reciprocal rank fusion (RRF), then reranked by field-match strength and recency.
When a tier fails or returns no results, the pipeline gracefully degrades: semantic-only when FTS5 misses, lexical-only when embeddings are unavailable, and a chronological fallback scan as the last resort. This layered degradation ensures agents always get results, even under partial system failure.
Keep the same query preset while switching modes to see exactly how recall, relevance, and latency shift. The hybrid mode consistently outperforms either tier alone because keyword and semantic signals are complementary: keywords catch exact identifiers, while embeddings catch conceptually related messages that use different terminology.
Jump-key navigation across four screen categories: operations, coordination, observability, and system.
The TUITUITerminal User Interface operations consoleA 15-screen interactive terminal interface built on frankentui. Provides real-time dashboards, message browsing, thread exploration, agent roster, search, reservation management, and system health monitoring. organizes 15 screens into four categories: operations (dashboard, inbox, threads), coordination (agents, reservations, contacts), observability (metrics, health, timeline), and system (search, projects, settings). Each screen answers a single core question and surfaces the primary signals an operator needs for fast decisions.
Jump keys provide O(1) navigation to any screen. Press d for dashboard, i for inbox, r for reservations. Filter by category in the visualization, then inspect the selected screen's core question to understand the information architecture behind each key.
The design principle: an operator should be able to assess swarm health, identify blocked agents, and intervene, all without leaving the terminal. The Web UIWeb UIBrowser-based operator interfaceServed at http://127.0.0.1:8765/mail, the web interface provides unified inbox, project overview, message details, search, file reservations, and the Human Overseer compose form for sending messages to agents. provides the same data for browser-based workflows, but the TUI is optimized for the keyboard-driven speed that incident response demands.
16 non-interactive commands across 5 tracks with toonToon FormatToken-efficient robot output formatThe default output format for robot mode at a TTY. Compact, human-scannable, and designed to minimize token consumption when agents parse the output. Alternative formats: json and md., JSON, and Markdown output formats.
Robot modeRobot ModeNon-interactive CLI for agent consumptionThe ‘am robot’ subcommand provides 16 commands (status, inbox, timeline, thread, search, etc.) that output token-efficient toon, JSON, or Markdown. Designed for agent consumption, not human interaction. provides agents with 16 non-interactive commands designed for machine consumption. The toon formatToon FormatToken-efficient robot output formatThe default output format for robot mode at a TTY. Compact, human-scannable, and designed to minimize token consumption when agents parse the output. Alternative formats: json and md. minimizes token usage with a compact, human-scannable layout. JSON provides full data fidelity for programmatic use. Markdown renders threads and messages for contexts where readability matters more than token efficiency.
Commands are organized into five tracks: status/health, inbox/messaging, search/discovery, reservations/coordination, and metrics/diagnostics. The command recipe panel demonstrates a practical sequence an agent can run to triage its workload, make a decision, and report back.
The distinction from the TUITUITerminal User Interface operations consoleA 15-screen interactive terminal interface built on frankentui. Provides real-time dashboards, message browsing, thread exploration, agent roster, search, reservation management, and system health monitoring. is critical. The TUI is an interactive terminal application for human operators. If an AI agent accidentally launches it, the system immediately exits to prevent the agent from burning tokens parsing ANSI escape sequences. Robot mode is the agent-safe counterpart: every command produces structured output and exits cleanly.
Link repositories under products for unified search, cross-project messaging, and contact-governed communication.
The product busProduct BusCross-repository coordination layerLinks multiple Git repositories under a single product umbrella. Enables cross-project search, unified inbox aggregation, and inter-project contact management. groups multiple repositories under a shared product umbrella. Once linked, agents can search across all repos, send messages to agents in other projects using name@project addressing, and coordinate via contact governanceContact HandshakeProtocol for establishing cross-agent communicationBefore agents in different projects can message each other, they perform a contact handshake: request_contact sends the invitation, respond_contact accepts or denies. Contact policies can auto-accept or block by default. policies.
The stepper makes the governance order explicit: a contact handshakeContact HandshakeProtocol for establishing cross-agent communicationBefore agents in different projects can message each other, they perform a contact handshake: request_contact sends the invitation, respond_contact accepts or denies. Contact policies can auto-accept or block by default. must succeed before cross-project messaging is permitted. This prevents a rogue agent in one repository from spamming agents in another. Once contacts are established, cross-project search lets an agent query the full message history across all linked repositories.
This architecture models how real codebases work: a frontend and backend repo need coordinated API changes, a shared library update affects all downstream consumers, or a migration spans multiple services. The product bus provides the coordination layer that repository boundaries would otherwise prevent.
Write batching, backpressureBackpressureFlow control under overloadWhen incoming request rate exceeds processing capacity, the system applies backpressure by shedding low-priority work (maintenance tools like archive_repair) while always admitting high-priority operations (send_message, fetch_inbox). This prevents cascading failure under load spikes. management, lock recovery, and worker loop health monitoring.
Agent MailAgent MailCoordination infrastructure for AI coding agentsMCP Agent Mail provides the full operational fabric for multi-agent coding: identities, threaded messaging, file reservations, search, audit trails, and operator tooling, all backed by SQLite + Git.'s SQLite storage layer coalesces individual writes into batched WALWALWrite-Ahead Log for crash safetySQLite's WAL (Write-Ahead Log) mode allows concurrent readers and a single writer without blocking. Agent Mail uses WAL mode to serve agent queries while the commit coalescer batches writes, combining high read throughput with durable writes. transactions. When 17 operations arrive in a 50ms burst, the commit coalescerCommit CoalescerBatches Git commits for efficiencyInstead of creating a Git commit for every write operation, the storage layer batches multiple writes into fewer commits. Stress tests show a 9.1x reduction (100 writes → 11 commits). groups them into a single atomic fsync, reducing I/O overhead by an order of magnitude while maintaining strict durability guarantees.
The backpressureBackpressureFlow control under overloadWhen incoming request rate exceeds processing capacity, the system applies backpressure by shedding low-priority work (maintenance tools like archive_repair) while always admitting high-priority operations (send_message, fetch_inbox). This prevents cascading failure under load spikes. system monitors write queue depth against a configurable threshold (default: 128). When the queue exceeds this limit, callers receive advisory backpressure signals to throttle submissions. Four independent worker loops (ACK processing, retention enforcement, metrics collection, and integrity checking) each recover gracefully from stalls without blocking the others.
Toggle between normal and stress profiles to see how queue pressure and commit latency shift under load. The key insight: these internals are invisible during normal operation, but they determine whether the system degrades gracefully or cascades into failure when 30 agents hit it simultaneously.
Strict entrypoint separation prevents agents from hallucinating infinite TUI interactions.
Agent MailAgent MailCoordination infrastructure for AI coding agentsMCP Agent Mail provides the full operational fabric for multi-agent coding: identities, threaded messaging, file reservations, search, audit trails, and operator tooling, all backed by SQLite + Git. ships as a single binary with two entrypoints. The mcp-agent-mail entrypoint starts the JSON-RPC MCPMCPModel Context ProtocolAn open standard for connecting AI models to external tools and data sources. Agent Mail exposes its 34 tools and 20+ resources via MCP, making it compatible with any MCP-capable coding agent. server for agent consumption. The am entrypoint launches the interactive TUITUITerminal User Interface operations consoleA 15-screen interactive terminal interface built on frankentui. Provides real-time dashboards, message browsing, thread exploration, agent roster, search, reservation management, and system health monitoring. for human operators. These two surfaces share the same core logic and database, but their runtime contexts are incompatible.
Select different context/command combinations in the visualization to see the guardrails in action. If a coding agent accidentally executes am, the system immediately exits with code 2. If a human runs the raw MCP server in a terminal, it gracefully aborts with guidance to use am instead.
The agent-side guardrail prevents a costly failure mode: an LLM interpreting ANSI escape sequences as text, then generating responses to phantom UI elements, burning thousands of tokens on hallucinated interactions. The human-side guardrail prevents a confusing failure mode: a blank terminal waiting for JSON-RPC input that a human would never type.
Prevent heavy concurrent compilations from thrashing CPU or corrupting the Cargo target directory lock.
When multiple agents attempt to compile the same codebase concurrently, the results range from slow builds to corrupted artifacts to Cargo.lock conflicts.Build slotsBuild SlotConcurrency control for compilationA lease that controls how many agents can run resource-intensive operations (like cargo build) simultaneously. Agents acquire, renew, and release build slots to prevent contention. solve this with acquire_build_slot, which lets agents request mutually exclusive runtime leases on critical computational resources.
The visualization shows agents queuing for build slots. When the pool is full, new requests wait rather than competing. Each slot has a TTLTTLTime-to-live for reservationsFile reservations and build slots expire after their TTL (default 3600 seconds). Agents can renew before expiration. Expired reservations are automatically cleaned up, preventing stale locks., so a crashed agent's slot is reclaimed automatically. Agents can renew active slots if their build takes longer than expected.
Like file reservationsFile ReservationAdvisory lease on file pathsAn agent declares intent to edit specific file patterns (globs like src/auth/**/*.ts) for a given TTL. Other agents see the reservation and can coordinate accordingly. Conflicts are surfaced but not hard-blocked., build slots are advisory and TTL-governed. The pattern is the same: signal intent, get confirmation, do the work, release. This consistency across Agent Mail's coordination primitives means agents learn one pattern and apply it to both file ownership and build concurrency.
Send absolute-priority override messages directly into any agent's inbox via the Web UI.
Traditional approaches to redirecting an AI agent require killing the session and restarting with new instructions, losing all accumulated context. The Human OverseerHuman OverseerWeb UI for operator interventionThe web interface at localhost:8765/mail allows humans to compose and send high-priority messages to agents, view all inboxes, search messages, and monitor file reservations across projects. mechanism injects messages with importance: urgent directly into any agent's inboxInboxPer-agent message queueEach registered agent has a project-scoped inbox where incoming messages are delivered. Agents fetch their inbox via fetch_inbox or the resource://inbox/{agent} MCP resource., bypassing all standard contact policiesContact HandshakeProtocol for establishing cross-agent communicationBefore agents in different projects can message each other, they perform a contact handshake: request_contact sends the invitation, respond_contact accepts or denies. Contact policies can auto-accept or block by default..
The visualization shows the message path from the Web UIWeb UIBrowser-based operator interfaceServed at http://127.0.0.1:8765/mail, the web interface provides unified inbox, project overview, message details, search, file reservations, and the Human Overseer compose form for sending messages to agents. compose form into a running agent's inbox. Urgent messages surface at the top of the fetch_inbox response, so agents process them before any queued normal-priority work.
This gives operators a live steering wheel for autonomous swarms. An agent heading down the wrong path can be redirected mid-task. A blocked agent can be unblocked with a priority override. A runaway swarm can be paused with a broadcast to all agents. The operator never needs to touch the agent's terminal session.