ClaudeMailbox/README.md

ClaudeMailbox

A standalone MCP mail server that lets parallel Claude sessions coordinate with each other. Messages are queued in a tiny SQLite database via a local HTTP daemon. Any Claude session — Claude Code, ClaudeDo worktree, plain MCP client — can send to a peer's inbox, check for pending messages, and discover other active mailboxes.

Not a substitute for run_in_background: true (which handles single-session responsiveness). This handles session-to-session coordination.

---

Getting started

Pick one path. Most users want path A.

A. Claude Code plugin (recommended — three prompts)

Inside Claude Code:

/plugin marketplace add https://git.kuns.dev/releases/ClaudeMailbox.git
/plugin install claude-mailbox@claude-mailbox
/claude-mailbox:mailbox-doctor

The doctor command does the rest:

1. installs the daemon binary via npm install -g @kuns/claude-mailbox if missing (asks first)
2. registers the daemon for autostart and starts it
3. optionally lets you pick a base prefix (e.g. backend, frontend); without one, mailbox names are anonymous (claude-a8b3c1d2)
4. runs a self → self smoke test

After that, every Claude Code session automatically:

• gets a unique mailbox identity derived from its session UUID (so two parallel sessions never collide),
• announces that identity and the list of currently active peers at session start,
• pulls unread mailbox messages into context before every prompt.

You can then say things like:

"I started a second session, coordinate with it on the refactor."

Claude already has the peer's mailbox name in context from the SessionStart announcement, so it calls mcp__mailbox__send(from="<my-name>", to="<peer>", body="...") directly.

See plugin/README.md for the full walkthrough, including the mailbox-status and mailbox-update slash commands.

B. Manual install (no Claude Code plugin)

If you're using a different MCP client, scripts, or you don't want the plugin:

# one-time per machine: point the @kuns scope at the public Gitea npm registry
npm config set @kuns:registry=https://git.kuns.dev/api/packages/releases/npm/

# install + autostart
npm install -g @kuns/claude-mailbox
claude-mailbox install-autostart

Or the bootstrap one-liner:

# Windows
irm https://git.kuns.dev/releases/ClaudeMailbox/raw/branch/main/install.ps1 | iex

# macOS / Linux
curl -fsSL https://git.kuns.dev/releases/ClaudeMailbox/raw/branch/main/install.sh | sh

Then drop this into your project's .mcp.json:

{
  "mcpServers": {
    "mailbox": {
      "type": "http",
      "url": "http://127.0.0.1:37849/mcp"
    }
  }
}

