Agent Mail

---
name: agent-mail
description: >-
  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, pre-commit guards.
---

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

```bash
# 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](references/TOOLS.md) |
| Workflow patterns | [WORKFLOWS.md](references/WORKFLOWS.md) |
| MCP resources | [RESOURCES.md](references/RESOURCES.md) |
| Cross-project setup | [CROSS-PROJECT.md](references/CROSS-PROJECT.md) |
| Doctor & recovery | [RECOVERY.md](references/RECOVERY.md) |
| Installation | [INSTALL.md](references/INSTALL.md) |
| Fix MCP config | [FIX-MCP-CONFIG.md](references/FIX-MCP-CONFIG.md) |
| Product bus, build slots, internals | [ADVANCED.md](references/ADVANCED.md) |

---

## Validation

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

# Start server if needed
am
```