feat(naming)!: auto-derive mailbox name from project + runtime rename

Mailbox names are now built as <project>-<session-short>, where <project>
is the sanitized git-repo basename (or cwd basename) — no more env-var
prefix step. Sessions can re-tag themselves at runtime via the new
mcp__mailbox__rename tool (POST /v1/rename), which transfers all
pending messages to the new name in a single transaction. Peers using
the old name re-discover via list_mailboxes.

BREAKING: \$CLAUDE_MAILBOX_NAME is no longer read. Existing setups that
relied on the env-var prefix should remove it from .claude/settings.json;
the prefix now comes from the working directory automatically.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

plugin/README.md

@@ -15,21 +15,23 @@ The doctor walks the rest:
 1. installs the `claude-mailbox` binary via `npm install -g @kuns/claude-mailbox` if missing (asks first)
 2. registers the daemon for autostart and starts it if needed
 3. health-probes `http://127.0.0.1:37849/health`
-4. optionally lets you set a **base prefix** (e.g., `backend`) — without one, mailbox names are anonymous (`claude-XXXXXXXX`)
-5. runs a self → self smoke test
+4. runs a self → self smoke test
 
-Restart Claude Code only if step 4 wrote a new prefix. After that, every prompt auto-pulls unread messages.
+After that, every prompt auto-pulls unread messages.
 
 ## Mailbox identity (the important bit)
 
-Each Claude Code session gets its own mailbox name, derived from the session's UUID:
+Each Claude Code session gets its own mailbox name, automatically derived as `<project>-<session-short>`:
 
-| Configuration | Resulting mailbox name |
+| Where the session runs | Resulting mailbox name |
 |---|---|
-| No `CLAUDE_MAILBOX_NAME` set | `claude-a8b3c1d2` (first 8 hex chars of session_id) |
-| `CLAUDE_MAILBOX_NAME=backend` in `.claude/settings.json` env | `backend-a8b3c1d2` |
+| Inside a git repo | `<repo-basename>-a8b3c1d2` (e.g. `claude-mailbox-a8b3c1d2`) |
+| Outside a git repo | `<cwd-basename>-a8b3c1d2` |
+| No cwd in stdin (rare) | `claude-a8b3c1d2` |
 
-So if you open two Claude Code sessions in the same project, they'll be e.g. `backend-a8b3c1d2` and `backend-d4e5f6a7` — distinct, addressable, no manual setup.
+So if you open two Claude Code sessions in the same project, they'll share the project prefix but differ in the session-short — e.g. `claude-mailbox-a8b3c1d2` and `claude-mailbox-d4e5f6a7`. No env-var, no manual prefix step.
+
+If a session focuses on a sub-area (frontend, backend, …), Claude can call `mcp__mailbox__rename(current_name="…", new_name="claude-mailbox-frontend-a8b3c1d2")` to tag itself; pending messages are transferred. Peers using the old name re-discover via `list_mailboxes`.
 
 The `SessionStart` hook announces the current session's mailbox name in the conversation context on startup. Peers discover each other via `claude-mailbox list` or the `mcp__mailbox__list_mailboxes` MCP tool.
 
@@ -55,6 +57,7 @@ Each MCP tool takes the caller's mailbox name as an explicit argument (from the
 | `mcp__mailbox__check_inbox` | `name` | Pull all undelivered messages for your mailbox (marks delivered). |
 | `mcp__mailbox__peek_inbox` | `name` | Non-consuming count of pending messages. |
 | `mcp__mailbox__list_mailboxes` | `name` | Discover known mailboxes and `pendingForYou` counts. |
+| `mcp__mailbox__rename` | `current_name`, `new_name` | Rename your own mailbox (e.g. add an area tag). Pending messages are transferred. Use the new name afterward. |
 
 The SessionStart announcement spells out the exact args to pass, so Claude picks them up automatically.
 

plugin/commands/mailbox-doctor.md

@@ -81,18 +81,13 @@ If `install-autostart` still fails after both attempts (very rare — would mean
 
 Hit `http://127.0.0.1:<port>/health` (use the configured port, not necessarily 37849). Expect a JSON body with `"status":"ok"` AND a `version` matching `claude-mailbox --version`. If unreachable or version mismatch, stop and report.
 
-## Step 6 — mailbox identity (base prefix)
+## Step 6 — mailbox identity
 
-**No prompt by default.** Each Claude Code session gets a unique mailbox name auto-derived from its `session_id` (e.g., `claude-a8b3c1d2`).
+**No prompt.** Each Claude Code session gets a unique mailbox name auto-derived as `<project>-<short_session_id>`, where `<project>` is the git-repo basename of the session's `cwd` (or the cwd basename if not a git repo). Example: `claude-mailbox-a8b3c1d2`.
 
-Read `.claude/settings.json` and look for `env.CLAUDE_MAILBOX_NAME`.
+✓ "Mailbox name will be auto-derived as `<project>-<short_session_id>`."
 
-- 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`.
+Sessions can also rename themselves at runtime via the `mcp__mailbox__rename` MCP tool — e.g. to add an area tag like `claude-mailbox-frontend-a8b3c1d2`. No config involved.
 
 ## Step 7 — smoke test
 

plugin/commands/mailbox-status.md

@@ -12,12 +12,12 @@ Claude-Mailbox status
   binary:       <output of `claude-mailbox --version`, or "not installed">
   daemon:       <output of `claude-mailbox status`>
   health:       <"ok" if GET http://127.0.0.1:37849/health returns 200, else "unreachable">
-  mailbox name: <value of env.CLAUDE_MAILBOX_NAME in ./.claude/settings.json, or "unset"; also note if ~/.claude/settings.json has a value>
-  pending:      <integer count from `claude-mailbox peek --name <resolved-name>` if name is set, else "n/a">
+  mailbox name: auto-derived per session as <project>-<short-session-id> (see SessionStart announcement)
+  pending:      n/a (the session's mailbox name isn't known until SessionStart runs in this session's context)
 ```
 
 End with one line:
 
 - All good → `Status: OK`
-- Missing daemon or unset name → `Status: Setup incomplete. Run /claude-mailbox:mailbox-doctor to fix.`
+- Missing daemon → `Status: Setup incomplete. Run /claude-mailbox:mailbox-doctor to fix.`
 - Daemon installed but stopped → `Status: Daemon is not running. Try \`claude-mailbox start\` or run /claude-mailbox:mailbox-doctor.`