agent-mail

# MCP Agent Mail

A mail-like coordination layer for coding agents exposed as an HTTP-only FastMCP server. Provides memorable identities, inbox/outbox, file reservation leases, contact policies, searchable message history, and Human Overseer messaging. Backed by Git (human-auditable artifacts) and SQLite (fast queries with FTS5).

## Why This Exists

Without coordination, multiple agents:
- Overwrite each other's edits or panic on unexpected diffs
- Miss critical context from parallel workstreams
- Require humans to relay messages between tools

Agent Mail solves this with:
- Memorable identities (adjective+noun names like "GreenCastle")
- Advisory file reservations to signal editing intent
- Threaded messaging with importance levels and acknowledgments
- Pre-commit guard to enforce reservations at commit time
- Human Overseer for direct human-to-agent communication

## Starting the Server

```bash
# Quickest way (alias added during install)
am

# Or manually
cd ~/projects/mcp_agent_mail
./scripts/run_server_with_token.sh
```

Default: `http://127.0.0.1:8765`
Web UI for humans: `http://127.0.0.1:8765/mail`

## Core Concepts

### Projects
Each working directory (absolute path) is a project. Agents in the same directory share a project namespace. Use the same `project_key` for agents that need to coordinate.

### Agent Identity
Agents register with adjective+noun names (GreenCastle, BlueLake). Names are unique per project, memorable, and appear in inboxes, commit logs, and the web UI.

### File Reservations (Leases)
Advisory locks on file paths or globs. Before editing files, reserve them to signal intent. Other agents see the reservation and can choose different work. The optional pre-commit guard blocks commits that conflict with others' exclusive reservations.

### Contact Policies
Per-agent policies control who can message whom:

| Policy | Behavior |
|--------|----------|
| `open` | Accept any message in the project |
| `auto` (default) | Allow if shared context exists (same thread, overlapping reservations, recent contact) |
| `contacts_only` | Require explicit contact approval first |
| `block_all` | Reject all new contacts |

### Messages
GitHub-Flavored Markdown with threading, importance levels (`low`, `normal`, `high`, `urgent`), and optional acknowledgment requirements. Images are auto-converted to WebP.

## Essential Workflow

### 1. Start Session (One-Call Bootstrap)

```
macro_start_session(
  human_key="/abs/path/to/project",
  program="claude-code",
  model="opus-4.5",
  task_description="Implementing auth module"
)
```

Returns: `{project, agent, file_reservations, inbox}`

This single call: ensures project exists, registers your identity, optionally reserves files, fetches your inbox.

### 2. Reserve Files Before Editing

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

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

Conflicts are reported but reservations are still granted. Check conflicts and coordinate if needed.

### 3. Announce Your Work

```
send_message(
  project_key="/abs/path/to/project",
  sender_name="GreenCastle",
  to=["BlueLake"],
  subject="[bd-123] Starting auth refactor",
  body_md="Reserving src/auth/**. Will update session handling.",
  thread_id="bd-123",
  importance="normal",
  ack_required=true
)
```

### 4. Check Inbox Periodically

```
fetch_inbox(
  project_key="/abs/path/to/project",
  agent_name="GreenCastle",
  limit=20,
  urgent_only=false,
  include_bodies=true
)
```

Or use resources for fast reads:
```
resource://inbox/GreenCastle?project=/abs/path&limit=20&include_bodies=true
```

### 5. Release Reservations When Done

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

## The Four Macros

Prefer macros for speed and smaller models. Use granular tools when you need fine control.

| Macro | Purpose |
|-------|---------|
| `macro_start_session` | Bootstrap: ensure project → register agent → optional file reservations → fetch inbox |
| `macro_prepare_thread` | Join existing conversation: register → summarize thread → fetch inbox context |
| `macro_file_reservation_cycle` | Reserve files, do work, optionally auto-release when done |
| `macro_contact_handshake` | Request contact permission, optionally auto-accept, send welcome message |

## Beads Integration (bd-### Workflow)

When using Beads for task management, keep identifiers aligned:

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

Use `bd-###` as:
- Mail `thread_id`
- Message subject prefix `[bd-###]`
- File reservation `reason`
- Commit message reference

## Beads Viewer (bv) Integration

Use bv's robot flags for intelligent task selection:

| Flag | Output | Use Case |
|------|--------|----------|
| `bv --robot-insights` | PageRank, critical path, cycles | "What's most impactful?" |
| `bv --robot-plan` | Parallel tracks, unblocks | "What can run in parallel?" |
| `bv --robot-priority` | Recommendations with confidence | "What should I work on next?" |
| `bv --robot-diff --diff-since <ref>` | Changes since commit/date | "What changed?" |

**Rule of thumb:** Use `bd` for task operations, use `bv` for task intelligence.

## Cross-Project Coordination

For frontend/backend or multi-repo projects:

**Option A: Shared project_key**
Both repos use the same `project_key`. Agents coordinate automatically.

**Option B: Separate projects with contact links**
```
# Backend agent requests co