claude-mailbox
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| MAILBOX_TOKEN | No | Shared bearer token for HTTP mode; required when MAILBOX_HTTP_HOST is non-loopback | |
| MAILBOX_GLOBAL | No | Whether to use global beads database ('1'/'true') or local ('0'/'false') | 1 |
| MAILBOX_HTTP_HOST | No | Bind host when MAILBOX_TRANSPORT=http | 127.0.0.1 |
| MAILBOX_HTTP_PORT | No | Bind port when MAILBOX_TRANSPORT=http | 8000 |
| MAILBOX_TRANSPORT | No | Transport mode: 'stdio' or 'http' | stdio |
| MAILBOX_WORKSPACE | No | Override the bd workspace directory; defaults to the repo parent directory | |
| MAILBOX_TOKEN_FILE | No | Path to file containing token, alternative to MAILBOX_TOKEN |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
This server publishes no instructions, or was last inspected before Glama recorded them.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": true
} |
| logging | {} |
| prompts | {
"listChanged": false
} |
| resources | {
"subscribe": false,
"listChanged": false
} |
| extensions | {
"io.modelcontextprotocol/ui": {}
} |
| experimental | {
"claude/channel": {}
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| register_sessionA | Register this Claude session in the mailbox and start heartbeating. project/branch/worktree are auto-detected from git. Auto-claims leadership if on the main branch. Idempotent for the connection's lifetime (one process per session under stdio; one entry per connection under HTTP). Also captures the live session so peer messages can be pushed as claude/channel events. |
| heartbeatA | Manually pump a heartbeat and return role + inbox (the background thread heartbeats automatically; call it to force a fresh read). |
| update_objectiveC | Update this session's advertised objective. |
| set_statusA | Set this session's status: active | idle | blocked | done. |
| list_sessionsB | List other live Claude sessions: who is working, on what, where. |
| get_leaderA | Who is the current leader/orchestrator (the session on main)? |
| claim_leadershipA | Attempt to become leader. Only succeeds on the main branch unless force. force is restricted to stdio (global-tvr) — an HTTP caller force-claiming leadership would gain delegate() over every session. |
| release_leadershipB | Voluntarily give up leadership. |
| broadcastA | Broadcast a message to a channel. Defaults to this session's own project channel, so only sessions in the same repo are interrupted. Pass channel="general" to reach every project on the machine — do that only when the other projects genuinely need to know. |
| read_channelB | Read recent messages on a channel (newest first). |
| send_dmC | Send a direct message to a specific session. |
| poll_inboxA | Read messages/delegations addressed to this session. Closes DMs when mark_read is true (a closed DM = read). |
| request_infoA | Ask another session a question and block (up to timeout_s) for its answer. Creates a request bead (not ephemeral — an unanswered question must not evaporate) assigned to the target (surfaces in their poll_inbox); they reply via respond_info, which comments the answer and closes the bead. Returns {request_id, answer, resolved, timed_out}. If it times out, keep the request_id and poll later with check_request — the request stays open. |
| respond_infoA | Answer an info-request (from poll_inbox 'requests'): comment + close, which unblocks the asking session. Only the session the request is assigned to may answer it (global-5yn) — otherwise any connection could forge an answer to another agent's blocking request_info call. |
| check_requestA | Non-blocking: has an info-request been answered yet? Only the session that created the request may poll it — otherwise any connection could read another agent's answer by guessing/enumerating request_ids. |
| delegateB | Leader-only: assign a work item to a secondary session. |
| deregisterA | Cleanly leave the mailbox: release leadership, mark done, close bead. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 17 tools
Each tool targets a distinct resource/action: read_channel vs poll_inbox split channel reads from session-inbox reads, send_dm vs broadcast split direct vs channel messaging, and the request_info/respond_info/check_request trio has clear lifecycle roles. There is minimal overlap or ambiguity even among the message-oriented tools.
Most tools follow a clear verb_noun pattern such as read_channel, send_dm, update_objective, claim_leadership, and release_leadership. A few bare verbs like delegate, deregister, and broadcast deviate slightly from the pattern, but the overall naming style is predictable.
17 tools is slightly above the typical sweet spot, but each tool addresses a distinct coordination need such as registration, heartbeat, messaging, info-request handshakes, delegation, leadership, and status. The count feels purposeful rather than padded.
The set covers registration, messaging, polling, request/response, delegation, leadership, status, and clean deregistration, forming a robust coordination lifecycle. The main gap is that delegated work items lack an explicit completion/report-back tool, though set_status and respond_info can partially compensate.