ClaudeMailbox/plugin/commands/mailbox-doctor.md at 462d6561e12aa803c5dfbc37af8a1bef31fe14e5

Files

Mika Kuns 462d6561e1 feat(plugin): per-session mailbox identity + mailbox-update command

The hook now derives a unique mailbox name from the session_id supplied
on hook stdin, so two parallel Claude Code sessions in the same project
get distinct mailboxes (e.g. `claude-a8b3c1d2`, `claude-d4e5f6a7`)
instead of colliding on a shared env value. An optional
CLAUDE_MAILBOX_NAME base prefix flavors the names as `<base>-<sid>`.

Adds:
- `claude-mailbox session-announce` subcommand for the new SessionStart
  hook, which prints the current session's mailbox name to context
- `/claude-mailbox:mailbox-update` slash command for `npm update` +
  daemon restart
- stdin parsing helpers (parseHookStdin, deriveSessionName) with unit
  tests; the doctor no longer needs a mandatory name prompt

2026-05-19 11:39:14 +02:00

4.0 KiB

Raw Blame History

description, allowed-tools

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

Read .claude/settings.json (empty {} if missing).
Merge env.CLAUDE_MAILBOX_NAME = chosen value, preserving anything else.
Write back with 2-space indentation.
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: ."

4.0 KiB Raw Blame History