Getting Started with crew-opencode

This guide will help you install and start using crew-opencode for multi-agent orchestration.

Prerequisites
Installation
Configuration
Your First Workflow
Understanding SOPs
Working with Agents
Advanced Usage
Troubleshooting

Prerequisites

Before you begin, ensure you have:

API Keys for your chosen LLM providers:
- Anthropic API - For Claude models (PM, TA, QA)
- OpenAI API - For GPT models (Design)
- Google AI - For Gemini models (FE)
Runtime (only for npm installation):
- Node.js >= 18.0 or Bun >= 1.0
- Standalone binaries don't require a runtime
Optional: OpenCode CLI for plugin integration

Installation

Option 1: Standalone Binary (Recommended)

Download the binary for your platform and add it to your PATH:

macOS (Apple Silicon - M1/M2/M3)

curl -L https://github.com/sehyun0518/crew-opencode/releases/download/v1.0.0/crew-opencode-macos-arm64 -o crew-opencode
chmod +x crew-opencode
sudo mv crew-opencode /usr/local/bin/

macOS (Intel)

curl -L https://github.com/sehyun0518/crew-opencode/releases/download/v1.0.0/crew-opencode-macos -o crew-opencode
chmod +x crew-opencode
sudo mv crew-opencode /usr/local/bin/

Linux (x64)

curl -L https://github.com/sehyun0518/crew-opencode/releases/download/v1.0.0/crew-opencode-linux-x64 -o crew-opencode
chmod +x crew-opencode
sudo mv crew-opencode /usr/local/bin/

Windows (x64)

Download crew-opencode-windows-x64.exe
Add the directory to your PATH or run directly

Verify Installation

crew-opencode --version
# Should output: 1.0.0

Option 2: npm (GitHub Packages)

# Configure npm to use GitHub Packages
echo "@sehyun0518:registry=https://npm.pkg.github.com" >> ~/.npmrc

# Install globally
npm install -g @sehyun0518/crew-opencode

# Verify installation
crew-opencode --version

Option 3: Bun

bunx @sehyun0518/crew-opencode install

Configuration

Step 1: Set API Keys

Set your API keys as environment variables:

# Add to ~/.bashrc, ~/.zshrc, or ~/.profile
export ANTHROPIC_API_KEY="your-anthropic-key-here"
export OPENAI_API_KEY="your-openai-key-here"
export GOOGLE_API_KEY="your-google-key-here"

Don't have all API keys? You can disable agents you don't need (see Configuration File below).

Step 2: Initialize Configuration (Optional)

crew-opencode works with default configuration, but you can customize it:

Global Configuration (applies to all projects):

mkdir -p ~/.opencode/crew-opencode

Create ~/.opencode/crew-opencode/config.json:

{
  "version": "1.0.0",
  "crew": {
    "pm": {
      "enabled": true,
      "model": "claude-opus-4-5",
      "apiKey": "${ANTHROPIC_API_KEY}"
    },
    "ta": {
      "enabled": true,
      "model": "claude-sonnet-4.5",
      "apiKey": "${ANTHROPIC_API_KEY}"
    },
    "fe": {
      "enabled": true,
      "model": "gemini-3-pro",
      "apiKey": "${GOOGLE_API_KEY}"
    },
    "design": {
      "enabled": false,
      "model": "gpt-5.2-medium",
      "apiKey": "${OPENAI_API_KEY}"
    },
    "qa": {
      "enabled": true,
      "model": "claude-haiku-4.5",
      "apiKey": "${ANTHROPIC_API_KEY}"
    }
  },
  "sop": {
    "feature": { "enabled": true },
    "bugfix": { "enabled": true },
    "refactor": { "enabled": true }
  },
  "incidentReport": {
    "enabled": true,
    "outputDir": ".opencode/crew-opencode/incidents"
  }
}

Local Configuration (project-specific):

mkdir -p .opencode/crew-opencode
cp ~/.opencode/crew-opencode/config.json .opencode/crew-opencode/

Step 3: Verify Configuration

crew-opencode doctor

This will check:

