# @kuns/claude-mailbox

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

## 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 hooks (auto-check inbox)

Register the full plugin-equivalent hook set so Claude pulls pending mailbox messages at every natural sync point:

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

This installs five hooks:

| Event | Command | When it fires |
|---|---|---|
| `SessionStart` | `session-announce` | Announces this session's mailbox identity + active peers. |
| `UserPromptSubmit` | `check --hook` | Before each user prompt. |
| `SubagentStop` | `check --hook` | When a subagent finishes. |
| `TaskCompleted` | `check --hook` | When Claude marks a `TaskCreate` task completed — gives mid-run sync points. |
| `SessionEnd` | `session-end` | Cleans up the auto-derived mailbox if empty. |

The mailbox name is auto-derived from the session-id stdin payload — no `--name` required. Install is idempotent and only touches our own commands; other hooks and settings are preserved.

`check --hook`:

- 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 fire (~100ms on Windows).

## Push delivery (watch)

For long-running autonomous sessions, run the watcher as a background bash task so peer messages surface immediately via `BashOutput`:

```sh
claude-mailbox watch --block --name <mailbox>
```

Exit codes: `0` delivered or renamed, `1` error, `2` daemon unreachable, `3` timeout. See the [repository README](https://git.kuns.dev/releases/ClaudeMailbox/src/branch/main/README.md#push-delivery-watch) for the full contract.

## 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).