When Claude rate-limits, automatically switch to Gemini. When that fails, run your own script.

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.

crew provides three distinct modes for AI agent orchestration:

brew tap garnetlyx/crew
brew install crew

To uninstall:

brew uninstall crew
brew untap garnetlyx/crew

git clone https://github.com/garnetlyx/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"

To uninstall:

cd ~/dev/crew
./uninstall.sh

Requires:

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

Supported platforms:

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

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.

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 design-review loop
design review

# Check status
design status

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

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

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

Run structured, evidence-first execution ledgers. Perfect for massive document reviews, large-scale code refactors, or security audits where "done" must be proven line-by-line.

# Initialize an Audit Mode workspace
crew init audit

# 1. Provide an inventory file (e.g. .crew/state/audit-results.json)
# 2. Start the audit orchestrator
crew start

# View the real-time Ledger Dashboard
crew monitor

Unlike parallel Dev agents, Audit agents claim predefined tasks (rows) from a JSON ledger. Row-specific failures invoke backoff mechanics only for that row, isolating faults from the agent's lifecycle. The workflow automatically completes and shuts down agents cleanly once the ledger queue hits zero.

Audit Mode workflows are powered by a JSON inventory file located at .crew/state/audit-results.json (or configured via crew.yaml). This file dictates everything the workers will do. A basic row looks like this:

[
  {
    "id": "file_1.txt",
    "status": "pending",
    "context": "Migrate specific function signature."
  }
]

Agents will loop, claiming any row in pending or backoff (if the timeout expired), executing their prompts, and releasing the row as either audited, reviewed, skipped, or failed.

Audit mode treats the JSON ledger as a transactional database. You can rewind history manually:

• The system takes automatic snapshots governed by checkpoint_every in crew.yaml (default: 10 rows).
• Resume: Stop the orchestrator (crew stop), change logic or prompts, and crew start. It gracefully resumes from the pending rows in the ledger.
• Rollback: Look inside .crew/state/checkpoints/ for historical JSON backups. To revert the workflow, simply copy the backup over .crew/state/audit-results.json and run crew start.

Audit mode utilizes a strict completion gate:

• Successful Completion: The queue hits zero, and all rows reside in a final state (reviewed or skipped). The system renders an audit report and shuts down cleanly.
• Deadlock / Starvation: The queue hits zero, but rows linger in terminal failed states. The Watchdog detects that no valid work remains. It outputs a DEADLOCK warning, prints the report, and halts the execution, allowing you to explicitly fix the stubborn rows.

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

Edit .crew/crew.yaml:

project: my-project
check_interval: 30

agents:
  - name: QA
    icon: 🔴
    type: claude
    prompt: prompts/qa.txt
    interval: 10
    timeout: 600

  - name: DEV
    icon: 🔵
    type: claude
    prompt: prompts/dev.txt

  - name: JANITOR
    icon: 🟢
    type: claude
    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.

If you prefer JSON over YAML, create .crew/crew.json instead. The JSON format uses python3 (built-in json module, no pip install needed) and supports the same fields:

{
  "project": "my-project",
  "check_interval": 30,
  "agents": [
    {
      "name": "QA",
      "type": "claude",
      "prompt": "prompts/qa.md",
      "interval": 10,
      "timeout": 600
    }
  ]
}

YAML takes priority when both .crew/crew.yaml and .crew/crew.json exist. JSON config requires python3 to be available.

Get started quickly with preset configurations:

# List available templates
crew init --list-templates

# Initialize with a template
crew init --template code-review

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

crew uses a plugin system for CLI abstraction. Each supported CLI has a plugin that handles prompt delivery and execution.

List installed plugins:

crew plugins

Create a .sh file in .crew/cli.d/ (project-local) or ~/.crew/cli.d/ (global):

#!/bin/bash
# .crew/cli.d/myagent.sh

cli_myagent_check() {
  command_exists myagent
}

cli_myagent_run() {
  local prompt_file="$1"
  local working_dir="$2"
  (cd "$working_dir" && myagent --auto < "$prompt_file")
}

cli_myagent_run_prompt() {
  local prompt="$1"
  local working_dir="$2"
  (cd "$working_dir" && echo "$prompt" | myagent --auto)
}

Then use type: myagent in crew.yaml.

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

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

IMPORTANT: Codex CLI v0.105.0+ dropped wire_api = "chat" support, which is required by most third-party OpenAI-compatible providers. Use the built-in codex_legacy plugin (Codex v0.80.0) when working with non-OpenAI models.

Install both the latest codex and the legacy version side-by-side:

# Install latest codex (global default)
npm install -g @openai/codex@latest

# Install v0.80.0 to a separate prefix
npm install -g @openai/codex@0.80.0 --prefix ~/.codex-legacy
mkdir -p ~/.local/bin
ln -sf ~/.codex-legacy/bin/codex ~/.local/bin/codex-legacy

Verify both versions:

codex --version         # latest (e.g. 0.111.0)
codex-legacy --version  # 0.80.0

Both plugins support the same CODEX_* environment variables:

agents:
  - name: DEV
    type: codex              # latest codex for OpenAI models
    prompt: prompts/dev.md
    env:
      OPENAI_API_KEY: ${OPENAI_API_KEY}
    fallback:
      - label: dashscope
        type: codex_legacy   # v0.80.0 with wire_api=chat
        env:
          CODEX_MODEL: qwen3.5-plus
          CODEX_PROVIDER: dashscope
          CODEX_BASE_URL: https://coding.dashscope.aliyuncs.com/v1
          OPENAI_API_KEY: ${QWC_API_KEY}
      - label: minimax
        type: codex_legacy
        env:
          CODEX_MODEL: MiniMax-M2.5
          CODEX_PROVIDER: minimax
          CODEX_BASE_URL: https://api.minimaxi.com/v1
          OPENAI_API_KEY: ${MINIMAX_API_KEY}

