Agent Configuration

Configure and customize OpenCode agents for specialized tasks and workflows.

Overview

OpenCode agents are specialized AI assistants that can be configured for specific tasks. The agent system supports two types:

Primary agents - Main assistants you interact with directly (switchable via Tab key)
Subagents - Specialized assistants invoked by primary agents or via @ mention

Agents can be customized with specific prompts, models, tool access, and permissions to create focused workflows optimized for different development scenarios.

Core Concepts

Agent Types

Primary Agents

Main conversation partners
Switch between them using Tab key or configured keybind
Examples: Build (full access), Plan (restricted for analysis)

Subagents

Invoked automatically by primary agents for specialized tasks
Can be manually invoked with @ mention (e.g., @general help me search)
Examples: General (multi-step tasks), Explore (codebase exploration)

Built-in Agents

OpenCode includes four primary built-in agents:

Build (Primary)

Default agent with all tools enabled
Full file operations and system commands
Standard development work

Plan (Primary)

Restricted agent for planning and analysis
File edits and bash commands set to ask by default
Analyzes and suggests without modifying code

General (Subagent)

General-purpose for complex questions and multi-step tasks
Full tool access except todo
Execute multiple units of work in parallel

Explore (Subagent)

Fast, read-only codebase exploration
Cannot modify files
Find patterns, search keywords, answer codebase questions

Switching and Invoking Agents

Switch primary agents:

Press Tab key during a session
Cycles through available primary agents

Invoke subagents:

Automatically by primary agents based on descriptions
Manually via @ mention: @explore find the authentication logic

Navigate between sessions:

Leader+Right: Cycle forward (parent → child1 → child2 → parent)
Leader+Left: Cycle backward

Configuration Methods

JSON Configuration

Configure agents in opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "build": {
      "mode": "primary",
      "model": "anthropic/claude-sonnet-4-20250514",
      "temperature": 0.3,
      "tools": {
        "write": true,
        "edit": true,
        "bash": true
      }
    },
    "code-reviewer": {
      "description": "Reviews code for best practices and potential issues",
      "mode": "subagent",
      "model": "anthropic/claude-sonnet-4-20250514",
      "prompt": "You are a code reviewer. Focus on security, performance, and maintainability.",
      "tools": {
        "write": false,
        "edit": false
      }
    }
  }
}

Markdown Configuration

Create agent files in:

Global: ~/.config/opencode/agents/
Project: .opencode/agents/

Example ~/.config/opencode/agents/review.md:

---
description: Reviews code for quality and best practices
mode: subagent
model: anthropic/claude-sonnet-4-20250514
temperature: 0.1
tools:
  write: false
  edit: false
  bash: false
---

You are in code review mode. Focus on:
- Code quality and best practices
- Potential bugs and edge cases
- Performance implications
- Security considerations

Provide constructive feedback without making direct changes.

Essential Configuration Options

Description (Required)

Brief description of what the agent does and when to use it.

{
  "agent": {
    "review": {
      "description": "Reviews code for best practices and potential issues"
    }
  }
}

Mode

Controls how the agent can be used.

primary - Main agent, switchable via Tab
subagent - Invoked by other agents or @ mention
all - Both (default if not specified)

Model

Override the model for specific agents.

{
  "agent": {
    "plan": {
      "model": "anthropic/claude-haiku-4-20250514"
    }
  }
}

Model format: provider/model-id

Temperature

Control response randomness and creativity (0.0-1.0).

0.0-0.2: Focused, deterministic (code analysis)
0.3-0.5: Balanced (general development)
0.6-1.0: Creative (brainstorming)

Tools

Enable or disable specific tools.

{
  "agent": {
    "plan": {
      "tools": {
        "write": false,
        "bash": false,
        "mymcp_*": false  // Wildcard to disable MCP server tools
      }
    }
  }
}

Permissions

Control what actions an agent can take.

Permission levels:

allow - Execute without approval
ask - Prompt for approval
deny - Disable the tool

{
  "agent": {
    "build": {
      "permission": {
        "edit": "ask",
        "bash": {
          "*": "ask",
          "git status *": "allow",
          "git push": "ask"
        },
        "webfetch": "deny"
      }
    }
  }
}

