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

# 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. 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:

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:

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

{
  "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 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 — 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 — 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.