Agent Mail CLI

A self-describing local inbox for coding agents.

npx -y @juanjofuchs/agent-mail describe

That command is the product wedge: an agent can run it, read the JSON schema, and learn how to send, read, acknowledge, and inspect messages without MCP setup, a daemon, or separate documentation.

Status

This repository is the open-source extraction of a working internal tool. src/agent_mail/cli.py is the Python implementation and source of truth for behavior. Spec 001 is the behavioral specification. Spec 002 covers Python packaging, GitHub Release binaries, and WinGet. Spec 003 covers npm and npx.

Why

Multi-agent coding workflows need coordination. Heavy systems already exist for that: MCP servers, agent frameworks, workspace managers, and network protocols.

Agent Mail CLI is aimed at the simpler moment:

I am already inside Claude Code or Codex. I need this agent to send a handoff to that agent. I want one command that teaches both sides the mailbox.

Installation

npx

The primary experience is one command. The npm package name is scoped because npm rejected the unscoped agent-mail and agent-mail-cli names; the installed command remains agent-mail.

npx -y @juanjofuchs/agent-mail describe

npm

npm install -g @juanjofuchs/agent-mail
agent-mail describe

The npm package also exposes agent-mail-cli as an alias for compatibility:

agent-mail-cli describe

pipx

pipx install agent-mail-cli
agent-mail describe

For one-shot Python execution:

pipx run --spec agent-mail-cli agent-mail describe

From source:

python -m agent_mail describe

WinGet

WinGet support has been submitted and is waiting on Microsoft's package review. After approval:

winget install JuanjoFuchs.agent-mail-cli

Intended Usage

Sender:

npx -y @juanjofuchs/agent-mail send --from second-brain:main --to ccburn:worker --subject "Review spec" --body "Please read the referenced spec and report risks."

Recipient:

npx -y @juanjofuchs/agent-mail read ccburn:worker

Recipient staying reachable without a timed poll loop. watch blocks until mail arrives, so waiting costs nothing — the process sleeps, not the model:

# Blocks up to 90 minutes, or returns an empty result. Use --once to check
# without blocking; the wait is in MINUTES (--timeout-minutes, floor 5).
npx -y @juanjofuchs/agent-mail watch ccburn:worker

# watch reports envelopes and marks nothing read — always follow it with read.
npx -y @juanjofuchs/agent-mail read ccburn:worker

Sender checking whether a recipient is actually listening, rather than guessing from silence:

npx -y @juanjofuchs/agent-mail status --agent ccburn:worker --fields agent,watching,last_seen

Design Goals

• Runtime schema introspection through describe
• JSON output by default
• JSON errors on stderr
• Local durable mailbox state
• No registration
• No daemon
• No MCP server required for v1
• Stable storage outside npm cache (post-packaging)
• One-command install for users without the source script

Repository Structure

.
├── AGENTS.md
├── CHANGELOG.md
├── CLAUDE.md
├── LICENSE
├── PROJECT_UNDERSTANDING.md
├── README.md
├── docs/
│   └── landscape.md
├── npm/
│   ├── bin/
│   │   └── agent-mail.js
│   ├── scripts/
│   │   └── postinstall.js
│   ├── LICENSE
│   ├── README.md
│   └── package.json
├── specs/
│   ├── 001-agent-mail-cli.md
│   ├── 002-packaging.md
│   ├── 003-npm-distribution.md
│   ├── 004-output-integrity.md
│   ├── 005-storage-transparency.md
│   ├── 006-inbox-watch.md
│   ├── 007-wrapper-resolution.md
│   ├── 008-remove-the-wrong-choices.md
│   └── 009-rearm-state.md
└── src/
    └── agent_mail/
        ├── __init__.py
        ├── __main__.py
        └── cli.py

Specs

• specs/001-agent-mail-cli.md — behavioral specification. Status: pending review.
• specs/002-packaging.md — PyPI, GitHub Release binaries, and WinGet packaging.
• specs/003-npm-distribution.md — npm wrapper and npx distribution.
• specs/004-output-integrity.md — UTF-8 output and commit-after-output durability.
• specs/005-storage-transparency.md — describe reports the mailbox it actually resolved.
• specs/006-inbox-watch.md — blocking inbox watch and watcher liveness.
• specs/007-wrapper-resolution.md — npm wrapper binary resolution and diagnosability.
• specs/008-remove-the-wrong-choices.md — messages persist; the watch wait is bounded in minutes.
• specs/009-rearm-state.md — a watch that exits reports that the agent is now unreachable, and what to run.

Naming

• Product: Agent Mail CLI
• Repo: agent-mail-cli
• npm package: @juanjofuchs/agent-mail
• Python distribution: agent-mail-cli
• Python import package: agent_mail
• Command: agent-mail
• Command alias from npm: agent-mail-cli

License

MIT