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.

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