Back
13/61
Lesson 13
10 min

Agent Mail Coordination

Multi-agent messaging and file reservations

New to ACFS?

Complete the setup wizard first to get the most from these lessons.

Go to Choose Your OS
Goal

Coordinate multiple agents without conflicts using Agent Mail.

What Is 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.

Messaging

Agents send and receive messages with context

File Reservations

Advisory locks prevent edit conflicts

Searchable Threads

Find past decisions and discussions

Git Persistence

All artifacts are human-auditable in git

Why Coordination Matters

Without coordination, multiple agents working on the same codebase can:

✗
Overwrite each other's changes
→
✓
File reservations prevent conflicts
✗
Duplicate work on the same task
→
✓
Message threads track who's doing what
✗
Make conflicting architectural decisions
→
✓
Shared context via searchable threads
Note
Agent Mail is available as an MCP server. Your agents can use it automatically when configured!

Core Concepts

Projects & Agents

Each project has registered agents with unique names

python
# Agent names are adjective+noun combinations
# Examples: "BlueLake", "GreenCastle", "RedStone"
# Register an agent
ensure_project(human_key="/data/projects/my-app")
register_agent(
  project_key="/data/projects/my-app",
  program="claude-code",
  model="opus-4.5"
)

Sending Messages

Agents communicate via structured messages

python
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?"
)

File Reservations

Claim files before editing to prevent conflicts

python
# Reserve files before editing
file_reservation_paths(
  project_key="/data/projects/my-app",
  agent_name="BlueLake",
  paths=["src/api/*.py", "src/routes/*.py"],
  ttl_seconds=3600,  # 1 hour lease
  exclusive=true     # No one else can edit
)
# Release when done
release_file_reservations(
  project_key="/data/projects/my-app",
  agent_name="BlueLake"
)

Checking Your Inbox

Fetch messages addressed to you

python
# Check for new messages
fetch_inbox(
  project_key="/data/projects/my-app",
  agent_name="BlueLake",
  since_ts="2025-01-15T10:00:00Z",
  include_bodies=true
)
# Acknowledge important messages
acknowledge_message(
  project_key="/data/projects/my-app",
  agent_name="BlueLake",
  message_id=1234
)

Common Patterns

Starting a Session

Use the macro for quick setup

python
macro_start_session(
  human_key="/data/projects/my-app",
  program="claude-code",
  model="opus-4.5",
  task_description="Implementing auth"
)

Replying to a Thread

Keep discussions organized

python
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."
)

Searching Past Discussions

Find relevant context

python
search_messages(
  project_key="/data/projects/my-app",
  query="authentication AND JWT",
  limit=10
)

The Coordination Flow

Agent Mail System

Real-time coordination simulation

Mail Hub

BlueLake

API development

No file reservations

Messages

No messages yet

GreenCastle

UI integration

No file reservations

Messages

No messages yet

RedStone

Database layer

No file reservations

Messages

No messages yet

File Reservation Map
src/api.ts
Free
src/auth.ts
Free
src/ui.tsx
Free
src/db.ts
Free
src/utils.ts
Free
src/config.ts
Free
Activity Log

Start the simulation to see activity

Press Play or Next to begin the coordination simulation

Best Practices

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

Warning
If you see FILE_RESERVATION_CONFLICT, another agent has the file. Wait for expiry, adjust your patterns, or use non-exclusive reservations.

Quick Reference

Key Functions
ensure_projectInitialize a project
register_agentRegister your identity
send_messageSend a message
reply_messageReply to a thread
fetch_inboxGet your messages
acknowledge_messageConfirm receipt
file_reservation_pathsClaim files
release_file_reservationsRelease files
search_messagesSearch threads
macro_start_sessionQuick session setup

Ready to level up?

Mark complete to track your learning progress.