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