Learning HubACFS Academy
Progress
0%
0 of 2020 remaining
  • 1
    Welcome & Overview5 min
  • 2
    Linux Navigation8 min
  • 3
    SSH & Persistence6 min
  • 4
    tmux Basics7 min
  • 5
    Git Essentials10 min
  • 6
    GitHub CLI8 min
  • 7
    Agent Commands10 min
  • 8
    NTM Command Center8 min
  • 9
    NTM Prompt Palette6 min
  • 10
    The Flywheel Loop10 min
  • 11
    Keeping Updated4 min
  • 12
    UBS: Code Quality Guardrails8 min
  • 13
    Agent Mail Coordination10 min
    NOW
  • 14
    CASS: Learning from History8 min
  • 15
    The Memory System8 min
  • 16
    Beads: Issue Tracking8 min
  • 17
    Safety Tools: SLB & CAAM6 min
  • 18
    The Art of Agent Direction12 min
  • 19
    Case Study: cass-memory15 min
  • 20
    Case Study: SLB12 min
Back to Home
Back
13/20
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

Register

Agent joins the project with a unique name

→

Reserve

Claim files before editing

→

Communicate

Send messages to coordinate

→

Work

Make changes within your reservation

→

Release

Free files for other agents

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.

Previous
UBS: Code Quality Guardrails
Next
CASS: Learning from History