DLB — Dead Letter Box

A tiny MCP server that lets independent AI-agent sessions leave each other notes. Fire-and-forget. Queued for non-existent recipients. No daemon. Six tools + an optional dlb-monitor wake source.

Why

If you've ever had two Claude Code / Cursor / Codex sessions running in different terminals and wished they could coordinate, you've hit the gap DLB fills. Existing options (mcp_agent_mail, agent frameworks like CrewAI/AutoGen) either bundle too much (40+ tools, contact policies, file leases) or only work inside a single parent process.

DLB does one thing: messages between agent sessions. It does NOT do orchestration, contact handshakes, file reservations, web hosting, or auto-name-generation. If you want those, you want a different tool.

Five differentiators (vs. mcp_agent_mail and friends)

1. 6 tools — fits cleanly in Claude Code's tool list without crowding out the builtins.
2. No daemon — each MCP call opens SQLite, runs one transaction, closes. No server.lock, no port management.
3. Names accepted as-is — call yourself alpha, ThreadBeta, worker-1. DLB will not rename you.
4. Real dead-letter semantics — send(to="ghost") succeeds and queues the message; if/when someone registers as ghost, the messages are waiting.
5. Zero ceremony — send works on call one. Registration is optional and observational.

Install

Zero-install (recommended — uvx fetches and runs on demand):

uvx dlb-mcp

Or install once:

uv tool install dlb-mcp

Wire into Claude Code

Add to ~/.claude.json:

{
  "mcpServers": {
    "dlb": {
      "type": "stdio",
      "command": "uvx",
      "args": ["dlb-mcp"]
    }
  }
}

Multiple sessions can coexist — they all share ~/.dlb/store.sqlite3 via SQLite WAL mode.

The 8 tools

That's the entire API.

Task lifecycle (v0.3.0+) — the pattern that closes the "delivered ≠ acted on" gap

DLB 0.2.x guaranteed delivery and read-receipts, but a message the recipient had read yet not acted on was indistinguishable (to the sender) from a task in progress. A documented incident (2026-07-01) had a security-review task sit unexecuted for ~1 hour with no signal.

v0.3.0 adds the minimum vocabulary to close that gap as a convention, not enforcement — DLB stays a small file store; the state machine lives in the CLAUDE.md DLB Inbox Protocol.

Sender pattern:

task = send(to="worker", body="run /security-review", msg_type="task")
# ... later, without holding worker's session_token:
status = get_task_status(task.id)
# → {"status": "running", "status_note": "scanning src/", "read_at": "..."}

Recipient pattern (as required by the DLB Inbox Protocol in ~/.claude/CLAUDE.md):

inbox = read(name="worker", session_token=my_token)
for msg in inbox:
    if msg.msg_type == "task":
        # STEP 1: reply IMMEDIATELY (before starting work)
        send(to=msg.sender_name, body="accepted, ETA 20m",
             session_token=my_token, in_reply_to=msg.id)
        update_status(msg.id, "accepted", my_token, note="ETA 20m")

        # STEP 2: do the work
        result = do_work(msg.body)
        update_status(msg.id, "running", my_token, note="in progress")

        # STEP 3: report completion
        send(to=msg.sender_name, body=f"done: {result}",
             session_token=my_token, in_reply_to=msg.id)
        update_status(msg.id, "done", my_token, note=result)

What DLB does NOT do:

• No enforcement — nothing forces status values to a fixed set.
• No SLA nudges — DLB won't automatically re-notify a stale task. That's a job for a task-orchestration product built on top of DLB.
• No heartbeat beacons — the recipient calls update_status explicitly when the state changes.
• No history — only the LATEST status per message is stored; note-per-status is not preserved.

If you need any of those, you want a full task-orchestration layer, not more features on DLB.

Push-like wake — dlb-monitor + Claude Code's Monitor tool

DLB itself is polling-only (request-response MCP, no push). But Claude Code has a Monitor tool that streams stdout from a long-running process into the conversation as notifications — each line wakes the LLM mid-idle. dlb-monitor is a tiny CLI that polls the same SQLite store and emits one line per new message, designed to be wrapped by Monitor:

# Run this at session start (or have the LLM call it after registering):
Monitor({
  command: "dlb-monitor --name alpha",
  description: "DLB inbox: alpha",
  persistent: true
})

Each new message addressed to alpha produces one stdout line:

2026-06-30T21:30:14Z bravo: "ping — can you look at the reskin route?"

Filters:

dlb-monitor --name alpha --include-senders bob,carol      # allowlist
dlb-monitor --name alpha --exclude-senders bot,system     # denylist
dlb-monitor --name alpha --interval 1                     # tick frequency (default 2s)

When dlb-monitor is the right answer vs. dlb-launcher:

They're complementary, not competitive.

Configuration

Trust model — coordination, not confidentiality

DLB is for cooperating agents under the same OS user, not against adversarial ones. Specifically:

• session_token gates the DLB tool API, not the underlying SQLite file. Any process running as the same OS user can open ~/.dlb/store.sqlite3 directly and read every body, every token. Tightening file perms (0600) raises the bar against accidental leakage, but does not change the threat model.
• Send is open by default. Anyone running as your user can drop messages into any inbox. Passing session_token on send makes provenance trustworthy (binds from_ to the token's name); tokenless sends keep the unverified free-text from_ field.
• force=True is stale-gated. Without a matching prior_token or a stale holder (> DLB_TAKEOVER_AFTER_SECONDS), name takeover is rejected — closes the casual-hijack hole of v0.1.
• No TLS, no accounts, no cross-host. If you need a real adversarial boundary between agent sessions, you want a broker-process design (DLB rejects this — it would break the "no daemon" promise) or a different tool entirely.

What DLB is NOT

• Not an orchestrator. Use a script + your LLM SDK if you need to spawn agents.
• Not a web service. Local only.
• Not Gmail. No threading, replies, CC/BCC, attachments, contacts, importance flags.
• Not a file-coordination tool. No file leases or advisory locks.
• Not push by itself — but dlb-monitor + Claude Code's Monitor tool gets you there (see above).

If you find yourself wishing for any of these, that's a signal to use a different tool, not to ask DLB to grow.

License

MIT.