opencode-teams

The policy, config, and UX layer for OpenCode Agent Teams

A CLI tool and library that brings intelligent task routing to OpenCode. Automatically route tasks to the right agent based on complexity, security sensitivity, and task type—saving costs while maintaining quality.

Features

• Smart Task Routing - Automatically routes tasks to the most appropriate agent based on signals like complexity, security sensitivity, and task type
• Multiple Agents - 7 specialized agents: teams (orchestrator), explorer, reviewer, impl-cheap, impl-fast, impl-deep, and quick
• Cost Optimization - Use cheaper models for simple tasks, reserve expensive models for complex work
• Presets - Three built-in presets: balanced, cost-optimized, and quality-first
• Flexible Configuration - Global defaults + per-project overrides with JSONC support
• Pattern Matching - Custom routing rules using regex patterns

Installation

npm install -g opencode-teams
# or
bun add -g opencode-teams

Quick Start

1. Initialize Configuration

# Interactive setup
opencode-teams init

# Or use a preset directly
opencode-teams init --preset balanced --yes

# Force overwrite existing config
opencode-teams init --preset cost-optimized --force --yes

2. Install Agents

The init command automatically installs agent files to ~/.config/opencode/agents/. These are markdown files that define each agent's behavior and capabilities.

3. Validate Setup

opencode-teams doctor

This checks that your configuration is valid and all required agents are installed.

4. Test Routing

# See which agent would handle a task
opencode-teams explain "Add authentication to the API"

# Show detailed signals
opencode-teams explain "Fix typo in README" --signals

Agents

| Agent | Capability | Default Model | Use Case | |-------|------------|---------------|----------| | @teams | lead | claude-sonnet-4 | Orchestrator, delegates to other agents | | @explorer | explore | claude-haiku-4 | Read-only codebase exploration | | @reviewer | review | claude-sonnet-4 | Code review and analysis | | @impl-cheap | cheap | claude-haiku-4 | Simple implementations, tests | | @impl-fast | fast | claude-sonnet-4 | Standard implementations | | @impl-deep | deep | claude-opus-4 | Complex/security-sensitive work | | @quick | quick | claude-haiku-4 | Trivial changes (typos, renames) |

Configuration

Configuration uses JSONC (JSON with comments) and is loaded from two locations:

1. Global: ~/.config/opencode/teams.jsonc - User defaults
2. Local: ./opencode-teams.jsonc - Project overrides

Local config is merged on top of global config.

Example Configuration

{
  // Use auto-routing based on task analysis
  "routing": {
    "mode": "auto",
    "fallbackAgent": "impl-fast",
    "patterns": [
      // Custom patterns (evaluated first)
      { "match": "migration|database", "capability": "deep", "agent": "impl-deep", "reason": "DB work needs care" }
    ]
  },
  
  // Model assignments per capability
  "capabilities": {
    "fast": {
      "primary": "anthropic/claude-sonnet-4-20250514",
      "fallback": ["openai/gpt-4o"]
    },
    "cheap": {
      "primary": "anthropic/claude-haiku-4-20250514",
      "fallback": []
    },
    "deep": {
      "primary": "anthropic/claude-opus-4-20250514",
      "fallback": ["openai/o3"]
    }
  },
  
  // Execution settings
  "execution": {
    "backend": "compat",
    "parallelAgents": 1
  },
  
  // Failover behavior
  "failover": {
    "maxRetries": 2,
    "retryDelay": 1000
  },
  
  // Logging for cost analysis
  "logging": {
    "enabled": true,
    "logDir": ".opencode-teams/logs"
  }
}

Presets

Use --preset with the init command:

| Preset | Description | |--------|-------------| | balanced | Default. Sonnet for most work, Haiku for cheap tasks, Opus for complex work | | cost-optimized | Haiku everywhere possible, Sonnet only for deep work | | quality-first | Opus for everything, o3 for deep thinking |

Routing Logic

The router analyzes task descriptions to extract signals:

• Task Type: explore, implement, test, review, fix, refactor
• Complexity: Architecture, algorithms, concurrency, etc.
• Security: Auth, tokens, encryption, XSS/CSRF, etc.
• Trivial: Typos, formatting, renames, etc.
• Test Related: Test keywords or test file patterns

Routing Priority

1. Pattern Match - Custom patterns in config (highest priority)
2. Security - Security-sensitive → impl-deep
3. Complexity - Complex/architectural → impl-deep
4. Exploration - Find/explore tasks → explorer
5. Review - Review/audit tasks → reviewer
6. Tests - Test tasks → impl-cheap
7. Trivial - Typos, renames → quick
8. Default - Standard work → impl-fast

CLI Commands

# Initialize configuration
opencode-teams init [options]
  --preset <name>    Use a preset (balanced, cost-optimized, quality-first)
  --local            Create local config only (no global)
  --force            Overwrite existing files
  -y, --yes          Skip confirmation prompts

# Validate configuration
opencode-teams doctor

# Explain routing for a task
opencode-teams explain <task> [options]
  --signals          Show detailed signal analysis
  --json             Output as JSON

# Print agent content (for debugging)
opencode-teams print-agent <name>

Programmatic Usage

import { createPlan, loadConfig, extractSignals } from 'opencode-teams'

// Load merged config
const config = await loadConfig()

// Create execution plan
const plan = createPlan('Add authentication to the API', config)

console.log(plan.steps[0].agent)      // 'impl-deep'
console.log(plan.steps[0].capability) // 'deep'
console.log(plan.steps[0].rationale)  // 'Security-sensitive task'

// Just extract signals
const signals = extractSignals('Fix typo in README')
console.log(signals.isTrivial)        // true

How It Works

1. Signal Extraction - Analyzes task description for keywords, patterns, and context
2. Pattern Matching - Checks custom routing patterns from config
3. Heuristic Routing - Falls back to built-in rules based on signals
4. Model Resolution - Maps agent capability to configured model
5. Plan Generation - Creates execution plan with rationale and risks

Integration with OpenCode

This package is designed to work with OpenCode's emerging Agent Teams feature. It provides:

• Policy Layer - Define which models/agents handle which tasks
• Config Layer - Centralized configuration with presets
• UX Layer - CLI tools for setup and debugging

Once OpenCode's native Teams API is available, this package will integrate directly.

Development

# Install dependencies
bun install

# Build
bun run build

# Run tests
bun run test

# Run tests once
bun run test:run

# Type check
bun run lint

License

MIT