agent-mail

Agent Mail (MCP Server)

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: