c231f8c18c
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.
60 lines
2.5 KiB
Markdown
60 lines
2.5 KiB
Markdown
# 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:
|
|
|
|
1. 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
|
|
2. checks the daemon status — runs `install-autostart` and/or `start` until it reports `Running`
|
|
3. ensures `CLAUDE_MAILBOX_NAME` is set in `.claude/settings.json` env — prompts for a name if not, writes it idempotently
|
|
4. 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)
|
|
|
|
```sh
|
|
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
|
|
```
|