Skip to main content

​
Overview

Agents are specialized AI assistants for specific tasks. OpenCode supports two agent modes and multiple configuration formats.

​
Agent Types

TypeDescription
primaryMain agents you interact with directly (Tab to switch)
subagentSpecialized assistants invoked by primary agents or via @mention

​
Built-in Agents

AgentModeDescription
buildprimaryDefault agent with all tools enabled
planprimaryAnalysis mode with edit/bash set to ask
generalsubagentGeneral-purpose research and multi-step tasks
exploresubagentFast codebase exploration

​
JSONC Configuration

Define agents in opencode.jsonc: 
{
  "agent": {
    "code-reviewer": {
      "description": "Reviews code for best practices",
      "mode": "subagent",
      "model": "anthropic/claude-sonnet-4-5",
      "temperature": 0.1,
      "prompt": "You are a code reviewer. Focus on security and performance.",
      "steps": 10,
      "tools": {
        "write": false,
        "edit": false
      },
      "permission": {
        "bash": "ask"
      }
    }
  }
}

​
Markdown Configuration

Place files in ~/.config/opencode/agents/ or .opencode/agents/:
~/.config/opencode/agents/review.md
---
description: Reviews code for quality and best practices
mode: subagent
model: anthropic/claude-sonnet-4-5
temperature: 0.1
tools:
  write: false
  edit: false
  bash: false
permission:
  edit: deny
  bash:
    "git diff": allow
    "git log*": allow
    "*": ask
---

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.

​
Agent Options

OptionTypeDescription
descriptionstringRequired. Brief description of agent purpose
modeprimary / subagent / allAgent mode (default: all)
modelstringModel override (provider/model-id)
temperaturenumber0.0–1.0 (lower = more focused)
stepsnumberMax agentic iterations before forced response
promptstringCustom system prompt (supports {file:path})
toolsobjectTool enable/disable map
permissionobjectPermission overrides
disablebooleanDisable the agent

​
Temperature Guidelines

RangeUse Case
0.0–0.2Code analysis, planning (focused/deterministic)
0.3–0.5General development (balanced)
0.6–1.0Brainstorming, exploration (creative)

​
Additional Model Options

Pass provider-specific options directly: 
{
  "agent": {
    "deep-thinker": {
      "model": "openai/gpt-5",
      "reasoningEffort": "high",
      "textVerbosity": "low"
    }
  }
}

​
See Also