462d6561e1
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
93 lines
4.0 KiB
Markdown
93 lines
4.0 KiB
Markdown
---
|
|
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>."
|