Optionally add a static identity (so your client doesn't need to pass from / name on every call):

"headers": { "X-Mailbox": "backend" }

---

How identity works

Every Claude Code session gets a unique mailbox name automatically derived as <project>-<8-hex-of-session-id>:

Setup	Resulting mailbox name
Inside a git repo	<repo-basename>-<8-hex> (e.g. claude-mailbox-a3f91b2c)
Outside a git repo	<cwd-basename>-<8-hex>
No cwd available (rare)	claude-<8-hex>
Manual .mcp.json with X-Mailbox: backend header (no plugin)	backend (legacy mode)

Project names are sanitized (lowercased, non-alphanumerics → dashes, capped at 40 chars). The plugin's SessionStart hook prints the session's identity and the list of peers active in the last hour into the conversation context, so Claude knows who it is and who's around without needing to call any tools first.

Renaming at runtime

Claude can refine its own mailbox name during the session — useful when a session focuses on a specific area (e.g. only frontend work):

mcp__mailbox__rename(current_name="claude-mailbox-a3f91b2c", new_name="claude-mailbox-frontend-a3f91b2c")

Pending messages are transferred to the new name in a single transaction. The old name is removed — peers using it must re-discover via list_mailboxes. The endpoint returns 409 if the target name is already in use.

---

Autostart

claude-mailbox install-autostart            # per-user, no admin
claude-mailbox install-autostart --service  # Windows only: Windows Service (admin)
claude-mailbox status                       # Running | Stopped | NotInstalled
claude-mailbox uninstall-autostart [--purge]

Platform	Default mechanism	--service mechanism
Windows	Scheduled Task at logon (no admin); falls back to HKCU Run-key if Group Policy blocks schtasks	Windows Service (admin, via node-windows)
macOS	launchd LaunchAgent in ~/Library/LaunchAgents/	n/a
Linux	systemd --user unit in ~/.config/systemd/user/	n/a

---

MCP tools

Tool	Required args	Purpose
mcp__mailbox__send	to, body, from	Send a message. from falls back to X-Mailbox header.
mcp__mailbox__check_inbox	name	Pull all pending messages and mark delivered. Falls back to header.
mcp__mailbox__peek_inbox	name	Non-consuming { pending, oldestAt }. Falls back to header.
mcp__mailbox__list_mailboxes	name	Discover known mailboxes + pendingForYou. Falls back to header.

The plugin's SessionStart announcement tells Claude exactly which name to pass for the current session, so the args are filled in automatically.

Suggested CLAUDE.md snippet for poll discipline

When coordinating with a peer session, call mcp__mailbox__peek_inbox
after each subagent completes. If pending > 0, call mcp__mailbox__check_inbox
and treat the messages as input with priority over the current plan.

---

Push delivery (watch)

The watch --block subcommand turns mail delivery from pull (poll between turns) into push (the receiver reacts as soon as a peer sends). It's a long-poll that exits the moment one message arrives.

claude-mailbox watch --block --name <mailbox> [--timeout 25] [--url <daemon>]

Intended use: a Claude Code background bash task. The plugin's SessionStart hook now tells Claude to start one on its first turn, so peers can mcp__mailbox__send to it and Claude reacts mid-session via BashOutput — no user prompt needed. After every exit Claude relaunches the watcher in the background.

Exit code	Meaning
0	One message delivered (or mailbox renamed — stdout disambiguates)
1	Generic error (e.g. missing --name)
2	Daemon unreachable
3	Timeout reached with no message

The CLI consumes exactly one message per cycle (single-delivery, FIFO winner across concurrent watchers on the same mailbox). Backlog drains one message per reconnect (~100 ms turnaround).

Cross-process semantics:

• Concurrent watchers on the same mailbox: the first to register wins each individual message; others continue waiting.
• Rename mid-watch: the open watch exits 0 with a Mailbox renamed to '<new>' notice; relaunch with the new --name.
• Daemon restart: all watchers see exit 2; back off and retry.
• Session end: Claude Code reaps background bash on exit; the fetch aborts and the daemon-side waiter is cleaned up.

When push helps: during active turns where the receiver is busy with tool calls — BashOutput notifications surface between tool calls, so peer messages arrive mid-turn. When push degrades to pull: when the receiver is idle between turns, BashOutput is buffered until the next user prompt, at which point the existing UserPromptSubmit poll hook delivers the same message. The two channels coexist.

---

CLI

Any external process — scripts, UIs, manual debugging — can talk to a running daemon directly:

claude-mailbox send         --from <mailbox> --to <mailbox> --body <text>
claude-mailbox peek         --name <mailbox>
claude-mailbox check        --name <mailbox> [--hook]
claude-mailbox watch        --block --name <mailbox> [--timeout 25]
claude-mailbox list
claude-mailbox status
claude-mailbox session-announce         # hook helper, reads stdin JSON
claude-mailbox install-hook   --name <mailbox> [--user|--project]
claude-mailbox uninstall-hook                  [--user|--project]

All subcommands accept --url <url> to target a non-default daemon address.

---

REST surface

Method	Path	X-Mailbox required	Purpose
GET	/health	no	{ status, version, dbPath }
POST	/v1/send	yes (sender)	body: { to, body }
GET	/v1/peek?name=<mailbox>	no	read-only status
POST	/v1/check-inbox?name=<mailbox>	yes (must match name)	consume inbox
GET	/v1/watch?name=<mailbox>&timeout=<sec>	yes (must match name)	long-poll one message: 200 + body / 204 timeout / 409 { reason: "renamed", to }
GET	/v1/list	optional (presence registers caller)	list all mailboxes

---

Config precedence

CLI flag   >   mailbox.json   >   built-in defaults

mailbox.json is searched at ~/.claude-mailbox/mailbox.json (per-user), and on Windows additionally at %ProgramData%\ClaudeMailbox\mailbox.json (machine-wide, written by --service install). Override with --config <path>.

Defaults: port 37849, bind 127.0.0.1, database at ~/.claude-mailbox/mailbox.db.

---

Architecture

One long-running daemon binds HTTP on loopback, hosts the MCP server at /mcp and a small REST API at /v1/*, and persists state in a single SQLite file.

 session-A                       session-B                  external sender
 mailbox: claude-a8b3c1d2        mailbox: claude-d4e5f6a7   (CLI / UI / script)
        |                                |                          |
        |  HTTP                          |                          |
        +--------------+-----------------+--------------------------+
                       v
          claude-mailbox serve   (Fastify)
            /mcp      MCP tools
            /v1/*     REST for non-MCP senders
            /health
                       v
          ~/.claude-mailbox/mailbox.db   (SQLite WAL)

---

Development

cd node
npm install
npm run build
npm test

The test suite covers end-to-end coordination, concurrent check_inbox race safety, schema idempotency, hook stdin parsing, session-id derivation, and settings-file patching.

---

Scope

• Loopback bind only (v1). Cross-machine coordination is a future extension — swap the middleware for token auth and change the bind address.
• No auth on loopback. Local filesystem permissions are the trust boundary.
• No message expiry. Delivered messages remain as an audit log.