---
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."