66967167bc
Adds `install-hook` / `uninstall-hook` subcommands that idempotently patch ~/.claude/settings.json (or .claude/settings.json with --project), plus a `--hook` flag on `check` that emits human-readable output and stays silent on empty inbox or unreachable daemon.
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>
|
|
```
|
|
|
|
`gyp ERR! find VS` on Windows during install
|
|
: `better-sqlite3` ships prebuilt binaries for current Node LTS versions. If yours isn't covered, npm falls back to building from source and needs the Visual Studio Build Tools. Either install them or pin to a Node version with a matching prebuild.
|