collab

collab — Coding Agent ↔ Persona Agent collaboration

A Claude Code plugin that lets a coding agent collaborate with you — even when you're not there. When the coding agent hits a question it would normally stop and ask you, a second Claude Code process answers on your behalf, grounded in a SOUL.md that captures your experience, preferences, goals, and decision principles. You watch the two agents work through a task hands-off, and step in only when you want to.

The stand-in's value is knowledge of you (taste, priorities, constraints, prior decisions) — the thing the asking agent can't derive on its own — enhanced by the model's own expertise. In short: you, made consistent and decisive, then sharpened by expert depth.

How it works

Two interactive Claude Code processes, each with this plugin enabled, communicate through a shared SQLite message bus:

  ┌─────────────────┐        SQLite store         ┌──────────────────┐
  │  Coding Agent   │  ── question ──▶  collab.db  ── question ──▶    │  Persona Agent   │
  │  (does the work)│  ◀── answer ───            ◀── answer ───      │  (answers as you │
  │                 │                                                 │   via SOUL.md)   │
  └─────────────────┘                                                 └──────────────────┘
       /collab:coding-watch                                      /collab:persona-watch

• Each agent runs a watch command on a recurring /loop, polling its inbox each tick.
• The Coding Agent, when blocked, sends a self-contained question instead of stopping; the Persona Agent auto-answers every question, grounded in SOUL.md.
• When the task is complete the Coding Agent sends done and both loops stop.
• You can course-correct at any time by typing prose into the Persona (it's relayed to the Coding Agent), and stop either side with /collab:stop.

See docs/running-a-collaboration.md for the full walkthrough, and docs/design/collaboration.md for the design rationale.

Requirements

• bun — the collab CLI is plain TypeScript on bun and uses the built-in bun:sqlite (no external dependencies).
• Claude Code — two sessions, with the /loop recurring- command capability for the watch loops. (No /loop? Re-run the watch command manually each interval instead.) The watch interval is ≥60s (/loop 1m schedules a recurring job), so a round-trip is ~1–2 min.

Install

The repo is both the plugin and a single-plugin marketplace (.claude-plugin/plugin.json

• .claude-plugin/marketplace.json), so either install path works.

Via the marketplace (recommended)

/plugin marketplace add LeonidShamis/agent-collaboration
/plugin install collab@agent-collaboration

collab is the plugin; agent-collaboration is the marketplace name. This is repeatable per machine and survives across sessions. (Non-interactive equivalents: claude plugin marketplace add …, claude plugin install collab@agent-collaboration.)

Private repo: this repo is private, so a collaborator must have repo access and git auth (an SSH key or gh login that can clone it) for /plugin marketplace add to fetch it. Invite them on GitHub first.

From a local clone (development, or no GitHub access)

git clone <this-repo> agent-collaboration
cd agent-collaboration
bun install                                   # dev/test deps only; the bundled CLI is dependency-free
claude --plugin-dir /abs/path/to/agent-collaboration

Either way, enabling the plugin puts the collab CLI on the Bash PATH and registers the commands and hooks. (The CLI is dependency-free, so a marketplace install needs no bun install — only bun on the machine.)

Configure

Environment variables (set at launch for each agent):

Variable	Purpose	Default
COLLAB_DB	Absolute path to the shared SQLite store. Both agents must use the same path.	.collab/collab.db (cwd-relative)
COLLAB_ID	Collaboration id — scopes a run. Both agents must match. Use distinct ids for concurrent collaborations.	default
COLLAB_ROLE	coding or persona — scopes the role-specific hooks (relay + read-only fire only for persona).	—

Per-agent permission allowlist. Plugins can't grant permissions, so each agent directory needs a .claude/settings.json so the unattended /loop poll doesn't prompt: