releases/ClaudeMailbox
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 17 Wiki Activity

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

Browse Source 
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.
This commit is contained in:
Mika Kuns
2026-05-19 10:55:05 +02:00
parent 5c5843e62d
commit c231f8c18c
4 changed files with 141 additions and 48 deletions
Download Patch File Download Diff File Expand all files Collapse all files

65
plugin/README.md
View File

@@ -1,68 +1,59 @@
# claude-mailbox plugin
Lets Claude Code automatically pull unread messages from a local `claude-mailbox` daemon before every prompt and inject them into the conversation context.
Lets Claude Code pull unread messages from a local `claude-mailbox` daemon before every prompt and inject them into the conversation context.
## Three-step setup
The Claude Code plugin itself is just the glue — you still need the daemon binary on PATH and a mailbox name.
### 1. Install the daemon (one-time, per machine)
```sh
npm config set @kuns:registry=https://git.kuns.dev/api/packages/releases/npm/
npm install -g @kuns/claude-mailbox
claude-mailbox install-autostart # registers per-OS autostart (no admin needed by default)
```
Verify with:
```sh
claude-mailbox status # expect: Running
```
### 2. Install the plugin
In Claude Code:
## 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
```
### 3. Choose a mailbox name
The doctor command walks the rest:
Set the env var Claude Code will inherit (any unique name — your username, machine name, whatever):
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
```sh
# Windows (PowerShell, persistent)
setx CLAUDE_MAILBOX_NAME alice
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.
# macOS / Linux (add to ~/.zshrc or ~/.bashrc)
export CLAUDE_MAILBOX_NAME=alice
```
## Why a mailbox name?
Restart Claude Code so the new env var is picked up.
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.
## What happens at runtime
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 missing step 1 is loud).
- emits a one-line setup hint when the daemon is unreachable, so a missing daemon is loud, not invisible.
## Sending yourself a message (smoke test)
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 alice --body "hello from the CLI"
claude-mailbox send --from probe --to <your-mailbox-name> --body "hello"
```
Then start a new Claude Code session — the message should appear in context before Claude's first reply.
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
claude-mailbox uninstall-autostart # if you used it
```