8832eab6c7
Some checks failed
CI (Node) / build-test (push) Failing after 8s
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>
53 lines
2.2 KiB
Markdown
53 lines
2.2 KiB
Markdown
# @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:
|
||
|
||
```sh
|
||
npm config set @kuns:registry=https://git.kuns.dev/api/packages/releases/npm/
|
||
npm install -g @kuns/claude-mailbox
|
||
```
|
||
|
||
Then:
|
||
|
||
```sh
|
||
claude-mailbox install-autostart # registers per-OS autostart, no admin needed by default
|
||
```
|
||
|
||
See the [repository README](https://git.kuns.dev/releases/ClaudeMailbox/src/branch/main/README.md) 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:
|
||
|
||
```sh
|
||
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:
|
||
|
||
```sh
|
||
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).
|