claude-mailbox

An MCP server that lets concurrently-running Claude Code sessions cross-talk. Each session registers its project / worktree / branch / objective; sessions can see each other, broadcast over channels, DM, and coordinate under a single leader (the session on main). All state is backed by the shared beads (bd) database beads_global, so it works across projects and — via the existing Dolt remote — the fleet.

Why beads

bd already gives us a persistent, Dolt-synced, event-logged store with the exact primitives a mailbox needs: labels (channels/identity), set-state (status/role/ heartbeat), assignees (DMs/delegations), ephemeral beads (transient messages), gates (request/response), and a shared machine-wide DB (--global). The server is a thin, typed wrapper around the bd CLI — no schema of our own.

Related MCP server: claude-connect-nats-mcp

Layout

src/claude_mailbox/
  bd.py        # `bd --global -C <workspace>` wrapper (+ --json)
  identity.py  # session id + git project/branch/worktree detection
  model.py     # label/state naming conventions + heartbeat math
  leader.py    # main-branch leader election over a singleton slot bead
  server.py    # FastMCP server: tools + background heartbeat + atexit deregister
  cli.py       # `mailbox` shim (who / leader / say / inbox)
skills/        # `mailbox` + `mailbox-leader` Claude skills
docs/DESIGN.md # full design (data model, protocol, risks)

The server needs a bd workspace (a directory with a .beads/) to resolve the shared-server connection, and passes it as bd -C <workspace> on every call so the mailbox is reachable from any cwd. bd.py picks one automatically:

MAILBOX_WORKSPACE overrides both.

Install

Every route needs bd (beads) on PATH and the machine-wide database created once:

bd init --global               # creates/initializes beads_global on the shared dolt server

Nix

nix run github:zach-source/claude-mailbox              # run the MCP server (stdio)
nix run github:zach-source/claude-mailbox#mailbox -- who
nix profile install github:zach-source/claude-mailbox  # or install it

The wrapper appends its own beads and git to PATH as a suffix, so a bd you already have keeps winning — mailbox state lives in a shared database that carries schema migrations, and forcing a different bd version at it risks schema skew. Build with preferSystemBd = false to pin the packaged one.

A devShell (nix develop) provides uv, python3, beads, and git.

Homebrew

brew tap zach-source/claude-mailbox https://github.com/zach-source/claude-mailbox
brew install zach-source/claude-mailbox/claude-mailbox

Pulls in beads as a dependency. It's a tap formula, not homebrew-core: it resolves its ~69 Python dependencies from PyPI at install time rather than vendoring each as a pinned resource (see the note atop Formula/claude-mailbox.rb).

From a checkout

uv run claude-mailbox          # start the MCP server (stdio)
uv run mailbox who             # list live sessions (CLI, no agent)

Initialize the workspace (installed builds only)

A checkout already has one. An installed build needs it once:

mkdir -p ~/.local/share/claude-mailbox
bd init -C ~/.local/share/claude-mailbox

mailbox who tells you this, with the exact commands, if you skip it.

Wire into Claude Code / codex

Add to ~/.claude/mcp_servers.json (and it mirrors to codex):

"mailbox": { "command": "claude-mailbox" }

Installed via nix or brew, the bare command is enough. From a checkout, point uv at it instead:

"mailbox": { "command": "uv", "args": ["run", "--project",
  "/path/to/claude-mailbox", "claude-mailbox"] }

HTTP mode (standalone service, local database)

By default the server runs over stdio, one process per Claude Code session, sharing the machine-wide beads_global database — this is unchanged. Set MAILBOX_TRANSPORT=http to instead run it as a standalone network service, for example hosting one authoritative instance in a remote pod that a Claude Code session on a different machine reaches as an http-type MCP server entry, or that a plain Python daemon (not a Claude session) calls directly as an MCP client. This mode is meant to be paired with MAILBOX_GLOBAL=0 so the pod gets its own dedicated local database instead of the shared machine-wide one.

Environment variables:

Run it as a standalone HTTP service backed by its own local database:

cd /path/to/claude-mailbox     # WORKSPACE — where the local .beads/ will live
bd init --non-interactive      # one-time: creates the local embedded db
export MAILBOX_TOKEN=$(openssl rand -hex 32)   # save this — the MCP client needs it too
MAILBOX_TRANSPORT=http MAILBOX_HTTP_HOST=0.0.0.0 MAILBOX_HTTP_PORT=8000 \
  MAILBOX_GLOBAL=0 uv run claude-mailbox

A non-loopback MAILBOX_HTTP_HOST (like 0.0.0.0 above) refuses to start without MAILBOX_TOKEN/MAILBOX_TOKEN_FILE set — any local (or LAN) process can otherwise reach the mailbox. Configure the same token as an Authorization: Bearer <token> header in the MCP client pointed at this server. Then add it to a Claude Code session on another machine as an http-type MCP server entry pointing at http://<pod-host>:8000/mcp, or point any MCP-capable HTTP client (including a non-Claude Python daemon) at the same URL.