agents:
  - name: DEV
    type: codex_legacy
    prompt: prompts/dev.md
    env:
      CODEX_MODEL: qwen3.5-plus
      CODEX_PROVIDER: dashscope
      CODEX_BASE_URL: https://coding.dashscope.aliyuncs.com/v1
      CODEX_WIRE_API: chat
      OPENAI_API_KEY: ${QWC_API_KEY}
    fallback:
      - label: minimax
        type: codex_legacy
        env:
          CODEX_MODEL: MiniMax-M2.5
          CODEX_PROVIDER: minimax
          CODEX_BASE_URL: https://api.minimaxi.com/v1
          CODEX_WIRE_API: chat
          OPENAI_API_KEY: ${MINIMAX_API_KEY}

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

Set API keys in .crew/.env (git-ignored) or your shell environment:

export ANTHROPIC_API_KEY="sk-..."
export OPENAI_API_KEY="sk-..."

Multiple projects can share configuration files. crew searches in the following order, with local settings taking the highest priority:

The first config file found is used (no merging):

1. Local: .crew/crew.yaml in the current directory
2. Parent: .crew/crew.yaml in any parent directory (recursive)
3. Global: ~/.crew/crew.yaml

This means you can put a shared crew.yaml in ~/dev/.crew/crew.yaml and all projects under ~/dev/ will inherit it, unless they have their own .crew/crew.yaml.

.env files are merged (all levels stack):

1. Global: ~/.crew/.env
2. Parent: .crew/.env or .design/.env in any parent directory (recursive)
3. Local: .crew/.env or .design/.env in the current project

Values are merged, with local project settings taking the highest priority.

When an agent fails repeatedly (reaching max_restarts), it automatically falls back to the next level in its fallback chain. Each level can change the CLI type, env vars, or both.

flowchart LR
    A[Primary] -->|Fails max_restarts| B[Fallback 1]
    B -->|Fails| C[Fallback 2]
    C -->|Fails| D[Exhausted / Stop]
    A -.->|Success| A
    B -.->|Success| B
    C -.->|Success| C

• Each level retries up to its max_restarts (default: 5) with exponential backoff
• On success, the agent stays at that level (does not revert to primary)
• After all levels are exhausted, the agent stops (.crew/run/<name>.exhausted)
• Fallback-level env vars are merged on top of agent-level env — only override what changes
• Use crew restart AGENT to reset the fallback chain and start from primary
• crew status shows the current active fallback level

Stay on the same CLI tool but step down through cheaper models or providers:

# opus (best) → sonnet (balanced) → 3rd party (cheapest)
- name: QA
  type: claude
  max_restarts: 5
  env:
    ANTHROPIC_MODEL: claude-opus-4-20250514
    ANTHROPIC_API_KEY: ${ANT_API_KEY}
  fallback:
    - label: sonnet-fallback
      type: claude
      max_restarts: 3
      env:
        ANTHROPIC_MODEL: claude-sonnet-4-20250514  # API key inherited
    - label: openrouter-fallback
      type: claude
      max_restarts: 3
      env:
        ANTHROPIC_BASE_URL: ${OPENROUTER_ANT_URL}
        ANTHROPIC_MODEL: ${OPENROUTER_ANT_MODEL}
        ANTHROPIC_API_KEY: ${OPENROUTER_ANT_KEY}

Cascade through entirely different CLI tools for maximum resilience:

# claude → codex → gemini → local LLM (self-hosted, no API cost)
- name: DEV
  type: claude
  max_restarts: 5
  env:
    ANTHROPIC_API_KEY: ${ANT_API_KEY}
  fallback:
    - label: codex-openai
      type: codex
      max_restarts: 3
      env:
        OPENAI_API_KEY: ${OPENAI_API_KEY}
    - label: gemini-google
      type: gemini
      max_restarts: 3
    - label: local-llm
      type: codex
      max_restarts: 3
      env:
        CODEX_MODEL: ${LOCAL_OAI_MODEL}
        CODEX_PROVIDER: local
        CODEX_BASE_URL: ${LOCAL_OAI_URL}
        CODEX_WIRE_API: chat
        OPENAI_API_KEY: ${LOCAL_OAI_KEY}

When all AI tools fail, run a custom shell script as last resort — send notifications, trigger CI/CD, or run non-AI automation:

# claude → opencode → notify team via script
- name: JANITOR
  type: claude
  max_restarts: 5
  fallback:
    - label: opencode-backup
      type: opencode
      max_restarts: 3
    - label: notify-team
      command: ./scripts/notify.sh  # sends SMS/Slack/PagerDuty alert
      max_restarts: 1

See templates/crew.yaml.example for a complete annotated configuration.

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

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

If you already have crew set up on another project:

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

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)

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

The command field is now optional. Use the type field instead:

Before:

command: claude --dangerously-skip-permissions

After:

type: claude

The command field still works for backward compatibility and custom CLIs.

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

Requires bats-core:

# macOS
brew install bats-core

# Linux (apt)
sudo apt-get install bats

Run tests:

# All unit tests
bats tests/unit/

# Specific test file
bats tests/unit/test_utils.bats

# Integration tests
bats tests/integration/

MIT