releases/ClaudeMailbox
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 17 Wiki Activity

feat(hook): add TaskCompleted drain + multi-event install-hook

Browse Source 
Wire a fifth pull hook so peer messages also surface between todo
items, not only at user prompts and subagent stops. While here,
extend the manual `install-hook` CLI so it patches the full plugin
hook set (SessionStart/UserPromptSubmit/SubagentStop/TaskCompleted/
SessionEnd) instead of only UserPromptSubmit, mirroring what the
plugin's hooks.json registers. Mailbox name is auto-derived from
stdin, so --name is no longer required.

Also corrects stale docs that claimed SessionStart auto-bootstraps
the watcher — push delivery has been opt-in since the
mailbox-collaborate skill landed.
This commit is contained in:
Mika Kuns
2026-05-27 11:23:19 +02:00
parent 840a3e32c8
commit 3ebf54e75d
7 changed files with 187 additions and 72 deletions
Download Patch File Download Diff File Expand all files Collapse all files

26
node/README.md
View File

@@ -19,25 +19,35 @@ claude-mailbox install-autostart # registers per-OS autostart, no admin needed
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)
## Claude Code hooks (auto-check inbox)
Register a `UserPromptSubmit` hook so Claude pulls pending mailbox messages before every prompt:
Register the full plugin-equivalent hook set so Claude pulls pending mailbox messages at every natural sync point:
```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
claude-mailbox install-hook # patches ~/.claude/settings.json
claude-mailbox install-hook --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.
This installs five hooks:
Under the hood the hook runs `claude-mailbox check --name <mailbox> --hook`, which:
| 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 prompt (~100ms on Windows).
Cost: one local HTTP round-trip plus Node coldstart per fire (~100ms on Windows).
## Push delivery (watch)