Note: on a machine that already sets BEADS_DOLT_SHARED_SERVER=1 globally (a machine-wide bd default, independent of this server), MAILBOX_GLOBAL=0 still resolves through that shared server unless the pod environment leaves BEADS_DOLT_SHARED_SERVER unset — the pod deployment should simply not set it.

Per-connection session isolation: one HTTP-mode process can serve many concurrent connections, and each gets its own sid/git-context/bead_id/ objective, keyed off FastMCP's Context.session_id (the mcp-session-id header) — they never collide, and proactive <channel> push (see below) delivers to every connection, not just the first one to register. Residual limitation: cleanup of a connection that disconnects without calling deregister is time-based (idle for 15 minutes with no tool call), not a true liveness check against the underlying transport — a connection that stays open but genuinely idle that long gets treated as abandoned. See server.py's _hb_tick_once docstring for the tradeoff. Stdio mode (one process per session) is unaffected either way — idle reap only ever applies under MAILBOX_TRANSPORT=http.

Docker

A published image runs the server in HTTP mode with its own local database out of the box (MAILBOX_TRANSPORT=http, MAILBOX_GLOBAL=0 are baked in as defaults — override via -e if you need something else). Images are built by .github/workflows/docker-publish.yml for linux/amd64 and linux/arm64 and published to GHCR:

docker pull ghcr.io/<owner>/claude-mailbox:latest   # latest tagged release
docker pull ghcr.io/<owner>/claude-mailbox:edge     # latest main

/data is MAILBOX_WORKSPACE (and $HOME) inside the container — mount a volume there for the local database to survive restarts, and initialize it once before the first start (bd needs git init to succeed, which needs an already-writable, already-owned directory — the named volume gets that from the image's useradd --create-home on first use):

docker volume create mailbox-data
docker run --rm -v mailbox-data:/data --user mailbox \
  --entrypoint bd ghcr.io/<owner>/claude-mailbox:latest init --non-interactive

export MAILBOX_TOKEN=$(openssl rand -hex 32)   # save this — the MCP client needs it too
docker run -d --name claude-mailbox -p 8000:8000 \
  -e MAILBOX_TOKEN \
  -v mailbox-data:/data ghcr.io/<owner>/claude-mailbox:latest

The container binds 0.0.0.0 internally (so Docker's own port mapping can reach it) — a non-loopback bind refuses to start without MAILBOX_TOKEN, so it's required here, not optional. Save the token you pass; the MCP client needs the same value as an Authorization: Bearer <token> header.

Then wire it into a Claude Code session elsewhere as an http-type MCP server entry pointing at http://<host>:8000/mcp (see "HTTP mode" above for the non-Docker equivalent and the per-connection isolation notes, which apply here too).

Build notes (low-CVE build): multi-stage — build tooling never reaches the final image, which installs only git + ca-certificates on top of the official python:3.11-slim base (distroless was evaluated and rejected: bd hard-shells out to git, which needs a shell environment distroless doesn't provide) and runs as a non-root user. The bd binary is fetched as a pinned, checksum-verified release tarball rather than trusted implicitly. CI scans every build with Trivy and uploads results to the repo's Security tab (report-only — see the Dockerfile header for the residual CVE clusters this repo can't fully resolve on its own, and why) and rebuilds weekly so upstream Debian/Python security patches land automatically. Build it yourself with:

docker build -t claude-mailbox .

Push delivery via Claude Code channels

The server is also a Claude Code channel: it declares the claude/channel capability and pushes peer messages into the session as <channel source="mailbox" kind="dm|request|delegation|broadcast" from_sid="…">…</channel> events — so a peer's DM or info-request interrupts the session instead of waiting for a poll_inbox call. A background thread (CHANNEL_POLL_SECONDS, default 4s) watches beads_global for new inbound addressed to this session (and broadcasts on subscribed channels: general, <project>, leader) and emits the notification. The existing send_dm / respond_info / broadcast tools are the reply side.

broadcast posts to the sender's own <project> channel unless you name one, so a message only interrupts sessions working in the same repo. Reaching every project on the machine is the explicit channel="general" (or mailbox say -c general).

To actually receive channel pushes, start Claude Code with the research-preview dev flag so it loads the mailbox as a channel (custom channels aren't allowlisted yet):

claude --dangerously-load-development-channels server:mailbox

Without the flag the mailbox still works fully as a normal MCP server (pull-based: poll_inbox, read_channel); you just don't get proactive <channel> interrupts. Channels are also gated by the org channelsEnabled policy on Team/Enterprise.

Status: beyond-MVP — presence, channels, DMs, leadership+failover, delegation, blocking request_info, and channel push delivery. All committed, unit- + live-tested.