# claude-mailbox plugin

Lets Claude Code pull unread messages from a local `claude-mailbox` daemon before every prompt and inject them into the conversation context.

## Setup (two steps, all inside Claude Code)

```
/plugin marketplace add https://git.kuns.dev/releases/ClaudeMailbox
/plugin install claude-mailbox@claude-mailbox
/claude-mailbox:mailbox-doctor
```

The doctor command walks the rest:

1. checks whether the `claude-mailbox` binary is on `PATH` — installs it (`npm install -g @kuns/claude-mailbox`) if missing, asks before doing anything that might need elevation
2. checks the daemon status — runs `install-autostart` and/or `start` until it reports `Running`
3. ensures `CLAUDE_MAILBOX_NAME` is set in `.claude/settings.json` env — prompts for a name if not, writes it idempotently
4. runs a self → self smoke test to verify the round-trip works

Restart Claude Code after the doctor finishes (only needed if the mailbox name was newly written). Unread messages will then appear in context before every prompt.

## Why a mailbox name?

Each Claude session has an identity used to address peer sessions — like an email address. If you run a `backend` session and a `frontend` session in parallel, they need different names so they can send messages to each other.

For a single Claude Code instance just wanting notifications, any stable kebab-case name works. The name lives in **per-project** `.claude/settings.json` env, so different worktrees / projects automatically get different mailboxes.

## What the hook actually does

Before every prompt the plugin runs `claude-mailbox check --hook`, which:

- prints unread mailbox messages in a Claude-friendly format and marks them delivered,
- stays **silent** when the inbox is empty or `CLAUDE_MAILBOX_NAME` is not set,
- emits a one-line setup hint when the daemon is unreachable, so a missing daemon is loud, not invisible.

Cost: one local HTTP round-trip plus Node coldstart per prompt (~100ms on Windows).

## Commands

| Command | What it does |
|---|---|
| `/claude-mailbox:mailbox-doctor` | Diagnose + auto-fix the full setup. |
| `/claude-mailbox:mailbox-status` | Read-only health check. No changes. |

## Smoke test (manually, after doctor finishes)

```sh
claude-mailbox send --from probe --to <your-mailbox-name> --body "hello"
```

Then start a new Claude Code prompt — the message should appear in context before Claude's first reply.

## Uninstall

```
/plugin uninstall claude-mailbox@claude-mailbox
npm uninstall -g @kuns/claude-mailbox
claude-mailbox uninstall-autostart    # if you used it
```