Files

CI (Node) / build-test (push) Failing after 8s

Details

refactor(node): migrate from better-sqlite3 to node:sqlite, require Node 24+

Native binding caused install pain on every new Node major (no prebuilts +
node-gyp needs VS+Windows SDK to fall back). For this project's workload
(a few ops/day, no advanced SQLite features) better-sqlite3's perf edge is
irrelevant — node:sqlite's bundled, ABI-stable sync API is the better fit.

- db.ts: DatabaseSync, db.exec("PRAGMA …"), explicit BEGIN/COMMIT helper to
  replace db.transaction(); row casts go through unknown because node:sqlite
  returns Record<string, SQLOutputValue>.
- package.json: drop better-sqlite3 + @types/better-sqlite3, bump
  engines.node to >=24, vitest 2 → 4 (2.x couldn't resolve `node:sqlite`).
- mailbox-doctor: add Step 1 that enforces Node ≥24 with a concrete fix
  message, renumbers downstream steps.

Node 1.2.0 → 1.3.0. 35 transitive packages removed from the lockfile.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

2026-05-19 16:07:21 +02:00

2.2 KiB

Raw Blame History

@kuns/claude-mailbox

Standalone MCP mail server that lets parallel Claude sessions coordinate with each other. TypeScript / Node port of the .NET claude-mailbox daemon — wire-compatible (same port, same X-Mailbox header, same MCP tool names, same SQLite schema).

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)

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.5–23.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).

2.2 KiB Raw Blame History Unescape Escape

@kuns/claude-mailbox

Install

Claude Code hook (auto-check inbox)

Troubleshooting

2.2 KiB

Raw Blame History