CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Repo layout (important)

The active codebase lives entirely in node/ (TypeScript, Node 24+). The top-level src/ClaudeMailbox/ and tests/ClaudeMailbox.Tests/ directories are stale .NET build artifacts (bin/, obj/ only) left over from an abandoned C# prototype — ignore them, don't build them, don't grep them.

Other top-level dirs:

plugin/ — the Claude Code plugin (hooks/hooks.json, slash commands/, the mailbox-collaborate skill). Loaded via .claude-plugin/marketplace.json.
homebrew/, install.ps1, install.sh — distribution shims for the published npm package @kuns/claude-mailbox.
docs/superpowers/ — design specs and plans (history, not runtime).

Development commands

All commands run from node/:

cd node
npm install
npm run build           # tsc → dist/
npm test                # pretest builds, then vitest run
npm run test:watch      # vitest in watch mode
npx vitest run tests/cli-watch.test.ts   # single test file
npx vitest run -t "rename"               # by test name pattern
npm start               # node dist/cli.js serve  (run daemon in foreground)

npm test runs pretest (build) first — vitest executes against dist/, not via a TS transformer, so always rebuild after editing src/ if running vitest directly.

Vitest config: tests/**/*.test.ts, pool: "forks", 15 s timeout. Tests spin up real Fastify servers and real SQLite files in temp dirs — they are integration tests, not unit tests with mocks.

Runtime CLI surface (after `npm run build`)

dist/cli.js is the single entry point (bin name claude-mailbox):

serve | send | peek | check [--hook] | watch --block | list | status
session-announce                       # SessionStart hook helper, reads stdin JSON
session-end                            # SessionEnd hook helper, deletes mailbox if empty
install-hook / uninstall-hook          # patch settings.json
install-autostart / uninstall-autostart [--service]   # OS autostart registration
mcp-stdio                              # stdio MCP wrapper that proxies to the HTTP daemon

All subcommands accept --url <url>; CLAUDE_MAILBOX_URL env overrides the default http://127.0.0.1:37849.

Architecture

One long-running daemon, single SQLite file, multiple thin clients.

clients (Claude sessions, CLI, scripts)
        │  HTTP loopback
        ▼
claude-mailbox serve   (Fastify, port 37849)
   ├─ /mcp           MCP Streamable HTTP transport (registerMcp)
   ├─ /v1/send /peek /check-inbox /watch /list   REST
   └─ /health
        │
        ▼
~/.claude-mailbox/mailbox.db   (SQLite WAL, two tables: mailboxes, messages)

Module map under node/src/:

File	Responsibility
`cli.ts`	Commander CLI; dispatches to every other module. Single entry.
`server.ts`	Fastify app, request hook that enforces `X-Mailbox` header on non-anonymous paths, REST routes.
`mcp.ts`	Registers MCP tools (`send`, `check_inbox`, `peek_inbox`, `list_mailboxes`, `rename`) on the same Fastify app at `/mcp`.
`mcp-stdio.ts`	Stdio MCP wrapper used by the plugin's `.mcp.json` — proxies tool calls to the HTTP daemon (workaround for Claude Code not yet supporting env-var substitution in HTTP MCP URLs).
`db.ts`	`MailboxStore` — all SQL via `node:sqlite` (no ORM). Owns DDL idempotency, atomic `check_inbox`, rename-with-message-transfer, long-poll `wait` for push delivery.
`hook.ts`	Helpers shared by `session-announce` / `check --hook` / `install-hook`: stdin parsing, identity derivation (`<project>-<8hex>` from `session_id`), settings.json patching, peer formatting.
`config.ts`	Config precedence: CLI flag > `mailbox.json` > defaults. Looks in `~/.claude-mailbox/mailbox.json` and on Windows also `%ProgramData%\ClaudeMailbox\mailbox.json`.
`autostart/{windows,darwin,linux}.ts`	Per-OS autostart: Scheduled Task / HKCU Run / `node-windows` service / launchd LaunchAgent / systemd `--user`. Selected via `autostart/index.ts`.

Identity derivation

hook.ts::deriveSessionName builds the mailbox name from the SessionStart hook's stdin JSON (session_id, cwd): <sanitized-project>-<first-8-hex-of-session-id>. Project name is the git repo basename if inside a repo, else the cwd basename, sanitized (lowercased, non-alphanumerics → -, capped at 40 chars). Without a cwd it degrades to claude-<8hex>. This is how two parallel sessions in the same project stay distinct.

Push delivery (`watch --block`)

Long-poll on GET /v1/watch?name=…&timeout=…. The daemon parks the request on an in-memory waiter list keyed by mailbox; send wakes the first waiter atomically (FIFO winner across concurrent watchers). Exit codes: 0 delivered (or Mailbox renamed to '<new>' on stdout), 2 daemon unreachable, 3 timeout. Push is opt-in — the plugin's SessionStart hook does not launch the watcher automatically; users invoke the mailbox-collaborate skill (or /collaborate) to enter collaboration mode. The pull path via UserPromptSubmit / SubagentStop hooks remains the always-on fallback.

Plugin hooks (what runs without you doing anything)

plugin/hooks/hooks.json wires five hooks to the installed claude-mailbox binary:

SessionStart → claude-mailbox session-announce (prints identity + active peers into context, registers session with daemon)
UserPromptSubmit → claude-mailbox check --hook (drains inbox, injects messages)
SubagentStop → claude-mailbox check --hook (same, when a subagent finishes)
TaskCompleted → claude-mailbox check --hook (same, when Claude marks a TaskCreate task completed — gives mid-run sync points between todo items)
SessionEnd → claude-mailbox session-end (deletes the session's mailbox if no pending messages — same semantics as the sweeper, just immediate; renamed mailboxes are preserved because the auto-derived name no longer exists)

install-hook / uninstall-hook patch the same five events into settings.json for users not using the plugin. The manual installer is multi-event aware — adding/removing a hook in plugin/hooks/hooks.json should be mirrored by MANAGED_HOOK_EVENTS and buildPluginHookCommands in hook.ts.

Conventions worth knowing

ES modules with NodeNext resolution — relative imports must use the .js extension even in .ts source (e.g. import { … } from "./db.js").
tsconfig.json is strict including noUnusedLocals / noUnusedParameters — dead identifiers fail the build.
node:sqlite is used directly (no better-sqlite3) — Node 24+ requirement comes from this.
The daemon never authenticates: loopback bind + filesystem perms are the trust boundary. X-Mailbox header is identity, not auth — anything on loopback can claim any name. Don't add code that assumes otherwise.
*.db, *.db-shm, *.db-wal are gitignored — never commit a real mailbox DB.

Release

node/package.json is the published artifact (@kuns/claude-mailbox, registry https://git.kuns.dev/api/packages/releases/npm/). Version bumps land as chore(release): X.Y.Z commits (see git log). The plugin and the npm package version-lockstep — mailbox-doctor and mailbox-update slash commands run npm install -g @kuns/claude-mailbox against that registry.

7.3 KiB Raw Blame History