# crewmail

Interoffice mail for your AI crew — a zero-dependency, file-based message bus and shared inbox for AI coding agents (Claude Code, Codex CLI, Cursor, ...) working on the same machine, with a built-in human escalation queue and an MCP server.

## Why

Running multiple AI coding agents in parallel on one codebase is increasingly common, but coordination between them is usually ad hoc: tmux panes, comments left in code, or nothing at all. Agents overwrite each other's work, ask the same question twice, and block silently when they hit a decision only a human can make. crewmail gives agents a durable, auditable inbox instead: register, send, check mail, ack, and — when you're stuck on something only a human can decide — escalate and move on to other work.

## Quick start

```bash
# In your project root
npx crewmail init

# Register two agents
npx crewmail register --code CLAUDE-01 --name "Claude Code" --runtime claude --role builder
npx crewmail register --code CODEX-01 --name "Codex CLI" --runtime codex --role implementer

# Claude asks Codex to do something
npx crewmail send --from CLAUDE-01 --to CODEX-01 --kind task \
  --subject "Implement rate limiter" --body "Add a token-bucket limiter to src/http/client.ts"

# Codex checks its inbox
npx crewmail inbox --agent CODEX-01

# Codex acknowledges it
npx crewmail ack --agent CODEX-01 --all

# Anyone can see who's around and what's outstanding
npx crewmail status
```

Data lives in `.crewmail/` at your project root (created by `init`): an append-only `mail.jsonl` log, `reads.jsonl` read receipts, and a mutable `agents.json` registry. `.crewmail/*.jsonl` is gitignored by default; run `crewmail init --commit-log` if you want the audit trail checked into git instead.

## The protocol

crewmail comes with a short, paste-into-your-`AGENTS.md` protocol snippet: [docs/protocol.md](docs/protocol.md). It covers session start, declaring work before touching shared files, escalating to a human, and reporting on completion.

## Human escalation

Any message can be addressed to the reserved recipient `HUMAN`. Send one with `--kind decision_request` when an agent is blocked on something only a person can decide:

```bash
crewmail send --from CLAUDE-01 --to HUMAN --kind decision_request \
  --subject "Approve prod deploy?" --body "Migration tested in staging, need go/no-go."
```

A human (or a dashboard/cron job watching the queue) reviews open decisions and acks them once resolved:

```bash
crewmail decisions          # open (un-acked) decision requests
crewmail decisions --all    # include ones already acked
crewmail ack --agent HUMAN --id m-1234567890-ab12
```

## MCP server setup

`crewmail mcp` runs a minimal [Model Context Protocol](https://modelcontextprotocol.io) server over stdio, exposing five tools (`crewmail_inbox`, `crewmail_send`, `crewmail_ack`, `crewmail_status`, `crewmail_escalate`) so an agent can use crewmail natively instead of shelling out.

Add it to your MCP client config (e.g. `.mcp.json`, or Claude Desktop's `claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "crewmail": {
      "command": "npx",
      "args": ["crewmail", "mcp", "--agent", "CLAUDE-01"]
    }
  }
}
```

`--agent` fixes the identity of the calling agent, so `agent`/`from` become optional in tool calls. Omit it to require an explicit `agent`/`from` argument on every call (useful if one server instance is shared by multiple identities).

## Design principles

1. **Zero dependencies.** Node.js built-ins only. `npx crewmail` works without installing anything else.
2. **No network.** Local files only. Nothing leaves the machine.
3. **Append-only JSONL.** The mail log is an audit trail; nothing is ever rewritten or deleted.
4. **Single-file CLI.** `bin/crewmail.mjs` is the whole program — easy to read, easy to vendor into a repo directly.
5. **Agent-agnostic.** Any runtime that can run a shell command (or speak MCP) can participate.
6. **Not an approval system.** crewmail coordinates work between agents; it does not replace your code review or deployment approval workflow.

## Commands

All commands accept `--json` (machine-readable output) and `--dir <path>` (explicit data directory, overriding auto-discovery).

| Command | Purpose |
|---|---|
| `init [--commit-log]` | Create `.crewmail/` in the current directory |
| `register --code X [--name --runtime --model --role]` | Add or update an agent in the registry |
| `send --from X --to A,B --kind K --subject S --body B [--thread --tag --priority]` | Append a message |
| `inbox --agent X [--all]` | Unread (default) or all messages addressed to X, including `ALL` broadcasts |
| `ack --agent X (--id M ... \| --all)` | Write read receipts |
| `log [--limit N --tag T --thread T]` | Recent messages, newest first |
| `decisions [--all]` | Open (un-acked) `decision_request` messages to `HUMAN`; `--all` includes acked ones |
| `heartbeat --agent X --status active\|idle\|blocked\|done [--note]` | Update an agent's liveness status |
| `status` | Table of agents: role, last heartbeat, unread count |
| `watch [--agent X] [--interval <ms>]` | Poll and print new messages as they arrive (default 2000ms) |
| `export` | Dump the full registry and message log as JSON |
| `mcp [--agent X]` | Run the MCP server on stdio |

Message `kind`: `info` \| `question` \| `report` \| `task` \| `decision_request` \| `ack`. Reserved recipients: `ALL` (broadcast to every registered agent), `HUMAN` (the escalation queue). Subjects are capped at 80 characters. Exit codes: `0` success, `1` usage error, `2` data directory not found.

See [docs/DESIGN.md](docs/DESIGN.md) for the full design spec.

## Prior art & how crewmail differs

Agent-to-agent coordination is an active space; crewmail is one take on it, grown out of a private file bus the author has been running daily since 2026-07 to coordinate Claude Code and Codex CLI sessions building the same products. Related projects you should also consider:

- **[agmsg](https://github.com/fujibee/agmsg)** — cross-vendor messaging for CLI coding agents over bash + SQLite, with real-time monitor delivery and tmux-based agent spawning. Great for interactive, session-orchestration workflows. crewmail was developed independently (different storage, language, and command surface) and focuses instead on a durable append-only audit log, typed message kinds, a built-in `HUMAN` decision queue, and an MCP server — coordination as a record, not session orchestration.
- **[AgentMail](https://agentmail.to)** — a hosted email API for AI agents (real email over the network). crewmail is unrelated: local files only, nothing leaves the machine.
- **CrewAI** — an agent framework. crewmail is framework-agnostic and not affiliated; the name refers to your "crew" of coding agents.

## License

MIT — see [LICENSE](LICENSE).