Skip to content
BranchesTags

Repository files navigation

OpenCode Agent Team

License: MIT OpenCode Compatible Version

A production-ready, plan-first agent hierarchy configuration for OpenCode CLI with 15 specialized agents (2 primary + 13 subagents) and extensible architecture.

Quick Start • Installation • Agent Reference • Workflow Guide • Contributing

Overview

OpenCode Agent Team is a professional agent configuration system that transforms OpenCode CLI into a coordinated multi-agent development environment. It implements a proven plan-first workflow where strategic planning precedes implementation, enabling efficient parallel execution of specialized agents.

This configuration is designed for teams and individual developers who want to leverage AI-assisted development with clear separation of concerns, bounded execution, and fine-grained permission controls.

Key Features

  • Plan-First Workflow - Strategic analysis before implementation prevents costly mistakes
  • 15 Specialized Agents - 2 primary agents (plan, build) + 13 subagents, each optimized for specific development tasks with appropriate models and permissions
  • Parallel Execution - Independent tasks run simultaneously for faster development cycles
  • Fine-Grained Permissions - Each agent has precisely scoped tool access (read, write, bash, web)
  • Bounded Execution - Subagents limited to 15-30 steps to prevent runaway processes
  • MCP Integration - Optional Exa (web search) and Ref (documentation) servers for enhanced capabilities
  • Model Flexibility - Easily swap between Claude, GPT, Gemini, and other providers
  • Production Ready - Battle-tested configuration with clear documentation and examples

Quick Start

1. Install with the Installation Script

# Clone the repository
git clone https://github.com/BrightEra/opencode-agent-team.git
cd opencode-agent-team

# Run the installer (copy mode - default)
./install.sh

# Or use symlink mode for easy updates
./install.sh --symlink

2. Set Up API Keys

# Required: Anthropic API key
export ANTHROPIC_API_KEY='your-api-key-here'

# Optional: Enhanced search capabilities
export EXA_API_KEY='your-exa-key'      # Get at https://exa.ai
export REF_API_KEY='your-ref-key'      # Get at https://ref.tools

3. Start Using Agents

# Use the plan agent for strategic analysis
opencode --agent plan
@plan Analyze the codebase structure and suggest refactoring opportunities

# Use build for implementation
opencode --agent build
@build Implement the refactoring suggestions

# Use specialized agents for specific tasks
@scout Find all TypeScript files in src/
@tester Write unit tests for the new code
@reviewer Review the implementation for quality issues

Installation

Method 1: Automated Installer (Recommended)

The installation script provides three modes:

Copy Mode (Default)

Files are copied to ~/.config/opencode/ and are independent of the source repository.

git clone https://github.com/BrightEra/opencode-agent-team.git
cd opencode-agent-team
./install.sh --copy

Symlink Mode (For Development)

Files are symlinked, allowing easy updates via git pull.

git clone https://github.com/BrightEra/opencode-agent-team.git
cd opencode-agent-team
./install.sh --symlink

# Update later with:
git pull origin main

Uninstall

Remove the installation (creates a backup first).

./install.sh --uninstall

Features:

  • ✓ Automatic prerequisite checking
  • ✓ Backup of existing configuration
  • ✓ Colored output with progress indicators
  • ✓ Post-install instructions
  • ✓ Error handling and validation

Method 2: Manual Installation

# Download the configuration
git clone https://github.com/BrightEra/opencode-agent-team.git
cd opencode-agent-team

# Copy to OpenCode config directory
mkdir -p ~/.config/opencode/.opencode/prompts
cp opencode.json ~/.config/opencode/
cp AGENTS.md ~/.config/opencode/
cp .opencode/prompts/plan.md ~/.config/opencode/.opencode/prompts/
cp .opencode/prompts/build.md ~/.config/opencode/.opencode/prompts/

Method 3: NPM/Bun Install (Coming Soon)

# Install as a package
npm install -g @brighterra/opencode-agent-team

# Or with bun
bun add -g @brighterra/opencode-agent-team

Agent Reference

Primary Agents

Agent Model Steps Purpose
plan Claude Opus 4.5 Unlimited Strategic planning, task decomposition, architectural decisions, code analysis without modification
build Claude Sonnet 4.5 Unlimited Primary implementation, file editing, running commands, full tool access

Fast Subagents (Haiku)

Agent Model Steps Purpose
scout Claude Haiku 4.5 15 Fast codebase exploration, file pattern matching, code search, directory structure analysis
docs Claude Haiku 4.5 15 Documentation writing, README updates, API docs, docstrings, changelog entries

Standard Subagents (Sonnet)

Agent Model Steps Purpose
research Claude Sonnet 4.5 25 Documentation lookup, API research, best practices, framework patterns, version compatibility
reviewer Claude Sonnet 4.5 20 Code review, quality assessment, anti-pattern detection, architectural feedback
tester Claude Sonnet 4.5 25 Unit/integration/E2E tests, test suite execution, coverage analysis, test debugging
refactor Claude Sonnet 4.5 25 Code structure improvement, method extraction, variable renaming, design patterns, modernization
debug Claude Sonnet 4.5 25 Error investigation, stack trace analysis, log examination, git bisect, performance diagnosis
devops Claude Sonnet 4.5 30 Docker, Kubernetes, CI/CD pipelines, Terraform, cloud configs, monitoring, deployment
security Claude Sonnet 4.5 20 Vulnerability scanning, security anti-patterns, auth/authz review, secrets detection, API security

