Files

Mika Kuns c231f8c18c feat(plugin): add /claude-mailbox:mailbox-doctor for one-command setup

The doctor command runs entirely inside Claude Code and walks through:
binary install via npm, daemon autostart, mailbox-name prompt with write
to per-project `.claude/settings.json` env, and a self → self smoke test.
Also adds `/claude-mailbox:mailbox-status` as a read-only health check.

Reduces the colleague onboarding to: add marketplace, install plugin,
run the doctor — no terminal context-switch required.

2026-05-19 10:55:05 +02:00

2.5 KiB

Raw Blame History

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.

Setup (two steps, all inside Claude Code)

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

The doctor command walks the rest:

checks whether the claude-mailbox binary is on PATH — installs it (npm install -g @kuns/claude-mailbox) if missing, asks before doing anything that might need elevation
checks the daemon status — runs install-autostart and/or start until it reports Running
ensures CLAUDE_MAILBOX_NAME is set in .claude/settings.json env — prompts for a name if not, writes it idempotently
runs a self → self smoke test to verify the round-trip works

Restart Claude Code after the doctor finishes (only needed if the mailbox name was newly written). Unread messages will then appear in context before every prompt.

Why a mailbox name?

Each Claude session has an identity used to address peer sessions — like an email address. If you run a backend session and a frontend session in parallel, they need different names so they can send messages to each other.

For a single Claude Code instance just wanting notifications, any stable kebab-case name works. The name lives in per-project .claude/settings.json env, so different worktrees / projects automatically get different mailboxes.

What the hook actually does

Before every prompt the plugin runs claude-mailbox check --hook, which:

prints unread mailbox messages in a Claude-friendly format and marks them delivered,
stays silent when the inbox is empty or CLAUDE_MAILBOX_NAME is not set,
emits a one-line setup hint when the daemon is unreachable, so a missing daemon is loud, not invisible.

Cost: one local HTTP round-trip plus Node coldstart per prompt (~100ms on Windows).

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.

Smoke test (manually, after doctor finishes)

claude-mailbox send --from probe --to <your-mailbox-name> --body "hello"

Then start a new Claude Code prompt — the message should appear in context before Claude's first reply.

Uninstall

/plugin uninstall claude-mailbox@claude-mailbox
npm uninstall -g @kuns/claude-mailbox
claude-mailbox uninstall-autostart    # if you used it

2.5 KiB Raw Blame History