Skip to content
Back to search

session-mailbox

MarketplaceWorks with Claude CodeGitHub

分层文件信箱:让多个 Claude Code 会话快速、可靠地互相通信。

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/gordonynh--claude-mailbox/badge.svg)](/listings/gordonynh--claude-mailbox)

HTML

<a href="/listings/gordonynh--claude-mailbox"><img src="/api/listings/gordonynh--claude-mailbox/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Ask Claude to install it

Paste this into Claude Code:

Install claude-mailbox for me: clone https://github.com/Gordonynh/claude-mailbox.git into ~/.local/share/claude-mailbox (git pull if it is already there), run ./install.sh --mcp in that directory, confirm that `cmb version` and `claude mcp get mailbox` both succeed, and tell me to start a new session so the mailbox tools load.

Install by hand

git clone https://github.com/Gordonynh/claude-mailbox.git
cd claude-mailbox
./install.sh          # links bin/cmb into ~/.local/bin and installs the skill into ~/.claude/skills

You can also install it as a Claude Code plugin (`/plugin marketplace add Gordonynh/claude-mailbox`, then `/plugin install session-mailbox@session-mailbox`). The plugin bundles the skill and the MCP server, and puts `cmb` on the Bash tool's PATH.

Register the MCP server for all projects:

./install.sh --mcp     # same as: claude mcp add -s user mailbox -- python3 <repo>/bin/cmb mcp

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 14 lines
  1. {
  2. "name": "session-mailbox",
  3. "owner": {
  4. "name": "Gordonynh"
  5. },
  6. "description": "分层文件信箱:让多个 Claude Code 会话快速、可靠地互相通信。",
  7. "plugins": [
  8. {
  9. "name": "session-mailbox",
  10. "source": "./",
  11. "description": "分层文件信箱:MCP 服务器、skill 与 cmb 命令。"
  12. }
  13. ]
  14. }