Agent Capabilities Matrix

                 read  write  edit  bash  web   git   MCP
plan             ✓     ✗      ✗     ✗     ✓     ✗     ✓
build            ✓     ✓      ✓     ✓     ✓     ✓     ✓
scout            ✓     ✗      ✗     ✗     ✗     ✗     ✗
research         ✓     ✗      ✗     ✗     ✓     ✗     ✓
reviewer         ✓     ✗      ✗     ✗     ✗     ✗     ✓
tester           ✓     ✓      ✓     ✓*    ✗     ✗     ✗
refactor         ✓     ✗      ✓     ✗     ✗     ✗     ✗
debug            ✓     ✗      ✗     ✓*    ✗     ✓     ✗
devops           ✓     ✓      ✓     ✓*    ✓     ✗     ✓
security         ✓     ✗      ✗     ✓*    ✗     ✓     ✓

* = Scoped permissions (specific commands allowed)

Workflow Guide

Plan-First Development Cycle

The core workflow follows a proven pattern:

1. PLAN (@plan)
   ↓
   Analyze requirements → Decompose tasks → Create execution plan
   ↓
2. DISCOVER (@scout + @research in parallel)
   ↓
   Find relevant code → Research best practices → Gather context
   ↓
3. IMPLEMENT (@build or specialized agents in parallel)
   ↓
   Write code → Run tests → Execute commands
   ↓
4. VALIDATE (@tester + @reviewer in parallel)
   ↓
   Test coverage → Code quality → Security audit
   ↓
5. DEPLOY (@devops)
   ↓
   Build → Configure → Deploy

When to Use Each Agent

Strategic Tasks

  • @plan: "Analyze this codebase and suggest a refactoring strategy"
  • @plan: "Design the architecture for a new feature"
  • @plan: "Break down this complex task into parallelizable work units"

Discovery Tasks

  • @scout: "Find all files matching pattern *.test.ts"
  • @scout: "Where is the authentication logic implemented?"
  • @research: "What's the latest version of React and what are the breaking changes?"
  • @research: "Find best practices for error handling in Node.js"

Implementation Tasks

  • @build: "Implement the new authentication system"
  • @refactor: "Extract this method into a separate class"
  • @refactor: "Rename all instances of oldName to newName"

Quality Assurance

  • @tester: "Write unit tests for the authentication module"
  • @tester: "Run the test suite and fix any failures"
  • @reviewer: "Review this code for potential bugs and anti-patterns"
  • @security: "Scan for security vulnerabilities in dependencies"

Operations

  • @devops: "Create a GitHub Actions workflow for CI/CD"
  • @devops: "Write a Dockerfile for this application"
  • @debug: "Investigate why the build is failing"
  • @debug: "Find the commit that introduced this regression"

Documentation

  • @docs: "Write a comprehensive README for this project"
  • @docs: "Generate API documentation from code comments"

Parallel Execution Examples

Discovery Phase (Run in Parallel)

@scout Find all service files
@research Look up the latest TypeScript best practices
@security Scan for vulnerabilities

Validation Phase (Run in Parallel)

@tester Write and run tests
@reviewer Review the implementation
@docs Update the changelog

Sequential Execution (When Order Matters)

@debug → diagnose the issue
@refactor → fix the code
@tester → verify the fix works

Configuration

Customizing Models

Edit opencode.json to change the default model or per-agent models:

{
  "model": "anthropic/claude-sonnet-4-5-20250929",
  "agent": {
    "plan": {
      "model": "anthropic/claude-opus-4-5-20251101"
    },
    "build": {
      "model": "openai/gpt-4-turbo"
    }
  }
}

Adjusting Agent Permissions

Modify tool access for specific agents:

{
  "agent": {
    "scout": {
      "tools": {
        "bash": false,
        "webfetch": false,
        "read": true,
        "grep": true
      }
    }
  }
}

Changing Step Limits

Adjust maxSteps to control execution bounds:

{
  "agent": {
    "tester": {
      "maxSteps": 30
    }
  }
}

Adding Custom Agents

Extend the configuration with your own specialized agents:

{
  "agent": {
    "myagent": {
      "description": "My custom agent for specific tasks",
      "mode": "subagent",
      "model": "anthropic/claude-sonnet-4-5-20250929",
      "temperature": 0.2,
      "maxSteps": 20,
      "tools": {
        "read": true,
        "write": true,
        "edit": true,
        "bash": false
      }
    }
  }
}

Model Alternatives

The configuration uses Claude models by default, but you can substitute with alternatives. Here's the recommended tier structure:

Tier 1: Planning & Analysis (Strategic Thinking)

Primary Choice:

  • anthropic/claude-opus-4-5-20251101 (Claude Opus 4.5)

