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.
86 lines
4.2 KiB
Markdown
86 lines
4.2 KiB
Markdown
---
|
|
description: Diagnose and auto-fix the Claude-Mailbox setup (binary install, daemon autostart, mailbox name, smoke test).
|
|
allowed-tools: Bash, Read, Edit, Write
|
|
---
|
|
|
|
You are running the **Claude-Mailbox doctor**. Walk through these checks in order. After each check, print a one-line status (✓ / ✗) and the action you took. At the very end, print a final summary block.
|
|
|
|
Throughout, prefer the dedicated tools (`Read`, `Edit`, `Write`) for files. Use `Bash` only for `claude-mailbox` subcommands, `npm`, `where`/`which`, and `cat /etc/os-release` style lookups. Never run `sudo` automatically — if elevation is needed, stop and ask the user how to proceed.
|
|
|
|
---
|
|
|
|
## Step 1 — daemon binary on PATH
|
|
|
|
Run: `claude-mailbox --version`
|
|
|
|
- **Exit 0** → binary present. Record the version string. ✓ continue.
|
|
- **Command not found / non-zero exit** → binary missing. Tell the user the install command for their platform and ask before running it:
|
|
|
|
| Platform | Install command |
|
|
|---|---|
|
|
| Windows | `npm install -g @kuns/claude-mailbox` (no admin) |
|
|
| macOS / Linux | `npm install -g @kuns/claude-mailbox` (may need `sudo` depending on Node setup; ask the user if `npm install` fails with EACCES) |
|
|
|
|
Prerequisite: `npm config get @kuns:registry` should return `https://git.kuns.dev/api/packages/releases/npm/`. If it doesn't, set it first:
|
|
|
|
```
|
|
npm config set @kuns:registry=https://git.kuns.dev/api/packages/releases/npm/
|
|
```
|
|
|
|
After install, re-run `claude-mailbox --version`. If it still fails, stop and report the error.
|
|
|
|
## Step 2 — daemon autostart and running state
|
|
|
|
Run: `claude-mailbox status`
|
|
|
|
- **`Running`** → ✓ continue.
|
|
- **`Stopped`** → run `claude-mailbox start`. Re-check status.
|
|
- **`NotInstalled`** → run `claude-mailbox install-autostart`, then `claude-mailbox start`. Re-check status.
|
|
|
|
If status doesn't become `Running` after the fix, stop and report what `status` and `start` printed.
|
|
|
|
Sanity check: `curl -sf http://127.0.0.1:47822/health` (or use Bash to fetch it). Expect a JSON body with `"status":"ok"`.
|
|
|
|
## Step 3 — mailbox name in project settings
|
|
|
|
The hook reads the mailbox name from `$CLAUDE_MAILBOX_NAME`. Claude Code injects env vars from `.claude/settings.json` into hook commands, so the cleanest place to set it is per-project.
|
|
|
|
1. Read `.claude/settings.json` in the current working directory (it may not exist yet — that's fine).
|
|
2. Check if `env.CLAUDE_MAILBOX_NAME` is set.
|
|
3. If **set**: ✓ continue, record the name.
|
|
4. If **not set**:
|
|
- Ask the user for a mailbox name. Suggest a default based on the cwd basename (e.g., for `C:\Private\Claude-Mailbox` suggest `claude-mailbox`). Names should be short, kebab-case-ish, unique among parallel Claude sessions.
|
|
- Read existing `.claude/settings.json` if present, otherwise start with `{}`.
|
|
- Set/merge `env.CLAUDE_MAILBOX_NAME` to the chosen name. Preserve any other existing settings.
|
|
- Write back with 2-space indentation.
|
|
- Tell the user they need to **restart this Claude Code session** for the env to take effect in the hook — but the smoke test below can still run because we'll pass `--name` explicitly.
|
|
|
|
## Step 4 — smoke test
|
|
|
|
Use the resolved name from step 3 (either pre-existing or just chosen). Run:
|
|
|
|
```
|
|
claude-mailbox send --from doctor-probe --to <name> --body "ping from /claude-mailbox:mailbox-doctor"
|
|
claude-mailbox check --name <name>
|
|
```
|
|
|
|
- The `check` output should be a JSON array containing exactly one message with `"from": "doctor-probe"` and that body.
|
|
- If yes: ✓ smoke test passed.
|
|
- If no (empty array, error, or wrong message): ✗ report what was returned.
|
|
|
|
## Step 5 — final summary
|
|
|
|
Print a compact block with these fields, one per line:
|
|
|
|
```
|
|
Claude-Mailbox doctor
|
|
binary: <version>
|
|
daemon: Running | Stopped | NotInstalled (and what you did)
|
|
health: ok | unreachable
|
|
mailbox name: <name> (source: existing | newly written to .claude/settings.json)
|
|
smoke test: passed | failed
|
|
restart hint: <yes if name was newly written, otherwise no>
|
|
```
|
|
|
|
If everything is ✓ and `restart hint: yes`, end with: "Restart Claude Code (or open a new session) so the UserPromptSubmit hook picks up `CLAUDE_MAILBOX_NAME`." If `restart hint: no`, end with: "You're good to go — unread messages will appear before your next prompt."
|