Agent Collaboration CLI

Multi-agent collaboration prototype driven by the collaborate CLI.

Repository Layout

• .collab/: Runtime state (events.jsonl, config, generated task/review/context artifacts).
• collaborate/: CLI and orchestration source code.
• design/: Architecture docs, RFCs, and event schema reference.
• tasks/: Human-authored task definitions and templates for this workspace.
• reviews/: Review artifacts from agent turns.
• tests/: Unit and integration tests.

Quick Start

# 1) Initialize runtime state in this repo
.venv/bin/collaborate init

# 2) (Optional for real backends) export provider keys
export ANTHROPIC_API_KEY="sk-..."
export OPENAI_API_KEY="sk-..."
export GOOGLE_API_KEY="..."

# 3) Run one orchestration turn
.venv/bin/collaborate run --prompt "Your task description here"

Common Commands

# Show derived project state from .collab/events.jsonl
.venv/bin/collaborate status

# Validate event log structure/timestamps
.venv/bin/collaborate validate

# Use mock backends (no external API calls)
.venv/bin/collaborate run --prompt "Test task" --mock

Continuous Modes

# Run multiple queued tasks in sequence
.venv/bin/collaborate run --continuous --max-cycles 5 --mock

# Allow manager role to propose tasks when queue is idle
.venv/bin/collaborate run --continuous --autonomous --max-cycles 5 --mock

Note: continuous/autonomous behavior is under active iteration; check task/review status before relying on it for unattended runs.

Backends

SDK Backends

• anthropic — Claude via Anthropic SDK
• google — Gemini via Google GenAI SDK
• openai — GPT via OpenAI SDK

CLI Backends (Hybrid Phase 1)

• cli-claude — wraps claude -p (Claude Code CLI)
• cli-gemini — wraps gemini -p (Gemini CLI)
• cli-codex — wraps codex exec (Codex CLI)

CLI backends give agents full file I/O, shell access, and autonomous context management. If a CLI tool is not installed, the factory falls back to the corresponding SDK backend automatically.

Model and backend routing are configured in .collab/config.yaml.

CLI Wrapper Behavior

Current wrapper behavior in collaborate/agents/cli.py:

• cli-claude
  • Command shape: claude -p --output-format json --permission-mode bypassPermissions --append-system-prompt ...
  • Includes a role-aware system prompt suffix (implementer or reviewer).
• cli-gemini
  • Command shape: gemini -p ... --output-format json --yolo
• cli-codex
  • Command shape: codex exec --json --full-auto ...

Guardrails:

• Dirty worktree check is enabled for non-reviewer roles in git repositories.
• Reviewer role skips the dirty-worktree block so review can run after implementer edits.
• Changed files are derived from git diff HEAD --name-only (source of truth), not only model JSON output.
• CLI timeout is controlled by settings.cli_timeout (default 300s).

Fallback behavior in collaborate/agents/factory.py:

• If cli-claude is configured but claude is missing, backend falls back to anthropic.
• If cli-gemini is configured but gemini is missing, backend falls back to google.
• If cli-codex is configured but codex is missing, backend falls back to openai.

Development

# Run tests
./run_tests.sh

Troubleshooting

# 1) Verify current derived state and pending work
.venv/bin/collaborate status

# 2) Validate event log integrity
.venv/bin/collaborate validate

# 3) Run test suite after backend/config changes
./run_tests.sh

# 4) Confirm configured CLI tools are available on PATH
command -v claude gemini codex

Common failures:

• CLI tool '<name>' not found in PATH: install that CLI or switch backend in .collab/config.yaml.
• Refusing to run CLI backend on dirty git worktree: commit/stash changes or run reviewer role.
• API key errors after fallback: set ANTHROPIC_API_KEY, GOOGLE_API_KEY, or OPENAI_API_KEY as needed.