ClaudeMailbox/plugin/commands/mailbox-doctor.md

description, allowed-tools

description	allowed-tools
Diagnose and auto-fix the Claude-Mailbox setup (binary install, daemon autostart, mailbox name, smoke test).	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."