README.md · README · 179 lines
  1. # claude-mailbox
  2. [中文](README.zh-CN.md)
  3. A file-based, hierarchical mailbox that lets anywhere from 2 to several dozen Claude Code sessions talk to each other quickly and reliably. It does not rely on Claude Code's cross-session messaging. It ships as an **MCP server**, a **Claude Code skill** and the **`cmb` command line**.
  4. When you run many Claude Code sessions in parallel (one lead, a few group leads, a set of workers), direct cross-session messages are slow and often fail to arrive. claude-mailbox takes a simple approach. Each member has an append-only Markdown inbox, and the `cmb` command appends messages under a lock. Sessions receive mail through channel push, the `wait` tool, or a Monitor running `cmb watch`, so they learn about new mail as soon as it lands. Messages are plain text files that both people and models can inspect directly.
  5. - **Fast.** MCP tools read and write in-process, without spawning anything. `wait` returns within about 0.1 s of a message arriving, and each delivery takes milliseconds, even with dozens of sessions.
  6. - **Hierarchical routing.** You declare members and reporting lines in one config file. By default a member can only write to its direct parent, its direct children and its siblings. Skipping levels requires an explicit `--escalate`.
  7. - **Reliable under concurrency.** A global `flock` plus single-write appends means dozens of concurrent writers neither lose messages nor duplicate IDs. Each ID carries the sender's prefix: `A-12` is alpha's 12th message.
  8. - **No missed mail.** `watch` lists every unread message on startup, so mail that arrived while a Monitor was expired and not yet re-armed is still reported.
  9. - **Bounded size.** When an inbox grows past a configured size, read messages are moved to an archive. Unread messages are never archived. The `unread`, `since` and `inbox` commands read only what they need.
  10. - **Blocking wait on the command line.** `cmb wait` works like the MCP `wait` tool: it returns the full text as soon as mail arrives. Headless processes and subagents need neither a Monitor nor a hand-written polling script.
  11. - **No stolen mail.** Only one reader that marks mail as read (`unread` or `wait`) may run per member at a time; a second one is refused. You can also `--peek` first and `mark-read` once you have handled the mail.
  12. - **Acknowledgement tally.** `cmb acks <id>` lists who replied (with their replies), who read the message without replying, and who has not read it yet. `--wait` blocks until everyone has replied.
  13. - **Cascade.** `--cascade` delivers a notice to every descendant in one step, so intermediate levels do not have to relay it.
  14. - **Coordination.** `claim` and `release` record who holds a shared resource (a deploy, a staging database, a port) and can notify others at the same time. `--wait` queues in arrival order while the resource is held, and `--ttl` releases it automatically.
  15. - **Results on the first line.** Success, refusal and timeout are stated on the first line of output, with the exit code on failure, so a model has no reason to append `echo $?`.
  16. - **Secret guard.** Common key and token formats are rejected before sending.
  17. - **Zero dependencies.** A single Python 3 file using only the standard library (Python 3.9+). It runs on macOS and Linux.
  18. Command output, the onboarding briefs and the skill are currently written in Chinese.
  19. ## Install
  20. ### Ask Claude to install it
  21. Paste this into Claude Code:
  22. ```text
  23. Install claude-mailbox for me: clone https://github.com/Gordonynh/claude-mailbox.git into ~/.local/share/claude-mailbox (git pull if it is already there), run ./install.sh --mcp in that directory, confirm that `cmb version` and `claude mcp get mailbox` both succeed, and tell me to start a new session so the mailbox tools load.
  24. ```
  25. ### Install by hand
  26. ```bash
  27. git clone https://github.com/Gordonynh/claude-mailbox.git
  28. cd claude-mailbox
  29. ./install.sh # links bin/cmb into ~/.local/bin and installs the skill into ~/.claude/skills
  30. ```
  31. You can also install it as a Claude Code plugin (`/plugin marketplace add Gordonynh/claude-mailbox`, then `/plugin install session-mailbox@session-mailbox`). The plugin bundles the skill and the MCP server, and puts `cmb` on the Bash tool's PATH.
  32. Register the MCP server for all projects:
  33. ```bash
  34. ./install.sh --mcp # same as: claude mcp add -s user mailbox -- python3 <repo>/bin/cmb mcp
  35. ```
  36. ## Quick start
  37. ```bash
  38. cmb init ~/mailboxes/demo --example # 1 lead, 2 group leads, 3 workers each
  39. cmb --root ~/mailboxes/demo tree
  40. cmb --root ~/mailboxes/demo guide alpha-1 # paste the output into the alpha-1 session
  41. ```
  42. `mailbox.conf`, one member per line:
  43. ```text
  44. # name parent prefix role
  45. lead - L Lead
  46. alpha lead A Frontend group lead
  47. alpha-1 alpha A1 Frontend worker
  48. option rotate_bytes 262144
  49. option keep 50
  50. ```
  51. ## Sending and reading
  52. ```bash
  53. R=~/mailboxes/demo
  54. cmb send --root $R --as alpha --to alpha-1 "Please build the order page."
  55. cmb send --root $R --as alpha --to @children "Submit by 18:00."
  56. cmb send --root $R --as alpha-1 --to @parent "Order page done."
  57. cmb reply A1-1 --root $R --as alpha "Merged." # goes to the original sender
  58. cmb ack A-1 --root $R --as alpha-1 "Started."
  59. cmb unread --root $R --as alpha # full text of unread mail, then marks read
  60. cmb inbox --root $R --as alpha # recent headers
  61. cmb since A1-3 --root $R --as alpha # everything after a message, archives included
  62. cmb thread A1-1 --root $R
  63. cmb wait --root $R --as alpha --timeout 110s # block until mail arrives; exit code 6 on timeout
  64. cmb acks A-3 --root $R --wait 300s # tally replies; wait until everyone has replied
  65. cmb send --root $R --as alpha --cascade "Freeze merges at 17:00." # every descendant at once
  66. ```
  67. Only one `unread` or `wait` may run per member at a time. If two readers ran at once, one would mark the mail as read and the other would miss it, so the second one is refused (exit code 7). Add `--peek` to look without marking, or run `unread --peek` and then `mark-read #<n>` once the mail is handled.
  68. `acks` counts a reply when a recipient answers the message and the answer goes to the original sender (`ack`, `reply` and `send --reply-to` all count).
  69. Group recipients: `@parent`, `@children` and `@siblings` are always allowed. `@subtree` and `@all` require `--escalate`. `--cascade` (instead of `--to`) reaches every descendant without `--escalate` and marks the header `cascade`; use it for notices that need no processing in between. Results should still be reported level by level.
  70. ## Claude Code integration
  71. **The mailbox is the only channel between members.** Tasks, questions, progress, results and acknowledgements all go through the mailbox. Do not rely on Claude Code's built-in return paths:
  72. - A subagent started with the Agent tool hands a final report back to the session that started it, and a side session relays its final reply upward. These bypass the mailbox, so routing rules do not apply and nothing can be traced in the mailbox. A member's final reply should only say "Reported via the mailbox (message X)".
  73. - The dispatching side judges whether a member is done only from mailbox messages, not from subagent return values or session notifications. If they disagree, the message wins.
  74. - Do not use `SendMessage` to assign work or chase progress. Write a message instead.
  75. - To guarantee the mailbox is the only channel, run members as independent sessions or headless processes (`claude -p`) rather than Agent subagents.
  76. The `join` result, the `cmb guide` brief and the skill all state this rule.
  77. Arm a Monitor in each session (`timeout_ms: 1800000`):
  78. ```bash
  79. cmb --root ~/mailboxes/demo watch --as alpha-1
  80. ```
  81. Each new message produces exactly one line, and therefore one notification. A Monitor runs for at most 30 minutes, so re-arm it as soon as it expires. Because `watch` reports all unread mail on startup, nothing is lost in the gap. `cmb monitor-cmds` prints the command for every member. `cmb guide <member>` prints a ready-to-paste onboarding brief. The skill in [`skills/session-mailbox/SKILL.md`](skills/session-mailbox/SKILL.md) teaches sessions the full protocol: receiving mail, replying with ACK, re-arming the Monitor and catching up on missed mail.
  82. ### MCP tools
  83. `cmb mcp` is a stdio MCP server built on the standard library only. Each session runs its own server process, which keeps that session's identity. Call `join` first with `member` and, optionally, `root`. Then use these tools:
  84. - `send`, `reply`, `ack` and `forward` to write;
  85. - `unread`, `inbox`, `since`, `read` and `thread` to read;
  86. - `wait` to block until mail arrives, which then returns the full text;
  87. - `tree`, plus `claim`, `release` and `claims` for shared resources.
  88. There are three ways to receive mail, and you can combine them:
  89. | Method | Where | Latency |
  90. | --- | --- | --- |
  91. | Channel push (`notifications/claude/channel`) | Interactive CLI started with `claude --dangerously-load-development-channels server:mailbox` | ~0.3 s |
  92. | `wait` tool | Any session with the MCP server | ~0.1 s |
  93. | Monitor + `cmb watch` | Any session, including the desktop app | ~0.3 s |
  94. | `cmb wait` | Any session that can run Bash, including headless processes and subagents | under 0.1 s |
  95. In the main session, tool calls longer than 2 minutes are moved to the background automatically. Calls with no response for 30 minutes are aborted, so `wait` is capped at 1500 s. Pass `--no-channel` to disable push. `acks` tallies replies (`wait_seconds` waits for everyone), `send` and `forward` accept `cascade`, and `claim` accepts `wait_seconds` and `ttl_minutes`.
  96. ### Headless processes and subagents
  97. Headless processes (`claude -p`) and subagents cannot approve permissions on the spot, so they stall without allow rules. Generate the configuration before starting them:
  98. ```bash
  99. cmb --root ~/mailboxes/demo permissions --as beta-2
  100. cmb --root ~/mailboxes/demo guide beta-2 --permissions # the brief followed by the same configuration
  101. ```
  102. The output contains the `permissions.allow` rules for `.claude/settings.json` (`Bash(cmb *)` and `mcp__mailbox`), the equivalent `--allowedTools` flags for `claude -p`, and an `--mcp-config` snippet with the mailbox and identity preset.
  103. These sessions have no Monitor, so they wait with `cmb wait`. Upstream members may take minutes to answer. A timeout (exit code 6) is not an error: run the same command again rather than using one short timeout. The Bash tool times out after 2 minutes by default, which is why `cmb wait` defaults to 110 s.
  104. ### Suggested workflow
  105. 1. The lead creates the mailbox with `cmb init` and writes the member table.
  106. 2. The lead starts group-lead sessions, giving each the mailbox path and member name (or the output of `cmb guide <member> --permissions`). Group leads start their workers the same way.
  107. 3. Every session joins first and makes sure it receives mail, then starts work and reports to `@parent` when done.
  108. 4. The dispatching side tallies replies with `acks <id> --wait` instead of counting messages, and sends plain notices with `--cascade`.
  109. 5. Every level acts only on mailbox messages, never on subagent return values or session notifications.
  110. Pick models by role: intermediate levels mostly relay and summarise, so a smaller, faster model is usually enough. When dozens of processes start at once, model requests may queue; consider starting the levels in stages.
  111. ## Rules and conventions
  112. - **Relay, don't skip levels.** A worker that needs the lead writes to its group lead. The group lead relays the message with `cmb forward <id> --to lead`. Replies to any message you received are always allowed.
  113. - **Announce shared-resource use.** Claim the resource and notify before you start, then release it and notify when you finish:
  114. `cmb claim deploy --as beta --note "release v2" --notify @parent`, then `cmb release deploy --as beta --notify @parent "done"`.
  115. If the resource is held, `--wait 300s` queues in arrival order and takes it automatically when it is your turn; a queued process that exits drops out of the queue within 5 s. `--ttl 10m` releases the claim automatically (`90s`, `10m`, `1h`; a bare number means minutes), and claiming again as the holder renews it.
  116. - **Run commands exactly as given.** The first line of output states the result, and failures read like `cmb:已拒绝(退出码 3):…` with the exit code, so there is no need to append `; echo $?`.
  117. - **Never put secrets or personal data in messages.** The built-in check is a guardrail, not a guarantee.
  118. - **Do not edit mailbox files by hand.** Use `cmb rotate` to clean up.
  119. - **Pass `--root` and `--as` on every command.** Each Bash call in Claude Code starts a fresh shell, so environment variables do not persist.
  120. - **Keep the mailbox on a local disk.** `flock` may be unreliable on NFS, SMB or cloud-synced folders. Windows is not supported; use WSL.
  121. Exit codes: 0 ok, 1 error, 2 usage, 3 routing denied, 4 suspected secret, 5 resource held by someone else (or queue timeout), 6 wait timeout, 7 another reader is already running for this member.
  122. ## Tests
  123. ```bash
  124. python3 -m unittest discover -s tests -v
  125. examples/demo.sh
  126. ```
  127. ## License
  128. [MIT](LICENSE)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.