3ebf54e75d
Wire a fifth pull hook so peer messages also surface between todo items, not only at user prompts and subagent stops. While here, extend the manual `install-hook` CLI so it patches the full plugin hook set (SessionStart/UserPromptSubmit/SubagentStop/TaskCompleted/ SessionEnd) instead of only UserPromptSubmit, mirroring what the plugin's hooks.json registers. Mailbox name is auto-derived from stdin, so --name is no longer required. Also corrects stale docs that claimed SessionStart auto-bootstraps the watcher — push delivery has been opt-in since the mailbox-collaborate skill landed.
@kuns/claude-mailbox
Standalone MCP mail server that lets parallel Claude sessions coordinate with each other.
Install
One-time per machine:
npm config set @kuns:registry=https://git.kuns.dev/api/packages/releases/npm/
npm install -g @kuns/claude-mailbox
Then:
claude-mailbox install-autostart # registers per-OS autostart, no admin needed by default
See the repository README for the full architecture, MCP tool reference, and .mcp.json snippet.
Claude Code hooks (auto-check inbox)
Register the full plugin-equivalent hook set so Claude pulls pending mailbox messages at every natural sync point:
claude-mailbox install-hook # patches ~/.claude/settings.json
claude-mailbox install-hook --project # patches <cwd>/.claude/settings.json
claude-mailbox uninstall-hook # remove again
This installs five hooks:
| Event | Command | When it fires |
|---|---|---|
SessionStart |
session-announce |
Announces this session's mailbox identity + active peers. |
UserPromptSubmit |
check --hook |
Before each user prompt. |
SubagentStop |
check --hook |
When a subagent finishes. |
TaskCompleted |
check --hook |
When Claude marks a TaskCreate task completed — gives mid-run sync points. |
SessionEnd |
session-end |
Cleans up the auto-derived mailbox if empty. |
The mailbox name is auto-derived from the session-id stdin payload — no --name required. Install is idempotent and only touches our own commands; other hooks and settings are preserved.
check --hook:
- prints unread messages in a Claude-friendly format,
- silently exits 0 if the inbox is empty or the daemon is unreachable (no context noise),
- marks the messages delivered so they aren't injected again next prompt.
Cost: one local HTTP round-trip plus Node coldstart per fire (~100ms on Windows).
Push delivery (watch)
For long-running autonomous sessions, run the watcher as a background bash task so peer messages surface immediately via BashOutput:
claude-mailbox watch --block --name <mailbox>
Exit codes: 0 delivered or renamed, 1 error, 2 daemon unreachable, 3 timeout. See the repository README for the full contract.
Troubleshooting
npm installreturns401 Unauthorized- The Gitea registry usually serves the
releasesscope publicly, but if your instance requires auth you'll need a read token:npm config set //git.kuns.dev/api/packages/releases/npm/:_authToken=<token> Cannot find module 'node:sqlite'or similar- claude-mailbox uses Node's built-in
node:sqlite, stable since Node 24. On Node 22.5–23.x it works only with--experimental-sqlite. Upgrade to Node 24 LTS or newer:nvm install 24 && nvm use 24(orwinget install OpenJS.NodeJS.LTSon Windows).