ClaudeMailbox/plugin/commands/mailbox-doctor.md

---
description: Diagnose and auto-fix the Claude-Mailbox setup (binary install, port-conflict detection, 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` and `mailbox.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 — port-conflict check (before autostart!)

Default port is 47822. Probe whether anything is already on it:

```
curl -sf http://127.0.0.1:47822/health
```

- **Returns a JSON body with `"status":"ok"` and a `version` field that matches `claude-mailbox --version`** → it's already our daemon, ✓ skip to Step 4.
- **Returns 200 with `"status":"ok"` but a different `version`** → it's an older claude-mailbox; treat as running, ✓.
- **Returns non-200, non-JSON, or any other foreign response** → **port conflict**. Some other process owns 47822.
- **Connection refused** → port is free, ✓ continue to Step 3.

If port conflict detected:
1. Tell the user which process holds the port (Windows: `Get-NetTCPConnection -LocalPort 47822 | Select-Object OwningProcess`, then `Get-Process -Id <pid>`; macOS/Linux: `lsof -i :47822`).
2. Pick a free port. Default suggestion: **47900**. Verify it's free: `curl -sf http://127.0.0.1:47900/health` should fail with connection refused.
3. Read `~/.claude-mailbox/mailbox.json` (create empty `{}` if missing) and merge `{"port": <chosen>}`. Write back.
4. Also write the override into `.claude/settings.json` env so the plugin's hooks find the right URL:
   ```json
   "env": { "CLAUDE_MAILBOX_URL": "http://127.0.0.1:<chosen>" }
   ```
   Merge into existing env, preserving other keys.
5. Mark `restart_needed = true`.

## Step 3 — 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 `install-autostart` fails with "Access is denied" on Windows:** Group Policy may block non-admin `schtasks /Create`. Two fallbacks:
1. Tell the user to run `claude-mailbox install-autostart` from an elevated PowerShell themselves (one-time).
2. For this session, run `claude-mailbox serve` as a background process so the rest of the doctor's checks can pass — the daemon won't survive logoff, but that's fine for verification.

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

## Step 4 — health probe

Hit `http://127.0.0.1:<port>/health` (use the configured port, not necessarily 47822). Expect a JSON body with `"status":"ok"` AND a `version` matching `claude-mailbox --version`. If unreachable or version mismatch, stop and report.

## Step 5 — mailbox identity (base prefix)

**No prompt by default.** Each Claude Code session gets a unique mailbox name auto-derived from its `session_id` (e.g., `claude-a8b3c1d2`).

Read `.claude/settings.json` and look for `env.CLAUDE_MAILBOX_NAME`.

- If set → ✓ "Mailbox prefix is `<X>`." (real name will be `<X>-<short_session_id>`).
- If unset → ✓ "Mailbox name will be auto-derived (`claude-<short_session_id>`)."

Ask once: *"Want to flavor your mailbox names with a memorable prefix (e.g., `backend`, `frontend`)? (yes / no / `<name>`)"*

On yes/explicit name: merge `env.CLAUDE_MAILBOX_NAME = <name>` into `.claude/settings.json`, preserving other keys. Mark `restart_needed = true`.

## Step 6 — smoke test

Use two ephemeral names — we don't need the real session name here:

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

(If the port was changed in Step 2, pass `--url http://127.0.0.1:<port>` to both.)

The `check` output must be a JSON array with one message: `from: doctor-probe-a`, body matches. ✓ on success, ✗ otherwise.

## Step 7 — summary

```
Claude-Mailbox doctor
  binary:        <version>
  daemon:        Running    (port: <port>, what you did if anything)
  health:        ok
  port conflict: none | resolved (moved from 47822 to <port>)
  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."
- All ✓ and restart needed → "Restart Claude Code (or open a new session) so the SessionStart hook picks up the new env values."
- Anything ✗ → "Setup incomplete: <first failure>."