Files

CI (Node) / build-test (push) Successful in 9s

Details

fix(cli,plugin): CLAUDE_MAILBOX_URL env override + port-conflict-aware doctor

The plugin's UserPromptSubmit and SessionStart hooks call `claude-mailbox`
with no --url flag, so they previously always hit the hardcoded
http://127.0.0.1:47822/mcp default. If port 47822 was held by another
local service (e.g. ClaudeDo), the daemon couldn't bind there and every
hook was talking to the wrong process.

CLI default for --url now resolves to $CLAUDE_MAILBOX_URL when set,
falling back to http://127.0.0.1:47822. Doctor gained a Step 2 that
probes /health on 47822, identifies foreign occupants, picks a free
port, writes both ~/.claude-mailbox/mailbox.json and the
CLAUDE_MAILBOX_URL entry in .claude/settings.json env so the hooks
follow along automatically.

Also adds a fallback hint when Windows schtasks /Create fails with
Access is denied (Group Policy restricts non-admin task creation): run
install-autostart from an elevated shell, or accept an ephemeral serve
for the current session.

2026-05-19 13:30:51 +02:00

src

fix(cli,plugin): CLAUDE_MAILBOX_URL env override + port-conflict-aware doctor

2026-05-19 13:30:51 +02:00

tests

fix(cli,plugin): CLAUDE_MAILBOX_URL env override + port-conflict-aware doctor

2026-05-19 13:30:51 +02:00

.gitignore

feat(node): add TypeScript sibling project for npm-based install

2026-04-30 14:06:46 +02:00

package-lock.json

chore(node): release v0.1.0

2026-05-19 12:01:41 +02:00

package.json

fix(ci): add pretest hook so vitest sees built dist/cli.js

2026-05-19 13:12:59 +02:00

README.md

feat(node): add Claude Code UserPromptSubmit hook for auto inbox-check

2026-05-19 10:09:30 +02:00

tsconfig.json

feat(node): add TypeScript sibling project for npm-based install

2026-04-30 14:06:46 +02:00

vitest.config.ts

feat(node): add TypeScript sibling project for npm-based install

2026-04-30 14:06:46 +02:00

README.md

@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>

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.