RsCxCx

Get Started

Install MCP Agent Mail, start the server, and launch your first reservation-aware multi-agent workflow.

Step 1

Install

Install the binary with the recommended one-liner.

$curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/mcp_agent_mail_rust/main/install.sh?$(date +%s)" | bash
Step 2

Run Your First Coordination Flow

Start `am`, register an agent, reserve files, and coordinate through threaded messages.

quickstart.md
01# 1) Start MCP Agent Mail server + TUI02am03 04# 2) Bootstrap session context 
in
 one call05macro_start_session(06  project_key="/abs/path/to/repo",07  program="codex-cli",08  model="gpt-5"09)10 11# 3) Reserve files before editing12file_reservation_paths(13  project_key,14  agent_name,15  ["src/**"],16  ttl_seconds=3600,17  exclusive=true18)19 20# 4) Coordinate through threaded messages21send_message(22  project_key,23  sender_name="GreenCastle",24  to=["BlueLake"],25  subject="Starting auth refactor",26  thread_id="FEAT-123",27  ack_required=true,28  body_md="I have reservations on src/auth/**; taking login + token rotation."29)30fetch_inbox(project_key, agent_name)31acknowledge_message(project_key, agent_name, message_id)
Syntax_Validation_Active
UTF-8_ENCODED
Step 3

Configure MCP Client

Add the MCP server entry once; then your agent CLI can call Agent Mail tools directly.

.mcp.json / .codex/config.json
01{02  "mcpServers": {03    "agent-mail": {04      "command": "mcp-agent-mail",05      "args": []06    }07  }08}
Syntax_Validation_Active
UTF-8_ENCODED
Core Patterns

Three Pillars

The foundations of safe multi-agent execution at scale.

Scoped Agent Identity

Project-scoped identities, thread continuity, and explicit inbox semantics keep parallel agents coordinated instead of colliding.

Reservation Guardrails

Advisory file reservations plus optional guard enforcement make ownership visible before edits and safer at commit time.

Auditable Workflows

Messages, acknowledgements, and search traces are queryable in SQLite and preserved in a Git-auditable archive.

Real-World Workflows

Use Cases

Concrete scenarios where Agent Mail coordination makes the difference between chaos and velocity.

Rapid Multi-Agent Prototyping

Launch 10+ agents on a new project with NTM. Each agent picks the highest-impact task via bv graph analysis. File reservations prevent collisions. Threaded messages coordinate API boundaries.

Ship a working prototype in hours, not days

Large-Scale Codebase Refactoring

Decompose a refactoring plan into beads with dependency tracking. Agents claim work, reserve affected files, and coordinate through thread IDs that map to bead IDs. The pre-commit guard prevents accidental conflicts.

Refactor 50+ files with zero merge conflicts

Cross-Repository API Migration

Link frontend and backend repos via the product bus. Agents working on the backend notify frontend agents of API changes through cross-project messages. Contact handshakes establish secure communication channels.

Coordinated migrations across repository boundaries

24/7 Continuous Development

Agents work in shifts. Incoming agents use macro_prepare_thread to catch up on conversation history. Semi-persistent identities mean agents can pick up where predecessors left off without breaking coordination state.

Continuous progress without context loss between sessions

Auditable Agent Operations

Every message, reservation, and agent action is recorded in SQLite and archived to Git. Searchable audit trail shows exactly what each agent did, when, and why. Human Overseer provides real-time oversight.

Complete audit trail for every agent decision
FAQ

Common Questions

Answers to common setup and operations questions for MCP Agent Mail.

Do I need to configure every agent manually?
No. Running `am` auto-detects common coding agents and can bootstrap MCP connectivity. Manual config snippets are still available for Claude Code, Codex CLI, and Gemini CLI when needed.
What is the fastest way to start on a repository?
Start `am`, then use `macro_start_session` to register the agent, fetch inbox context, and begin reservation-aware work in one step.
Are file reservations mandatory locks?
They are advisory coordination primitives with conflict visibility, plus optional pre-commit enforcement if you install the guard integration.
How does Agent Mail avoid losing message history?
Messages are recorded in SQLite for query speed and exported into a Git-auditable archive for durable, reviewable history.
Can this work across multiple repos/projects?
Yes. Product-level search, inbox aggregation, and cross-project contact workflows are built in for multi-repo coordination.
Read the System ArchitectureExplore Interactive Demos