agent-mail

Multi-agent coordination: registration, file reservations, messaging, and build slots.

When This Applies

| Signal | Action | |--------|--------| | Starting a session | ensure_project + register_agent | | Before editing files | file_reservation_paths | | Communicating with agents | send_message / fetch_inbox | | Finishing work | release_file_reservations |

---

Registration (Required First)

# 1. Ensure project exists
ensure_project(human_key="/abs/path/to/project")

# 2. Register yourself (auto-generates name like "GreenCastle")
register_agent(
    project_key="/abs/path/to/project",
    program="claude-code",
    model="opus-4.5",
    task_description="Working on feature X"
)
# SAVE the returned agent name!

# 3. Set contact policy
set_contact_policy(
    project_key="/abs/path/to/project",
    agent_name="YOUR_AGENT_NAME",
    policy="open"
)

---

File Reservations

Reserve before editing:

file_reservation_paths(
    project_key="/abs/path",
    agent_name="YourName",
    paths=["src/module/**", "tests/test_module.py"],
    ttl_seconds=3600,
    exclusive=True,
    reason="bd-123: implementing feature"
)

Extend if needed:

renew_file_reservations(
    project_key="/abs/path",
    agent_name="YourName",
    extend_seconds=1800
)

Release when done:

release_file_reservations(
    project_key="/abs/path",
    agent_name="YourName"
)

---

Messaging

Send message:

send_message(
    project_key="/abs/path",
    sender_name="YourName",
    to=["OtherAgent"],
    subject="[CLAIMED] bd-123 - Feature Title",
    body_md="Starting work on **bd-123**.\n\nFile reservations: `src/module/**`",
    thread_id="bd-123",
    importance="normal"  # low, normal, high, urgent
)

Reply:

reply_message(
    project_key="/abs/path",
    message_id=123,
    sender_name="YourName",
    body_md="Acknowledged. Proceeding."
)

Check inbox:

fetch_inbox(
    project_key="/abs/path",
    agent_name="YourName",
    include_bodies=True,
    limit=10
)

# Urgent only
fetch_inbox(project_key, agent_name, urgent_only=True)

Acknowledge:

acknowledge_message(project_key, agent_name, message_id)

---

Discovery

Find other agents:

ReadMcpResourceTool(
    server="mcp-agent-mail",
    uri="resource://agents/PROJECT_PATH"
)

Search messages:

search_messages(project_key, query="authentication", limit=20)

Thread summary:

summarize_thread(project_key, thread_id="bd-123")

Who is this agent?

whois(project_key, agent_name="BlueLake")

---

Build Coordination

# Acquire build slot (prevents concurrent builds)
acquire_build_slot(project_key, agent_name, slot="main", exclusive=True)

# Release when done
release_build_slot(project_key, agent_name, slot="main")

---

Quick Start Macro (RECOMMENDED)

One call to start a session - use this instead of manual steps:

macro_start_session(
    human_key="/abs/path",
    program="claude-code",
    model="opus-4.5",
    file_reservation_paths=["src/**"],
    inbox_limit=10
)

This automatically:

1. Ensures project exists
2. Registers agent (auto-generates name)
3. Reserves specified files
4. Fetches recent inbox messages

Return value includes:

• agent_name: Your assigned name (e.g., "BlueLake")
• project: Project details
• file_reservations: Granted reservations
• inbox: Recent messages

---

Error Handling

Common Errors

| Error | Fix | |-------|-----| | "from_agent not registered" | Call register_agent first | | FILE_RESERVATION_CONFLICT | Wait for expiry or coordinate with holder | | "project not found" | Call ensure_project first |

Graceful Error Handling Pattern

When a tool call fails, include is_error: true in the result so Claude understands the failure:

# Example: Handling file reservation conflict
result = file_reservation_paths(
    project_key="/abs/path",
    agent_name="YourName",
    paths=["src/auth/**"],
    exclusive=True
)

if result.get("conflicts"):
    # Return error so Claude can adapt
    tool_result = {
        "type": "tool_result",
        "tool_use_id": tool_use_id,
        "is_error": True,  # CRITICAL: Tells Claude this failed
        "content": f"FILE_RESERVATION_CONFLICT: {result['conflicts'][0]['holders']}"
    }
    # Claude will now try a different approach or coordinate

Error Response Examples

# Conflict error
{
    "is_error": True,
    "content": "FILE_RESERVATION_CONFLICT: src/auth/** held by BlueLake (expires in 45min)"
}

# Registration error
{
    "is_error": True,
    "content": "AGENT_NOT_REGISTERED: Call register_agent() before sending messages"
}

# Project error
{
    "is_error": True,
    "content": "PROJECT_NOT_FOUND: Call ensure_project() with absolute path first"
}

Recovery Strategies

| Error Type | Recovery | |------------|----------| | FILE_RESERVATION_CONFLICT | Wait, coordinate via message, or pick different task | | AGENT_NOT_REGISTERED | Call register_agent() then retry | | PROJECT_NOT_FOUND | Call ensure_project() then retry | | MESSAGE_SEND_FAILED | Retry with exponential backoff |

---

Web UI

http://127.0.0.1:8765/mail

---

Quick Reference

# Startup
ensure_project(human_key=PATH)
register_agent(project_key=PATH, program="claude-code", model="opus-4.5")

# Files
file_reservation_paths(project_key, agent_name, paths, exclusive=True)
release_file_reservations(project_key, agent_name)

# Messaging
send_message(project_key, sender_name, to, subject, body_md, thread_id)
fetch_inbox(project_key, agent_name, include_bodies=True)
reply_message(project_key, message_id, sender_name, body_md)

---

See Also

• prime/ — Full startup protocol
• advance/ — Bead lifecycle with announcements