<!-- 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