@trustbaseai/claude-collab

Claude Code ↔ collab-mcp adapter for multi-agent collaboration.

Replaces the legacy D:\myopenclaw\scripts\collab-*.js shims with a proper npm package so Claude Code can call the collab-mcp HTTP API with auth, discoverable CLI subcommands, and a self-diagnosis tool.

v0.3.0 (Phase 4) adds:

• collab-doctor — 6-layer health check with fix suggestions
• claude-collab-config init — interactive setup wizard
• collab-send --from --reply-to — explicit sender + threading
• collab-read --since-time --unacked-only --json — richer filtering
• collab-list --type --assignee --json — finer-grained
• collab-ack --ids 1,2,3 — bulk ack
• 4 docs (quickstart, cli-reference, configuration, doctor, migration, troubleshooting)

1. Quick Start (30 seconds)

# Install
npm install -g @trustbaseai/claude-collab

# Configure (interactive)
claude-collab-config init

# Verify health
collab-doctor

# Send your first message
collab-send baobei 'hello from claude-collab'

That's it. collab-doctor will tell you exactly what's broken if anything is.

2. Architecture

+-----------------+      HTTP REST       +------------------+
|   Claude Code   |  --X-API-Key ----->  |   collab-mcp     |
|  (claude-collab)|  <----------------   |   (localhost:3010)|
+-----------------+                      +------------------+
        |                                          |
        | writes pending-{target}.json              | polls /api/pending
        v                                          v
   ./tmp/                                  unified-daemon.js
   (read by daemon)                        (for OpenClaw agent)

• CLI subcommands (6): collab-send, collab-read, collab-ack, collab-list, collab-doctor, claude-collab-config
• Programmatic API: require('@trustbaseai/claude-collab') exposes send / read / ack / list / rpc / writePendingFile / isHeartbeat / configStore
• File hook: writePendingFile(target, msgs) drops pending-<target>.json for the unified-daemon to poll
• Heartbeat detection: isHeartbeat(content) filters routine keepalive messages

3. CLI Reference

See docs/cli-reference.md for the full reference.

Quick examples

# Send
collab-send baobei 'task done' --category=task
collab-send baobei 'ack #185' --reply-to=185

# Read
collab-read all --limit=10
collab-read baobei 100 --unacked-only --json
collab-read claude --since-time=09:00

# Ack
collab-ack 185
collab-ack --ids 185,186,187

# List pending
collab-list todos --assignee=baobei
collab-list --type=reviews --json

# Doctor
collab-doctor

# Config
claude-collab-config init
claude-collab-config set api_key cmcp_xxx.<secret>
claude-collab-config set session_key agent:main:dashboard:<uuid>
claude-collab-config list
claude-collab-config path

Every binary supports --help.

4. Configuration

See docs/configuration.md for full field reference.

Config lives in ~/.claude-collab/config.json.

| Field | Default | Purpose | |---|---|---| | mcp_url | http://127.0.0.1:3010 | collab-mcp HTTP base | | api_key | null | plaintext cmcp_xxx.<secret> | | api_key_file | null | alternative: file path holding key | | from_user | claude-code | sender identity | | to_user | baobei | default recipient | | session_key | null | OpenClaw agent id for wakeup association | | poll_interval_ms | 5000 | reserved | | pending_dir | D:/myopenclaw/.tmp | state file drop dir |

Get an api_key

On the host running collab-mcp:

collab-mcp keys create claude-collab --scopes=read,write
# plaintext shown ONCE: cmcp_xxx.<secret>

Then:

claude-collab-config set api_key cmcp_xxx.<secret>
# or
claude-collab-config init

Security

• config.json contains plaintext secret → chmod 600 (auto-applied on POSIX)
• Add to .gitignore if copying outside ~/.claude-collab/
• For higher security: api_key_file points at a path only your user can read

5. Doctor / Troubleshooting

Self-diagnosis

collab-doctor

6 layers checked: config validity, mcp_url reachable, api_key accepted, pending_dir writable, Node.js version, server version.

Common issues

See docs/troubleshooting.md.

401 unauthorized → key missing or revoked. collab-doctor tells you which. Timeout → mcp_url unreachable. Test curl http://127.0.0.1:3010/health. MODULE_NOT_FOUND on require → use bin instead, or set NODE_PATH=$(npm root -g).

6. Migration from Legacy Scripts

See docs/migration.md.

Pre-v0.3.0 used D:\myopenclaw\scripts\collab-*.js. The npm package provides drop-in equivalents plus auth + discovery.

# Install + configure
npm install -g @trustbaseai/claude-collab
claude-collab-config init
collab-doctor

# Replace in PostToolUse hook, cron, etc.
# before: node D:/myopenclaw/scripts/collab-send.js baobei "..."
# after:  collab-send baobei "..."

7. Programmatic API

const { send, read, ack, list, rpc, writePendingFile, isHeartbeat, configStore } =
  require('@trustbaseai/claude-collab');

// Send a message
const r = await send('baobei', 'hello', 'info');
// → { message_id: 192, ok: true }

// Read messages
const r = await read('claude', 100, 10);
// → { messages: [...] }

// Bulk ack
await rpc('ack_message', { ids: [185, 186, 187] });

// List pending todos
await list('todos', 'baobei');

// File hook (for OpenClaw unified-daemon)
writePendingFile('baobei', [{ id: 185, content: '...' }]);
// → writes ./tmp/pending-baobei.json

// Heartbeat detection
isHeartbeat('💓 keepalive');  // → true
isHeartbeat('task done');    // → false

8. Development

git clone https://github.com/trustbaseai/claude-collab
cd claude-collab
npm install

# Run doctor against local collab-mcp
npm run doctor

# Verify all .js files parse
npm run check

# Build dist/ for publishing
npm run build

# Dry-run publish (verify tarball)
npm run publish:dryrun

# Real publish (requires npm login)
npm run publish:public

File layout

src/
  cli.js              # HTTP client + method table
  config-store.js     # ~/.claude-collab/config.json
  file-hook.js        # writePendingFile()
  heartbeat.js        # isHeartbeat()
  index.js            # require facade
bin/
  collab-send.js      # collab-send
  collab-read.js      # collab-read
  collab-ack.js       # collab-ack
  collab-list.js      # collab-list
  collab-doctor.js    # collab-doctor (v0.3.0)
  claude-collab-config.js
  claude-collab-config-init.js  # v0.3.0 wizard
scripts/
  prepare-publish.js  # builds dist/ from src/
docs/
  quickstart.md
  cli-reference.md
  configuration.md
  doctor.md
  migration.md
  troubleshooting.md

License

MIT — see LICENSE.

Maintainers

oxiaom [email protected]