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

19
README.md
View File

@@ -104,15 +104,26 @@ claude-mailbox uninstall-service [--purge]
## How identity works
Every Claude Code session gets a unique mailbox name derived from its UUID:
Every Claude Code session gets a unique mailbox name automatically derived as `<project>-<8-hex-of-session-id>`:
| Setup | Resulting mailbox name |
|---|---|
| Default | `claude-<8-hex-of-session-id>` |
| `CLAUDE_MAILBOX_NAME=backend` (in `.claude/settings.json` env) | `backend-<8-hex>` |
| Inside a git repo | `<repo-basename>-<8-hex>` (e.g. `claude-mailbox-a3f91b2c`) |
| Outside a git repo | `<cwd-basename>-<8-hex>` |
| No cwd available (rare) | `claude-<8-hex>` |
| Manual `.mcp.json` with `X-Mailbox: backend` header (no plugin) | `backend` (legacy mode) |
The plugin's `SessionStart` hook prints the session's identity and the list of peers active in the last hour into the conversation context, so Claude knows who it is and who's around without needing to call any tools first.
Project names are sanitized (lowercased, non-alphanumerics → dashes, capped at 40 chars). The plugin's `SessionStart` hook prints the session's identity and the list of peers active in the last hour into the conversation context, so Claude knows who it is and who's around without needing to call any tools first.
### Renaming at runtime
Claude can refine its own mailbox name during the session — useful when a session focuses on a specific area (e.g. only frontend work):
```
mcp__mailbox__rename(current_name="claude-mailbox-a3f91b2c", new_name="claude-mailbox-frontend-a3f91b2c")
```
Pending messages are transferred to the new name in a single transaction. The old name is removed — peers using it must re-discover via `list_mailboxes`. The endpoint returns `409` if the target name is already in use.
---