Agent Mail

Using MCP Agent Mail

Core Insight: Agent Mail is the side channel for leases, notifications, acknowledgements, and handoffs. BR/beads is the durable coordination bus and source of truth for work state, evidence, and decisions.

Coordination Boundary

Use Agent Mail to prevent collisions and notify active agents. Do not use it as the durable task queue, audit log, or final evidence store. If a mail thread and BR disagree, reconcile the bead first and link the mail thread from the bead note if the conversation matters.

One-writer-per-hot-dir rule: reserve the path before editing it. If the reservation conflicts, do not write into that path; coordinate with the holder, narrow scope, or wait for the lease to clear.

When to Use What

THE EXACT PROMPT — Session Bootstrap

Call this at the start of every agent session:

macro_start_session(
  human_key="/abs/path/to/project",
  program="codex-cli",
  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

The Four Macros

Fast Resource Reads (No Tool Call Required)

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. BR remains authoritative; mail carries the lease, notification, and discussion side channel.

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. Record evidence:  br update bd-123 --notes "Validation: tests, commit, CI, or handoff proof"
6. Complete:         br close bd-123, release_file_reservations(...), final message

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

Do not infer durable state from mail silence. A missing reply is not proof that a bead is abandoned, blocked, or complete. Check br show <id> --json, bv --robot-insights, git state, and CI evidence before changing work state.

Quick Troubleshooting

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="codex-cli",
  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

Validation

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

# Start server if needed
am