Alternatives:

  • openai/gpt-5.2 (OpenAI GPT-5.2)
  • google/gemini-3-pro (Google Gemini 3 Pro)
  • deepseek/deepseek-v3.2 (DeepSeek V3.2)

Use for: @plan agent

Tier 2: Implementation & Development (Balanced Performance)

Primary Choice:

  • anthropic/claude-sonnet-4-5-20250929 (Claude Sonnet 4.5)

Alternatives:

  • openai/gpt-5.1 (OpenAI GPT-5.1)
  • deepseek/deepseek-v3.2 (DeepSeek V3.2)
  • anthropic/claude-opus-4-5-20251101 (Claude Opus 4.5)

Use for: @build, @research, @tester, @refactor, @debug, @devops, @security, @reviewer

Tier 3: Fast Tasks (Speed Optimized)

Primary Choice:

  • anthropic/claude-haiku-4-5-20251001 (Claude Haiku 4.5)

Alternatives:

  • openai/gpt-5-mini (OpenAI GPT-5 Mini)
  • anthropic/claude-opus-4-5-20251101 (Claude Opus 4.5)

Use for: @scout, @docs

Model Selection Guide

Scenario Recommendation
Cost-sensitive, small tasks Haiku/GPT-5-mini
Balanced cost/performance Sonnet/GPT-5.1
Complex analysis, planning Opus/GPT-5.2
Long context windows needed Opus/GPT-5.2
Code generation focus Sonnet/GPT-5.1
Security-critical tasks Opus/GPT-5.2

MCP Setup

Optional: Exa (Web Search & Code Context)

Exa provides web search and code context capabilities for the @research and @plan agents.

Get API Key

  1. Visit exa.ai
  2. Sign up for a free account
  3. Copy your API key from the dashboard

Configure

export EXA_API_KEY="your-api-key-here"

The configuration will automatically use Exa if the environment variable is set.

Optional: Ref (Documentation Lookup)

Ref provides fast documentation lookup for libraries and frameworks.

Get API Key

  1. Visit ref.tools
  2. Sign up for a free account
  3. Copy your API key from the dashboard

Configure

export REF_API_KEY="your-api-key-here"

The configuration will automatically use Ref if the environment variable is set.

Verify MCP Setup

# Check if MCP servers are available
opencode --list-mcp

# Test Exa
@research Search for "React hooks best practices"

# Test Ref
@research Look up the TypeScript documentation for generics

Troubleshooting

Agent Not Found

Problem: Error: Agent 'xyz' not found

Solution:

  1. Verify the agent name is spelled correctly
  2. Check that opencode.json is in ~/.config/opencode/
  3. Reload OpenCode: opencode --reload-config

Permission Denied

Problem: Error: Permission denied for tool 'bash'

Solution:

  1. Check the agent's permissions in opencode.json
  2. Some agents have scoped bash permissions (e.g., @tester only allows test commands)
  3. Use @build for unrestricted bash access

MCP Server Not Connecting

Problem: Error: Failed to connect to MCP server 'exa'

Solution:

  1. Verify API keys are set: echo $EXA_API_KEY
  2. Check internet connection
  3. Temporarily disable MCP in opencode.json: 
    {
  "tools": {
    "exa*": false,
    "Ref*": false
  }
}

Agent Exceeding Step Limit

Problem: Error: Agent exceeded maximum steps (15)

Solution:

  1. Break the task into smaller subtasks
  2. Use @plan to decompose complex tasks
  3. Increase maxSteps in opencode.json if needed (not recommended)

Model Not Available

Problem: Error: Model 'anthropic/claude-opus-4-5-20251101' not available

Solution:

  1. Verify you have API access to the model
  2. Check your API key is set correctly
  3. Switch to an alternative model (see Model Alternatives)

Slow Response Times

Problem: Agents are responding slowly

Solution:

  1. Check your internet connection
  2. Verify API rate limits aren't exceeded
  3. Use faster models (Haiku for @scout, @docs)
  4. Break tasks into smaller units

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines on:

  • Reporting bugs
  • Suggesting improvements
  • Submitting pull requests
  • Adding new agent configurations
  • Improving documentation

Development Setup

# Clone the repository
git clone https://github.com/BrightEra/opencode-agent-team.git
cd opencode-agent-team

# Test your changes
opencode --validate-config opencode.json

# Submit a pull request
git checkout -b feature/your-feature
git commit -am "Add your feature"
git push origin feature/your-feature

License

This project is licensed under the MIT License - see the LICENSE file for details.

Attribution: Created by Justin Carlson / BrightEra

Acknowledgments

  • OpenCode - The AI-powered CLI that makes this possible
  • Anthropic - For Claude models
  • Exa - For web search and code context
  • Ref - For documentation lookup
  • The open-source community for inspiration and feedback

Back to Top

Made with ❤️ by BrightEra

About

Plan-first agent hierarchy for OpenCode with 15 specialized agents

github.com/BrightEra/opencode-agent-team

Resources

Readme
MIT license

Code of conduct

Code of conduct

Contributing

Contributing
Activity
Custom properties

Stars

2 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Sponsor this project

Packages

Contributors

Languages