crew

Adversarial Multi-Agent Orchestration Tool for AI-assisted development

WARNING: This tool launches AI agents that run with full access to your codebase and system. Agents can read, create, modify, and delete files autonomously. By default, agents run with --dangerously-skip-permissions, which bypasses all safety prompts. Review your agent prompts and configuration before running crew start. See SECURITY.md for details.

Overview

crew provides two distinct modes for AI agent orchestration:

Command	Mode	Use Case
design	Cross-Review	Refine ideas into polished design docs
crew	Parallel Agents	Run multiple AI agents for debugging/optimization

Installation

git clone https://github.com/YOUR_USERNAME/crew ~/dev/crew
cd ~/dev/crew
./install.sh

This creates symlinks in ~/.local/bin. If not already in PATH, add to your shell config:

export PATH="$HOME/.local/bin:$PATH"

Requires:

• Bash 4+
• yq for YAML parsing: brew install yq
• An AI CLI: claude, opencode, or gemini

Supported platforms:

• macOS (primary, actively developed)
• Linux (tested)
• Windows WSL (untested, should work)

First-time Setup Security Checklist

Before running crew start, verify the following:

• Git clean state — commit or stash all work; agents will modify files
• Review prompts — read every file in .crew/prompts/ before agents use them
• Review crew.yaml — confirm each agent's command and env fields look correct
• No secrets in config — API keys go in shell env (export ANTHROPIC_API_KEY=...), never in crew.yaml
• .gitignore covers runtime files — .crew/logs/, .crew/run/ should be ignored
• Understand --dangerously-skip-permissions — agents bypass all safety prompts and can read/write/delete any file

Tip: Run crew validate to check config syntax before starting agents.

design - Cross-Review Mode

Turn ideas into refined design documents through automated Writer ⇄ Reviewer loops.

# Initialize with your idea
design init "A CLI tool for managing container deployments"

# Start cross-review loop
design review

# Check status
design status

How it works

┌──────────────┐    trigger     ┌──────────────┐
│ Plan Writer  │ ──────────────→│   Reviewer   │
│    Agent     │                │    Agent     │
└──────────────┘                └──────────────┘
       ↑                               │
       │ trigger (if !pass)            │ pass?
       └───────────────────────────────┘

Termination Conditions

• pass: Reviewer approves the plan
• stale: Plan unchanged for 2 iterations
• conflict: Same issues repeat 3+ times

Files

.design/
├── design.yaml     # Config
├── idea.txt        # Your initial idea
├── plan.md         # Current plan
├── review.md       # Current review
└── history/        # All iterations

crew - Parallel Agents Mode

Run multiple AI agents in parallel for continuous codebase improvement.

# Initialize in your project
crew init

# Start all agents
crew start

# Start specific agents
crew start QA DEV JANITOR

# Monitor real-time
crew monitor

# View logs
crew logs QA

> **Tip**: For long-running tasks (like full test suites), log output may appear "stuck" due to buffering. The log will update in a large chunk once the command completes.

# Stop all
crew stop

Configuration

Edit .crew/crew.yaml:

project: my-project
check_interval: 30

agents:
  - name: QA
    icon: 🔴
    command: claude --dangerously-skip-permissions
    prompt: prompts/qa.txt
    interval: 10
    timeout: 600

  - name: DEV
    icon: 🔵
    command: claude --dangerously-skip-permissions
    prompt: prompts/dev.txt

  - name: JANITOR
    icon: 🟢
    command: claude --dangerously-skip-permissions
    prompt: prompts/janitor.txt
    interval: 10
    timeout: 600

> **Note**: Changes to `crew.yaml` (including `interval` and `env` variables) require a restart of the affected agents to take effect. Run `crew restart [AGENT]` to apply changes.

Files

.crew/
├── crew.yaml       # Config
├── prompts/        # Agent prompts
├── logs/           # Agent logs
└── run/            # PID files

3rd Party / Self-Hosted Models

Use the env field in .crew/crew.yaml to configure per-agent environment variables for different providers:

agents:
  - name: DEV
    command: claude --dangerously-skip-permissions
    prompt: prompts/dev.md
    env:
      ANTHROPIC_BASE_URL: https://openrouter.ai/api/v1
      ANTHROPIC_MODEL: anthropic/claude-sonnet-4-20250514

Common Providers

Provider	ANTHROPIC_BASE_URL
Anthropic (default)	https://api.anthropic.com
OpenRouter	https://openrouter.ai/api/v1
Self-hosted	http://localhost:8080/v1

API Key Handling

WARNING: Never put API keys in crew.yaml if it's committed to git.

Set ANTHROPIC_API_KEY in your shell environment instead:

export ANTHROPIC_API_KEY="sk-..."

Environment Variables

Variable	Description
CREW_AGENT	Override default agent type (claude, opencode, gemini)
ANTHROPIC_BASE_URL	Override API endpoint for Claude CLI
ANTHROPIC_MODEL	Override model for Claude CLI
ANTHROPIC_API_KEY	API key for Claude CLI (set in shell, not config)
DEBUG	Set to 1 for verbose output

Examples

Design a new feature

cd ~/dev/my-app
design init "Add real-time collaboration with WebSockets"
design review --max-iter 3
# Result: .design/plan.md with refined design

Run parallel debugging agents

cd ~/dev/my-app
crew init
# Edit .crew/crew.yaml and prompts
crew start QA DEV JANITOR
crew monitor
# Agents run continuously, finding and fixing issues
crew stop

Upgrading

If you already have crew set up on another project:

1. Update crew itself

cd ~/dev/crew    # or wherever you cloned crew
git pull
./install.sh     # re-creates symlinks, safe to re-run

2. Clean up old runtime files

In each project that uses crew:

crew stop                        # stop any running agents
rm -rf .crew/run/                # remove old PID files
rm -rf .crew/logs/               # remove old logs (optional)

3. Update .crew/crew.yaml

Breaking change: Commands with pipes or shell operators (e.g. cmd1 | cmd2) no longer work in the command field. Use a wrapper script instead.

Before:

command: ANTHROPIC_MODEL=my-model claude --dangerously-skip-permissions

After:

command: claude --dangerously-skip-permissions
env:
  ANTHROPIC_MODEL: my-model

4. Verify

crew validate    # check config syntax
crew start       # test agents start correctly
crew status      # confirm all running
crew stop        # clean shutdown

License

MIT