Files
ClaudeMailbox/node
Mika Kuns bc53daf6e6 fix(server): set explicit connectionTimeout to bound long-poll sockets
Fastify's default connectionTimeout is 0 (no timeout). With /v1/watch
holding requests open for up to 300s, an OS-level cap prevents a stuck
socket from persisting forever even if app-level cleanup misses a case.
Set just above the watch max so a healthy long-poll never races the
socket timeout.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-20 16:24:26 +02:00
..
2026-05-20 14:41:56 +02:00
2026-05-20 14:41:56 +02:00

@kuns/claude-mailbox

Standalone MCP mail server that lets parallel Claude sessions coordinate with each other.

Install

One-time per machine:

npm config set @kuns:registry=https://git.kuns.dev/api/packages/releases/npm/
npm install -g @kuns/claude-mailbox

Then:

claude-mailbox install-autostart   # registers per-OS autostart, no admin needed by default

See the repository README for the full architecture, MCP tool reference, and .mcp.json snippet.

Claude Code hook (auto-check inbox)

Register a UserPromptSubmit hook so Claude pulls pending mailbox messages before every prompt:

claude-mailbox install-hook --name alice            # patches ~/.claude/settings.json
claude-mailbox install-hook --name alice --project  # patches <cwd>/.claude/settings.json
claude-mailbox uninstall-hook                       # remove again

The hook is idempotent (running install-hook twice does nothing the second time) and only touches the UserPromptSubmit block — other hooks and settings are preserved.

Under the hood the hook runs claude-mailbox check --name <mailbox> --hook, which:

  • prints unread messages in a Claude-friendly format,
  • silently exits 0 if the inbox is empty or the daemon is unreachable (no context noise),
  • marks the messages delivered so they aren't injected again next prompt.

Cost: one local HTTP round-trip plus Node coldstart per prompt (~100ms on Windows).

Troubleshooting

npm install returns 401 Unauthorized
The Gitea registry usually serves the releases scope publicly, but if your instance requires auth you'll need a read token:
npm config set //git.kuns.dev/api/packages/releases/npm/:_authToken=<token>
Cannot find module 'node:sqlite' or similar
claude-mailbox uses Node's built-in node:sqlite, stable since Node 24. On Node 22.523.x it works only with --experimental-sqlite. Upgrade to Node 24 LTS or newer: nvm install 24 && nvm use 24 (or winget install OpenJS.NodeJS.LTS on Windows).