agent-mail

MCP Agent Mail for multi-agent coordination. Use when agents need file locks, messaging, inboxes, or conflict prevention. Handles macro_start_session, file_reservation_paths, send_message, threading,

SKILL.md

GitHub
<!-- TOC: Bootstrap | Core Ops | File Reservations | Beads | Troubleshooting | Identity | Human Overseer | Pre-Commit Guard | References -->

Using MCP Agent Mail

Core Insight: Without coordination, multiple agents overwrite each other's work. Agent Mail provides identities, messaging, and file reservations to prevent conflicts.

When to Use What

Situation Action
Starting any agent session macro_start_session
About to edit files file_reservation_paths → edit → release_file_reservations
Need to tell another agent something send_message with thread_id
Picking up someone else's work macro_prepare_thread
Can't message an agent request_contact → wait for approval
Server seems broken Use health_check() first; CLI-only: doctor check --verbose → doctor repair --yes

THE EXACT PROMPT — Session Bootstrap

Call this at the start of every agent session:

macro_start_session(
  human_key="/abs/path/to/project",
  program="claude-code",
  model="YOUR_MODEL",
  task_description="Working on auth module"
)

Returns: {project, agent, file_reservations, inbox}

This single call: ensures project exists → registers your identity → fetches inbox.


Core Operations

Task Tool
Bootstrap session macro_start_session(human_key, program, model, task_description)
Send message send_message(project_key, sender_name, to, subject, body_md)
Reply in thread reply_message(project_key, message_id, sender_name, body_md)
Check inbox fetch_inbox(project_key, agent_name, limit=20)
Reserve files file_reservation_paths(project_key, agent_name, paths, ttl_seconds)
Release files release_file_reservations(project_key, agent_name)
Search messages search_messages(project_key, "query")

The Four Macros

Macro When to Use
macro_start_session Bootstrap: project → agent → inbox
macro_prepare_thread Join existing thread with summary
macro_file_reservation_cycle Reserve → work → auto-release
macro_contact_handshake Cross-agent contact setup

Fast Resource Reads (No Tool Call Required)

Need Resource
List agents resource://agents/{project_key}
Inbox resource://inbox/{agent}?project=/abs/path&limit=20
Thread resource://thread/{thread_id}?project=/abs/path&include_bodies=true
Ack-required resource://views/ack-required/{agent}?project=/abs/path

File Reservations

Reserve Before Editing

file_reservation_paths(
  project_key="/abs/path/project",
  agent_name="GreenCastle",
  paths=["src/auth/**/*.ts"],
  ttl_seconds=3600,
  exclusive=true,
  reason="bd-123"
)

Returns: {granted: [...], conflicts: [...]}

Conflict Resolution

If conflicts exist:

  1. Wait — TTL will expire
  2. Coordinate — Message the holder
  3. Share — Use exclusive=false

Release When Done

release_file_reservations(project_key="/abs/path/project", agent_name="GreenCastle")

Beads Integration

Use bead IDs as your threading anchor:

1. Pick work:        br ready --json → choose bd-123
2. Reserve files:    file_reservation_paths(..., reason="bd-123")
3. Announce:         send_message(..., thread_id="bd-123", subject="[bd-123] Starting...")
4. Work:             Reply in thread with progress
5. Complete:         br close bd-123, release_file_reservations(...), final message

Bead ID (often bd-###) goes in: thread_id, subject prefix, reservation reason, commit message


Quick Troubleshooting

Error Fix
"sender_name not registered" Call macro_start_session first
"FILE_RESERVATION_CONFLICT" Wait, coordinate, or use exclusive=false
"CONTACT_BLOCKED" Use request_contact, wait for approval
Empty inbox Check since_ts, urgent_only, agent name spelling
Server unreachable Use health_check() or resource://config/environment to confirm MCP server is up; if CLI-only, check curl http://127.0.0.1:8765/health
Guard blocks commit Set AGENT_NAME env var; bypass: AGENT_MAIL_BYPASS=1 git commit

Doctor Diagnostics (CLI-only, optional)

# Quick health check (CLI daemon)
curl http://127.0.0.1:8765/health

# Full diagnostics (CLI)
uv run python -m mcp_agent_mail.cli doctor check --verbose

# Preview repairs (dry run, CLI)
uv run python -m mcp_agent_mail.cli doctor repair --dry-run

# Apply repairs (CLI)
uv run python -m mcp_agent_mail.cli doctor repair --yes

Agent Identity

Agents get adjective+noun names: GreenCastle, BlueLake, RedBear.

Best practice: Omit name parameter to auto-generate valid names.

register_agent(
  project_key="/abs/path/project",
  program="claude-code",
  model="YOUR_MODEL",
  task_description="Auth refactor"
)  # name auto-generated

Human Overseer

Send urgent messages to agents from the web UI at http://127.0.0.1:8765/mail:

  1. Click "Human Overseer" mode
  2. Compose with importance: urgent
  3. Select target agents

Agents see urgent messages via fetch_inbox(..., urgent_only=true).


Pre-Commit Guard

install_precommit_guard(project_key="/abs/path", code_repo_path="/abs/path")
  • Set AGENT_NAME env var so guard knows who you are
  • Bypass emergency: AGENT_MAIL_BYPASS=1 git commit -m "fix"
  • Warning mode: AGENT_MAIL_GUARD_MODE=warn

Search Syntax (FTS5)

"exact phrase"
prefix*
term1 AND term2
term1 OR term2
(auth OR login) AND NOT admin

References

Topic Reference
All MCP tools TOOLS.md
Workflow patterns WORKFLOWS.md
MCP resources RESOURCES.md
Cross-project setup CROSS-PROJECT.md
Doctor & recovery RECOVERY.md
Installation INSTALL.md
Fix MCP config FIX-MCP-CONFIG.md
Product bus, build slots, internals ADVANCED.md

Validation

# Server health
curl http://127.0.0.1:8765/health
# → {"status": "healthy"}

# Start server if needed
am