Back
13/65
Lesson 13
10 min
Agent Mail Coordination
Multi-agent messaging and file reservations
Ready to level up?
Mark complete to track your learning progress.
Multi-agent messaging and file reservations
Mark complete to track your learning progress.
Coordinate multiple agents without conflicts using Agent Mail.
MCP Agent Mail is a coordination system that lets multiple AI agents work on the same project without stepping on each other's toes.
Think of it as email + file locking for agents. Agents can send messages, claim files they're working on, and stay in sync—all persisted in git.
Agents send and receive messages with context
Advisory locks prevent edit conflicts
Find past decisions and discussions
All artifacts are human-auditable in git
Without coordination, multiple agents working on the same codebase can:
Each project has registered agents with unique names
# Agent names are adjective+noun combinations# Examples: "BlueLake", "GreenCastle", "RedStone"# Register an agentensure_project(human_key="/data/projects/my-app")register_agent(project_key="/data/projects/my-app",program="claude-code",model="opus-4.5")
Agents communicate via structured messages
send_message(project_key="/data/projects/my-app",sender_name="BlueLake",to=["GreenCastle"],subject="API design question",body_md="Should we use REST or GraphQL for the new endpoint?")
Claim files before editing to prevent conflicts
# Reserve files before editingfile_reservation_paths(project_key="/data/projects/my-app",agent_name="BlueLake",paths=["src/api/*.py", "src/routes/*.py"],ttl_seconds=3600, # 1 hour leaseexclusive=true # No one else can edit)# Release when donerelease_file_reservations(project_key="/data/projects/my-app",agent_name="BlueLake")
Fetch messages addressed to you
# Check for new messagesfetch_inbox(project_key="/data/projects/my-app",agent_name="BlueLake",since_ts="2025-01-15T10:00:00Z",include_bodies=true)# Acknowledge important messagesacknowledge_message(project_key="/data/projects/my-app",agent_name="BlueLake",message_id=1234)
Use the macro for quick setup
macro_start_session(human_key="/data/projects/my-app",program="claude-code",model="opus-4.5",task_description="Implementing auth")
Keep discussions organized
reply_message(project_key="/data/projects/my-app",message_id=1234,sender_name="GreenCastle",body_md="I agree, let's use GraphQL. Starting work now.")
Find relevant context
search_messages(project_key="/data/projects/my-app",query="authentication AND JWT",limit=10)
Real-time coordination simulation
BlueLake
API development
No file reservations
No messages yet
GreenCastle
UI integration
No file reservations
No messages yet
RedStone
Database layer
No file reservations
No messages yet
src/api.tssrc/auth.tssrc/ui.tsxsrc/db.tssrc/utils.tssrc/config.tsPress Play or Next to begin the coordination simulation
Reserve before editing
Always claim files before making changes to prevent conflicts
Keep subjects specific
Use descriptive subjects (≤80 chars) for easy searching
Use thread_id consistently
Keep related discussions in the same thread
Set realistic TTLs
Don't hold file reservations longer than needed
Acknowledge when required
Use acknowledge_message for ack_required messages
FILE_RESERVATION_CONFLICT, another agent has the file. Wait for expiry, adjust your patterns, or use non-exclusive reservations.ensure_projectInitialize a projectregister_agentRegister your identitysend_messageSend a messagereply_messageReply to a threadfetch_inboxGet your messagesacknowledge_messageConfirm receiptfile_reservation_pathsClaim filesrelease_file_reservationsRelease filessearch_messagesSearch threadsmacro_start_sessionQuick session setup