42237149a1
Two production-readiness fixes so colleagues can install cleanly: 1. Plugin's MCP server now spawns `claude-mailbox mcp-stdio`, a small stdio MCP wrapper that proxies tool calls to the daemon's REST API. Claude Code does not support env-var substitution in HTTP MCP `url` fields (issue #46889), so the wrapper is the only way to make the daemon URL configurable per machine via CLAUDE_MAILBOX_URL. 2. Windows `install-autostart` now falls back from `schtasks /Create` to an HKCU\Software\Microsoft\Windows\CurrentVersion\Run entry when Group Policy blocks the Scheduled Task path. Both modes are per-user, no admin, persist across logoffs. The chosen mode is recorded in ~/.claude-mailbox/autostart-mode so status/start/stop/ uninstall-autostart pick the right cleanup path. Also bumps the npm version to 1.0.1 to align with the published 1.0.0 plus this patch.
claude-mailbox plugin
Lets Claude Code pull unread messages from a local claude-mailbox daemon before every prompt and inject them into the conversation context. Each Claude session gets a unique mailbox identity auto-derived from its session id, so two sessions in the same project never collide.
Setup (three prompts, all 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 walks the rest:
- installs the
claude-mailboxbinary vianpm install -g @kuns/claude-mailboxif missing (asks first) - registers the daemon for autostart and starts it if needed
- health-probes
http://127.0.0.1:47822/health - optionally lets you set a base prefix (e.g.,
backend) — without one, mailbox names are anonymous (claude-XXXXXXXX) - runs a self → self smoke test
Restart Claude Code only if step 4 wrote a new prefix. After that, every prompt auto-pulls unread messages.
Mailbox identity (the important bit)
Each Claude Code session gets its own mailbox name, derived from the session's UUID:
| Configuration | Resulting mailbox name |
|---|---|
No CLAUDE_MAILBOX_NAME set |
claude-a8b3c1d2 (first 8 hex chars of session_id) |
CLAUDE_MAILBOX_NAME=backend in .claude/settings.json env |
backend-a8b3c1d2 |
So if you open two Claude Code sessions in the same project, they'll be e.g. backend-a8b3c1d2 and backend-d4e5f6a7 — distinct, addressable, no manual setup.
The SessionStart hook announces the current session's mailbox name in the conversation context on startup. Peers discover each other via claude-mailbox list or the mcp__mailbox__list_mailboxes MCP tool.
What the hooks do
| Hook | Command | Effect |
|---|---|---|
SessionStart |
claude-mailbox session-announce |
Registers the session with the daemon, then prints (a) this session's mailbox name, (b) the exact from / name args to pass to MCP tools, and (c) a list of other mailboxes active in the last hour — so Claude knows who's around without needing to call list_mailboxes first. |
UserPromptSubmit |
claude-mailbox check --hook |
Pulls unread messages for the session's mailbox and injects them as context. Silent on empty inbox; emits a one-line setup hint when the daemon is unreachable. |
Cost: one local HTTP round-trip per prompt + Node coldstart (~100ms on Windows).
MCP tools
The plugin ships a .mcp.json that spawns a stdio MCP wrapper (claude-mailbox mcp-stdio) so the daemon URL is configurable per machine via the CLAUDE_MAILBOX_URL env var (Claude Code doesn't yet support env substitution in HTTP MCP URLs — see issue #46889). The wrapper proxies tool calls to the daemon's REST API.
Each MCP tool takes the caller's mailbox name as an explicit argument (from the SessionStart announcement):
| Tool | Required args | Purpose |
|---|---|---|
mcp__mailbox__send |
from, to, body |
Send a message to another mailbox. |
mcp__mailbox__check_inbox |
name |
Pull all undelivered messages for your mailbox (marks delivered). |
mcp__mailbox__peek_inbox |
name |
Non-consuming count of pending messages. |
mcp__mailbox__list_mailboxes |
name |
Discover known mailboxes and pendingForYou counts. |
The SessionStart announcement spells out the exact args to pass, so Claude picks them up automatically.
Slash commands
| Command | What it does |
|---|---|
/claude-mailbox:mailbox-doctor |
Diagnose + auto-fix the full setup. |
/claude-mailbox:mailbox-status |
Read-only health check. No changes. |
/claude-mailbox:mailbox-update |
Update the daemon to the latest npm version and restart it. |
Coordinating two Claude Code sessions
- Open two Claude Code sessions in the same (or different) project.
- Each session's SessionStart hook registers itself with the daemon and prints both its own mailbox name and the list of currently active peers into context.
- In session A you can simply say: "I started a second session, coordinate with it." Because the peer's mailbox name is already in context, Claude can call
mcp__mailbox__send(from="<my-name>", to="<peer-name>", body="...")straight away — no manuallist_mailboxesstep needed. - Session B's
UserPromptSubmithook pulls the message on its next prompt and injects it as context.
You can also send from any shell:
claude-mailbox list
claude-mailbox send --from probe --to backend-a8b3c1d2 --body "hi"
Uninstall
/plugin uninstall claude-mailbox@claude-mailbox
npm uninstall -g @kuns/claude-mailbox
claude-mailbox uninstall-autostart # if you registered it