Agents

Agents combine a system prompt, model preference, tool permissions, and display metadata into a reusable assistant profile. OpenCode includes agents for common workflows, and you can override them or add your own in configuration or Markdown files.

Built-in agents

OpenCode also has hidden compaction, title, and summary system agents. They run internal maintenance tasks and are not selectable. There is no built-in scout agent in V2.

You can override a built-in agent with an entry of the same ID. Set disabled: true to remove one.

Default agent

Set the primary agent used when a session has not selected one:

{
  "$schema": "https://opencode.ai/config.json",
  "default_agent": "reviewer"
}

The configured agent must exist, must not have mode: "subagent", and must not be hidden. If it is unavailable, OpenCode falls back to build, then to the first visible agent that can run as a primary agent. This selection does not rewrite the agent already stored on an existing session.

Modes

An agent’s mode controls where it can run:

In the TUI, press Tab and Shift+Tab to cycle through visible primary and all agents, or use /agents to choose one.

Subagents run in child sessions with fresh context. A primary agent can invoke one with the subagent tool, either in the foreground or in the background. You can also @ mention a visible subagent to ask the current agent to delegate work to it:

@explore find where authentication errors are handled

The parent agent’s subagent permission controls which agents it may launch. The child currently uses its own configured permissions, not a restricted copy of the parent’s permissions.

Configure agents

Markdown files

The recommended file locations are:

~/.config/opencode/agents/<name>.md
.opencode/agents/<name>.md

OpenCode discovers project .opencode directories from the current directory up to the project root. The path below agents/ becomes the agent ID, so .opencode/agents/team/reviewer.md defines team/reviewer.

Frontmatter uses the same fields as an entry under agents. The Markdown body becomes system:

---
description: Reviews changes without modifying files
mode: subagent
model: anthropic/claude-sonnet-4-5#high
color: warning
steps: 8
permissions:
  - action: edit
    resource: "*"
    effect: deny
  - action: shell
    resource: "*"
    effect: deny
---

Review for correctness, security, regressions, and missing tests.
List findings in severity order with file and line references.

JSON or JSONC

Use the agents field in any OpenCode configuration file:

{
  "$schema": "https://opencode.ai/config.json",
  "default_agent": "reviewer",
  "agents": {
    "reviewer": {
      "description": "Reviews changes for correctness, security, and missing tests",
      "mode": "all",
      "model": "anthropic/claude-sonnet-4-5#high",
      "system": "Review the current changes. Report findings before any summary.",
      "color": "warning",
      "steps": 8,
      "permissions": [
        { "action": "edit", "resource": "*", "effect": "deny" },
        { "action": "shell", "resource": "*", "effect": "deny" }
      ]
    },
    "build": {
      "permissions": [
        { "action": "shell", "resource": "git push *", "effect": "ask" }
      ]
    }
  }
}

Agent definitions merge in configuration order. Later scalar fields replace earlier values, request maps merge by key, and permission rules are appended. Global permissions are applied to every agent before its agent-specific rules, so a later agent rule can refine a global rule.

Options

description

Explains the agent’s purpose. It is optional, but strongly recommended for subagents because OpenCode includes it in the subagent catalog shown to the model.

mode

Accepts primary, subagent, or all. The default is all.

model

Selects a model using provider/model with an optional #variant:

{
  "agents": {
    "reviewer": {
      "model": "anthropic/claude-sonnet-4-5#high"
    }
  }
}

The equivalent expanded form is:

{
  "agents": {
    "reviewer": {
      "model": {
        "providerID": "anthropic",
        "model": "claude-sonnet-4-5",
        "variant": "high"
      }
    }
  }
}

The TUI uses this as the preferred model when the agent is selected. A child session uses its subagent’s configured model, or inherits the parent session’s model when none is configured. In the API, the session’s selected model is stored separately; creating or switching a primary session with only an agent ID does not itself change that session model.

system

Sets the agent’s system prompt. A non-empty value replaces OpenCode’s provider-specific base prompt for that agent. Project instructions, skills, references, and other instruction sources are still added separately.

For a Markdown agent, use the document body instead of a system frontmatter field.

permissions

Permissions are an ordered array of rules:

{
  "agents": {
    "orchestrator": {
      "permissions": [
        { "action": "subagent", "resource": "*", "effect": "deny" },
        { "action": "subagent", "resource": "explore", "effect": "allow" },
        { "action": "shell", "resource": "git *", "effect": "ask" }
      ]
    }
  }
}

Each rule has:

The last matching rule wins. Important V2 action names include shell for shell commands, edit for all edit/write/patch tools, and subagent for child agents. Other tools generally use their tool name, such as read, glob, grep, webfetch, websearch, and skill.

~ and $HOME are expanded in filesystem resources for read, edit, and external_directory. Shell resources are raw command text and are not expanded.

steps

Sets a positive maximum number of model steps. On the final allowed step, OpenCode removes tools and asks the model to summarize its work in text. New user input resets the allowance.

hidden

When true, removes the agent from normal selectors, @ autocomplete, and the subagent catalog advertised to models. It is a visibility setting, not a security boundary.

color

Sets the agent’s UI color. Use a six-digit hex color such as #ff6b6b, or one of primary, secondary, accent, success, warning, error, or info.

disabled

When true, removes the agent definition at that point in configuration loading. This works for built-in and custom agents.

request

The V2 schema accepts per-agent request headers and JSON body overlays:

{
  "agents": {
    "reviewer": {
      "request": {
        "headers": { "x-agent": "reviewer" },
        "body": { "temperature": 0.1 }
      }
    }
  }
}