Prompt

Custom system prompt file for the agent.

{
  "agent": {
    "review": {
      "prompt": "{file:./prompts/code-review.txt}"
    }
  }
}

Path is relative to config file location.

Max Steps

Maximum agentic iterations before text-only response.

{
  "agent": {
    "quick-thinker": {
      "steps": 5
    }
  }
}

Additional Options

hidden - Hide subagent from @ autocomplete menu

{
  "agent": {
    "internal-helper": {
      "mode": "subagent",
      "hidden": true
    }
  }
}

color - Customize UI appearance (hex color or theme color)

{
  "agent": {
    "creative": {
      "color": "#ff6b6b"
    }
  }
}

top_p - Alternative to temperature for controlling diversity (0.0-1.0)

MUST FOLLOW

Always define color, model, and temperature for every agent in opencode.json — never in the markdown agent file. These fields belong in opencode.json as the single source of truth for runtime configuration.

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "your-agent-name": {
      "model": "github-copilot/claude-sonnet-4.6",
      "temperature": 0.3,
      "color": "#ff6b6b"
    }
  }
}

Do not include model, temperature, or color in the agent's .opencode/agents/<name>.md frontmatter. The markdown file should only contain description, mode, tools, permission, steps, hidden, and the system prompt body.

Creating Custom Agents

Interactive Creation

Use the built-in command:

opencode agent create

This interactive process:

Asks where to save (global or project)
Requests agent description
Generates system prompt and identifier
Lets you select tool access
Creates markdown file with configuration

Manual Creation Steps

Identify the use case - What specific task or workflow?
Choose configuration method - JSON in opencode.json or markdown file
Set required fields:
- description - When to use this agent
- mode - Primary or subagent
Configure tools and permissions - What can the agent access?
Add custom prompt (optional) - Specialized instructions
Test the agent - Try it on real tasks and iterate

Common Patterns

Read-Only Analysis Agent

{
  "agent": {
    "analyzer": {
      "description": "Analyzes code without making changes",
      "mode": "subagent",
      "tools": {
        "write": false,
        "edit": false,
        "bash": false
      }
    }
  }
}

Documentation Writer

---
description: Writes and maintains project documentation
mode: subagent
tools:
  bash: false
---

You are a technical writer. Create clear, comprehensive documentation.

Focus on:
- Clear explanations
- Proper structure
- Code examples
- User-friendly language

Security Auditor

---
description: Performs security audits and identifies vulnerabilities
mode: subagent
tools:
  write: false
  edit: false
---

You are a security expert. Focus on identifying potential security issues.

Look for:
- Input validation vulnerabilities
- Authentication and authorization flaws
- Data exposure risks
- Dependency vulnerabilities
- Configuration security issues

Faster Model for Planning

{
  "agent": {
    "quick-plan": {
      "description": "Fast planning with cheaper model",
      "mode": "primary",
      "model": "anthropic/claude-haiku-4-20250514",
      "temperature": 0.1,
      "permission": {
        "edit": "deny",
        "bash": "deny"
      }
    }
  }
}

Quick Reference

Switch Agents

Tab key - Cycle through primary agents
@ mention - Invoke subagent (e.g., @explore find auth code)

Navigate Sessions

Leader+Right - Next child session
Leader+Left - Previous child session

Configuration Locations

Global JSON: ~/.config/opencode/opencode.json
Project JSON: .opencode/opencode.json
Global agents: ~/.config/opencode/agents/
Project agents: .opencode/agents/

Permission Levels

allow - No approval needed
ask - Prompt user
deny - Disabled

Temperature Ranges

0.0-0.2: Focused (analysis, planning)
0.3-0.5: Balanced (general dev)
0.6-1.0: Creative (brainstorming)

Additional Resources

Reference Files

For detailed information:

references/primary-agents.md - In-depth primary agent configuration
references/subagents.md - Subagent setup and invocation strategies
references/permissions.md - Complete permission system details

Example Files

Working examples in examples/:

custom-agents.md - Real-world custom agent configurations

agent-configuration