---
description: Diagnose and auto-fix the Claude-Mailbox setup (binary install, daemon autostart, smoke test, optional base-prefix).
allowed-tools: Bash, Read, Edit, Write
---

You are running the **Claude-Mailbox doctor**. Walk through these checks in order. After each step, print a one-line `✓` / `✗` with the action you took. End with a summary block.

Use `Bash` only for `claude-mailbox` subcommands, `npm`, `where`/`which`, and HTTP probes. Use `Read`/`Edit`/`Write` for `.claude/settings.json`. Never run `sudo` automatically — if elevation is needed, stop and ask.

## Step 1 — daemon binary on PATH

Run: `claude-mailbox --version`

- **Exit 0** → ✓ record the version. Continue.
- **Command not found** → binary missing. Install path:

  | Platform | Command |
  |---|---|
  | Windows | `npm install -g @kuns/claude-mailbox` (no admin) |
  | macOS / Linux | `npm install -g @kuns/claude-mailbox` (may fail with EACCES — never run sudo automatically; ask the user) |

  Prerequisite: `npm config get @kuns:registry` must point at `https://git.kuns.dev/api/packages/releases/npm/`. If not:

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

## Step 2 — daemon autostart and running state

Run: `claude-mailbox status`

- `Running` → ✓ continue.
- `Stopped` → `claude-mailbox start`, re-check.
- `NotInstalled` → `claude-mailbox install-autostart`, then `claude-mailbox start`, re-check.

If status doesn't reach `Running`, stop and report.

## Step 3 — health probe

Hit `http://127.0.0.1:47822/health`. Expect a JSON body with `"status":"ok"`. If unreachable, stop and report — the daemon claims it's running but isn't accepting connections.

## Step 4 — mailbox identity

**No prompt by default.** Each Claude Code session now gets a unique mailbox name auto-derived from its `session_id` (e.g., `claude-a8b3c1d2`), so two parallel sessions can never collide.

Read `.claude/settings.json` in the current working directory and look for `env.CLAUDE_MAILBOX_NAME`.

- If set → ✓ this is a **base prefix**. The real name will be `<base>-<short_session_id>`. Tell the user "Mailbox prefix is set to `X`."
- If unset → ✓ tell the user "Mailbox name will be auto-derived (`claude-<short_session_id>`)."

Then **ask** the user (one question, not a deep prompt):

> "Want to flavor your mailbox names with a memorable prefix like `backend` or `frontend`? (yes / no / change to `<x>`)"

If they say yes or give a value:
1. Read `.claude/settings.json` (empty `{}` if missing).
2. Merge `env.CLAUDE_MAILBOX_NAME` = chosen value, preserving anything else.
3. Write back with 2-space indentation.
4. Mark this as `restart_needed = true`.

If they say no or skip → leave as-is.

## Step 5 — smoke test

Use two ephemeral names (`doctor-probe-a` / `doctor-probe-b`) — we don't need the real session name here, we just need to prove the daemon round-trips:

```
claude-mailbox send  --from doctor-probe-a --to doctor-probe-b --body "ping from doctor"
claude-mailbox check --name doctor-probe-b
```

The `check` output must be a JSON array with one message: `from: doctor-probe-a`, body matches. If yes ✓. If no ✗ and report what came back.

## Step 6 — summary

```
Claude-Mailbox doctor
  binary:        <version>
  daemon:        Running    (and what you did, if anything)
  health:        ok
  base prefix:   <name from settings, or "auto-derived (anonymous)">
  smoke test:    passed | failed
  restart hint:  yes if restart_needed, otherwise no
```

End with one of:

- All ✓ and no restart needed → "Setup is healthy. Your mailbox name this session will be revealed by the SessionStart hook on next session start (or run `claude-mailbox list` to see active mailboxes)."
- All ✓ and restart needed → "Restart Claude Code (or open a new session) so the SessionStart hook picks up the new base prefix."
- Anything ✗ → "Setup incomplete: <first failure>."