Initial

2026-04-24 18:26:11 +02:00
commit ec42e8e4bd
28 changed files with 1205 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,120 @@
+# ClaudeMailbox
+
+A standalone MCP mail server that lets parallel Claude sessions coordinate with each other. Any Claude session (plain terminal, ClaudeDo worktree, anything that consumes `.mcp.json`) can send messages to a peer session's inbox, check for pending messages, and discover other active mailboxes.
+
+Not a substitute for `run_in_background: true` — that handles single-session responsiveness. This handles **session-to-session** coordination.
+
+## Architecture
+
+One long-running daemon binds HTTP on loopback, hosts the MCP server at `/mcp` and a small REST API at `/v1/*`, and persists state in a single SQLite file. Sessions declare themselves via an `X-Mailbox` header in their `.mcp.json`.
+
+```
+ session-backend                 session-frontend           external sender
+ (X-Mailbox: backend)            (X-Mailbox: frontend)      (CLI / UI / hook)
+        |                                |                          |
+        |  HTTP                          |                          |
+        +--------------+-----------------+--------------------------+
+                       v
+         claude-mailbox serve  (ASP.NET Core + Kestrel)
+           /mcp      MCP tools
+           /v1/*     REST for non-MCP senders
+           /health
+                       v
+         ~/.claude-mailbox/mailbox.db  (SQLite WAL)
+```
+
+## Install
+
+```powershell
+dotnet publish -c Release -r win-x64 --self-contained -p:PublishSingleFile=true
+```
+
+Put the resulting `claude-mailbox.exe` on your `PATH`.
+
+## Daemon lifecycle
+
+The daemon is a normal console process. Pick whichever level of automation you want:
+
+1. **Manual.** Open a terminal, run `claude-mailbox serve`, leave it open. Stops when you close the window.
+2. **Startup shortcut.** Drop a shortcut to `claude-mailbox serve` in `shell:startup` — starts on login.
+3. **Windows Service.** `sc.exe create ClaudeMailbox binPath= "C:\path\to\claude-mailbox.exe serve" start= auto` — same pattern ClaudeDo uses.
+
+Defaults: port `47822`, bind `127.0.0.1`, database at `%USERPROFILE%\.claude-mailbox\mailbox.db`. All overridable:
+
+```
+claude-mailbox serve [--port 47822] [--bind 127.0.0.1] [--db-path <path>]
+```
+
+## Use from a Claude session
+
+Drop this into your project's `.mcp.json` (one per session, different `X-Mailbox` values):
+
+```json
+{
+  "mcpServers": {
+    "mailbox": {
+      "type": "http",
+      "url": "http://127.0.0.1:47822/mcp",
+      "headers": {
+        "X-Mailbox": "backend"
+      }
+    }
+  }
+}
+```
+
+Four MCP tools are exposed:
+
+| Tool | Purpose |
+|---|---|
+| `mcp__mailbox__send(to, body)` | Send a message to another mailbox |
+| `mcp__mailbox__check_inbox()` | Pull all pending messages for this mailbox (marks delivered) |
+| `mcp__mailbox__peek_inbox()` | Non-consuming check — returns `{ pending, oldestAt }` |
+| `mcp__mailbox__list_mailboxes()` | Discover known mailboxes and who has mail for you |
+
+### Suggested CLAUDE.md snippet for poll discipline
+
+```
+When coordinating with a peer session, call mcp__mailbox__peek_inbox
+after each subagent completes. If pending > 0, call mcp__mailbox__check_inbox
+and treat the messages as input with priority over the current plan.
+```
+
+## CLI client mode
+
+Any external process (scripts, UIs, hooks) can talk to a running daemon without needing MCP:
+
+```
+claude-mailbox send  --to <mailbox> --from <mailbox> --body <text> [--url http://127.0.0.1:47822]
+claude-mailbox peek  --name <mailbox>                              [--url ...]
+claude-mailbox check --name <mailbox>                              [--url ...]
+claude-mailbox list                                                [--url ...]
+```
+
+The CLI subcommands are thin HTTP clients against the `/v1/*` endpoints.
+
+## REST surface
+
+| Method | Path | Requires `X-Mailbox` | Purpose |
+|---|---|---|---|
+| `GET` | `/health` | no | `{ status, version, dbPath }` |
+| `POST` | `/v1/send` | yes (sender) | `{ to, body }` |
+| `GET` | `/v1/peek?name=<mailbox>` | no | read-only status |
+| `POST` | `/v1/check-inbox?name=<mailbox>` | yes (must match `name`) | consume inbox |
+| `GET` | `/v1/list` | no | list all mailboxes |
+
+## Development
+
+```
+dotnet build
+dotnet test tests/ClaudeMailbox.Tests/ClaudeMailbox.Tests.csproj
+dotnet run --project src/ClaudeMailbox -- serve
+```
+
+Test suite covers end-to-end coordination, concurrent `check_inbox` race safety, and schema idempotency.
+
+## Scope
+
+- Loopback bind only (v1). Cross-machine coordination is a future extension — swap the middleware for token auth and change the bind address.
+- No auth on loopback. Local filesystem permissions are the trust boundary.
+- No message expiry or cleanup. Delivered messages stay as a timeline/audit log.