@trustbaseai/claude-collab-plugin

Claude Code 集成层 for @trustbaseai/claude-collab

Wires collab-mcp into Claude Code via ~/.claude/settings.json hooks (PostToolUse, SessionStart, UserPromptSubmit), runs an active new-message fetcher watch daemon that auto-wakes a claude --print sub-session when baobei (or whoever) sends you a message, persists plugin config, and exposes a 15-subcommand CLI for setup, diagnostics, and on-demand wake.

Sits on top of the base client — does not replace it.

Install

npm install -g @trustbaseai/claude-collab @trustbaseai/claude-collab-plugin

# Register the 3 hooks in ~/.claude/settings.json
claude-collab-plugin install

# Optional: persist your watch preferences (read by `watch` if no flags)
claude-collab-plugin config set interval 30
claude-collab-plugin config set autoWake true
claude-collab-plugin config set toast true

# Start the watch daemon (no flags → uses saved config)
claude-collab-plugin watch &

# Verify everything
claude-collab-plugin doctor
claude-collab-plugin status

Subcommands (v0.8.2)

| Command | Purpose | |---|---| | install | Register the 3 hooks in ~/.claude/settings.json (idempotent, --force to overwrite) | | install --force-clean | Same, but also remove any "looks like ours" hooks without our marker | | uninstall | Remove the 3 hooks | | doctor | Claude Code specific health check (5+ items) | | watch | Run the active new-message fetcher daemon (default: 60s tick) | | wake-once | Trigger one immediate poll + auto-wake cycle (don't wait for next tick) | | clear-pending | Delete the pending file (force a fresh state) | | status | Print watch daemon + hooks state (PID, interval, lastSeenId, ...) | | config | Show all saved settings | | config get <key> / set <k> <v> / unset <k> / reset / path | Persistent config (saved to ~/.claude-collab/config-watch.json) | | session | Print most recent Claude Code session state | | session --all --json | List all projects with recent activity (machine-readable) | | version | Plugin + base version | | help | Help |

What each hook does

• PostToolUse — every time a tool call completes, a tiny script (scripts/claude-posttool-hook.js) reads the tool summary, deduplicates against the last 30s, and forwards a one-line note to baobei via collab-send. Read tools / grep are filtered; meaningful writes / bash get summarized.
• SessionStart — when a new Claude Code session starts, the hook reads the pending file and emits it as additionalContext so the new session sees baobei's most recent messages without you having to ask. First-inject only (clears pending after).
• UserPromptSubmit — every time you send a message, the hook reads the pending file and emits it as additionalContext. First-inject only.

All three pass --ack-on-inject so the same messages are not re-injected on every subsequent turn.

What the watch daemon does

watch runs in the background and actively polls the collab-mcp inbox for new messages every interval seconds (default 15s, configurable via config set interval). When it finds new messages it:

1. Writes them to ~/.claude-collab/claude-pending-baobei.json
2. (Optional) Shows a Windows toast notification (--toast)
3. (Optional) Spawns claude --print --bare as a sub-session via PowerShell to read the pending messages, generate a reply, and have the parent auto-wake script send that reply via collab-send + ack the inbound ids.

This implements "baobei wakes you up" without a real Claude Code system-event API — the sub-session is a sibling process; the current main session sees the reply on its next user turn (UserPromptSubmit hook).

Saved config (~/.claude-collab/config-watch.json, set via claude-collab-plugin config):

• interval (5-3600 seconds)
• autoWake (boolean, supports --no-auto-wake to turn off)
• toast (boolean, supports --no-toast to turn off)
• pollFrom (string, default baobei)

CLI flags always win over saved config.

Architecture

+-----------------------+
| Claude Code           | hooks.PostToolUse / SessionStart / UserPromptSubmit
+-----------------------+
        |
        v
+-----------------------+
| claude-collab-plugin  | (this package, v0.8.2)
+-----------------------+
        | requires @trustbaseai/claude-collab@^0.3.0
        v
+-----------------------+
| claude-collab        | (base client, by baobei)
+-----------------------+
        |
        v
+-----------------------+
| collab-mcp :3010     |
+-----------------------+

The plugin is a peer to the base client (depends on, but does not fork it). The base client talks HTTP to collab-mcp. The plugin adds Claude Code hooks + an active watch daemon + a 15-subcommand CLI.

Why a separate package?

Single-responsibility:

• Bug fixes in the base client don't ship in this plugin, and vice-versa.
• They version independently. The plugin is at v0.8.2; the base client is at v0.3.0.
• The plugin's npm test covers the plugin's hooks/settings/session; the base client's tests cover its own RPC client. No cross-coupling.

Install both with npm install -g so the plugin can require() the base.

See also

• docs/quickstart.md — 5-line setup
• docs/install.md — detailed install flow
• docs/hooks.md — how the 3 hooks are wired
• docs/doctor.md — what each health check does
• docs/heartbeat-philosophy.md — why we don't ping other agents
• docs/vs-base.md — how this plugin differs from the base client
• docs/troubleshooting.md — common issues
• docs/migration.md — moving from the legacy collab-*.js shim scripts

License

MIT