✓ OpenCode directory exists
✓ Configuration is valid
✓ API keys are set
✓ Agents are configured
✓ SOPs are available

Your First Workflow

Example 1: Simple Feature Implementation

crew-opencode crew "Add a user login form with email and password fields"

This will:

PM analyzes the request and creates a plan
TA researches best practices for login forms
Design reviews UX patterns (if enabled)
FE implements the login form component
QA writes and runs tests

Expected Output:

🚀 Starting workflow: feature
📋 Total steps: 5

[1/5] PM - Planning
  ⚙ Analyzing request...
  ✓ Plan created

[2/5] TA - Research
  ⚙ Researching login form patterns...
  ✓ Technical specs ready

[3/5] FE - Implementation
  ⚙ Creating login component...
  ✓ Component implemented

[4/5] QA - Testing
  ⚙ Writing tests...
  ✓ Tests passing

[5/5] PM - Final Review
  ✓ Workflow complete!

📊 Summary:
  Duration: 8m 32s
  Tasks: 5 completed
  Status: Success

Example 2: Bug Fix

crew-opencode crew "Fix the crash when clicking the logout button" --sop bugfix

This will:

PM prioritizes the bug
TA analyzes root cause
FE implements minimal fix
QA verifies fix doesn't break anything

Example 3: Refactoring

crew-opencode crew "Refactor the authentication module to use hooks instead of class components" --sop refactor

This will:

PM creates refactoring strategy
TA analyzes dependencies
FE performs refactoring
QA ensures all tests still pass

Understanding SOPs

SOPs (Standard Operating Procedures) define how the crew tackles different types of tasks.

Available SOPs

1. Feature Development (feature)

Duration: 60-90 minutes
Steps: 6
Agents: PM → TA → Design → FE → QA → PM
Best for: New features, enhancements

2. Bug Fix (bugfix)

Duration: 40-70 minutes
Steps: 5
Agents: PM → TA → FE → QA → PM
Best for: Fixing bugs, small corrections

3. Refactoring (refactor)

Duration: 100-160 minutes
Steps: 6
Agents: PM → TA → FE → QA → PM
Best for: Code improvements, restructuring

Selecting an SOP

# Default: feature SOP
crew-opencode crew "Add dark mode"

# Explicit SOP selection
crew-opencode crew "Fix memory leak" --sop bugfix
crew-opencode crew "Convert to TypeScript" --sop refactor

Working with Agents

The Crew

Your crew consists of 5 specialized agents:

Agent	Role	Model	Cost	Specialty
PM	Project Manager	Claude Opus 4.5	💰💰💰	Strategy, orchestration
TA	Technical Analyst	Claude Sonnet 4.5	💰💰	Research, architecture
FE	UI/UX Engineer	Gemini 3 Pro	💰💰	Implementation
Design	Designer	GPT 5.2 Medium	💰💰	UX/UI patterns
QA	Quality Assurance	Claude Haiku 4.5	💰	Testing, verification

Viewing Available Agents

crew-opencode list

Disabling Agents

To reduce costs, you can disable agents you don't need:

Edit your config file:

{
  "crew": {
    "design": {
      "enabled": false  // Disable Design agent
    }
  }
}

Common configurations:

Minimal (PM + TA + FE + QA): Best balance of quality and cost
Full (All 5 agents): Maximum quality, higher cost
Budget (PM + FE + QA): Lower cost, still functional

Advanced Usage

Dry Run Mode

Preview what the crew will do without executing:

crew-opencode crew "Add user profiles" --dry-run

Custom Project Path

Run crew-opencode in a different directory:

crew-opencode crew "Update homepage" --project /path/to/project

Viewing Workflow Status

Check the status of a running workflow:

crew-opencode status <workflow-id>

Incident Reports

When tasks fail, crew-opencode generates "Apology Letters" with:

Root cause analysis
Risk assessment
Prevention strategy

View recent incidents:

crew-opencode reports

View specific incident:

crew-opencode reports --id <incident-id>

Configuration Management

View current configuration:

crew-opencode config

Get specific value:

crew-opencode config crew.pm.model

Set configuration value:

crew-opencode config crew.pm.enabled true

Troubleshooting

Issue: "401 Unauthorized" or "API key not found"

Solution: Verify your API keys are set:

echo $ANTHROPIC_API_KEY
echo $OPENAI_API_KEY
echo $GOOGLE_API_KEY

If empty, add them to your shell profile and restart your terminal.

Issue: "Agent not found" or "SOP not found"

Solution: Run the install command to set up agents and SOPs:

crew-opencode install --global

Issue: Workflow takes too long

Solution: Disable unnecessary agents or use simpler SOPs:

Use bugfix SOP for smaller changes
Disable Design agent if not needed
Check if tasks can be broken into smaller chunks

Issue: "Rate limit exceeded"

Solution:

Wait a few minutes and retry
Upgrade your API plan for higher limits
Reduce parallel agent execution

Issue: Tests failing after implementation

Solution: Review the incident report:

crew-opencode reports

The QA agent will have documented:

What went wrong
Why it failed
How to prevent it

Getting Help

Check system status:

crew-opencode doctor

View logs:

ls -la .opencode/crew-opencode/workflows/

Report issues:

GitHub Issues: https://github.com/sehyun0518/crew-opencode/issues
Documentation: https://github.com/sehyun0518/crew-opencode#readme

Next Steps

Now that you're set up:

Try the examples above to get familiar with the crew
Customize your configuration for your workflow
Read the Configuration Guide for advanced options
Review Example Workflows for inspiration
Join the community to share your experience

Cost Estimation

Typical costs per workflow (approximate):

Feature (60-90min): $0.50 - $2.00
Bug Fix (40-70min): $0.30 - $1.00
Refactor (100-160min): $1.00 - $3.00

Cost varies based on:

Complexity of the task
Which agents are enabled
Your API plan rates
Amount of context needed

Cost-saving tips:

Disable Design agent for backend tasks
Use bugfix SOP for simple changes
Break large tasks into smaller workflows
Keep context windows small

Need more help? Check out the full documentation or join discussions.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Getting Started with crew-opencode

Table of Contents

Prerequisites

Installation

Option 1: Standalone Binary (Recommended)

Option 2: npm (GitHub Packages)

Option 3: Bun

Configuration

Step 1: Set API Keys

Step 2: Initialize Configuration (Optional)

Step 3: Verify Configuration

Your First Workflow

Example 1: Simple Feature Implementation

Example 2: Bug Fix

Example 3: Refactoring

Understanding SOPs

Available SOPs

Selecting an SOP

Working with Agents

The Crew

Viewing Available Agents

Disabling Agents

Advanced Usage

Dry Run Mode

Custom Project Path

Viewing Workflow Status

Incident Reports

Configuration Management

Troubleshooting

Issue: "401 Unauthorized" or "API key not found"

Issue: "Agent not found" or "SOP not found"

Issue: Workflow takes too long

Issue: "Rate limit exceeded"

Issue: Tests failing after implementation

Getting Help

Next Steps

Cost Estimation

FilesExpand file tree

getting-started.md

Latest commit

History

getting-started.md

File metadata and controls

Getting Started with crew-opencode

Table of Contents

Prerequisites

Installation

Option 1: Standalone Binary (Recommended)

Option 2: npm (GitHub Packages)

Option 3: Bun

Configuration

Step 1: Set API Keys

Step 2: Initialize Configuration (Optional)

Step 3: Verify Configuration

Your First Workflow

Example 1: Simple Feature Implementation

Example 2: Bug Fix

Example 3: Refactoring

Understanding SOPs

Available SOPs

Selecting an SOP

Working with Agents

The Crew

Viewing Available Agents

Disabling Agents

Advanced Usage

Dry Run Mode

Custom Project Path

Viewing Workflow Status

Incident Reports

Configuration Management

Troubleshooting

Issue: "401 Unauthorized" or "API key not found"

Issue: "Agent not found" or "SOP not found"

Issue: Workflow takes too long

Issue: "Rate limit exceeded"

Issue: Tests failing after implementation

Getting Help

Next Steps

Cost Estimation