releases/ClaudeMailbox
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 17 Wiki Activity

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

Browse Source 
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>
This commit is contained in:
Mika Kuns
2026-05-20 13:14:15 +02:00
parent 8832eab6c7
commit b10ac36ed0
14 changed files with 441 additions and 95 deletions
Download Patch File Download Diff File Expand all files Collapse all files

13
plugin/commands/mailbox-doctor.md
View File

@@ -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

6
plugin/commands/mailbox-status.md
View File

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