# @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)

**v0.10.0** adds:
- `webhook` subcommand — register/unregister/list webhooks for collab events
- `multi-target poll` — poll multiple `to_user` targets in one command
- `dispatch fix` — deterministic route resolution for multi-bot sessions
- `collab-send --to-user --ack-after` — explicit target + auto-ack

---

## 1. Quick Start (30 seconds)

```bash
# 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`](docs/cli-reference.md) for the full reference.

### Quick examples

```bash
# 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`](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:

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

Then:

```bash
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

```bash
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`](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`](docs/migration.md).

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

```bash
# 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

```js
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

```bash
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](LICENSE).

## Maintainers

oxiaom <244255055@qq.com>