Agents

Create a Markdown file to add a reusable agent. This example adds a read-only reviewer that the main agent can launch for code reviews:

---
description: Reviews changes for correctness and regressions
mode: subagent
model: anthropic/claude-sonnet-5-5#high
permissions:
  - action: edit
    resource: "*"
    effect: deny
  - action: shell
    resource: "*"
    effect: deny
---

Review the current changes. List findings in severity order with file and line references.

Ask your primary agent to use it:

Use the reviewer subagent to review my current changes.

An agent combines a system prompt, model preference, permissions, and display details into a named assistant profile.

Locations#

Save Markdown agents globally for all projects or inside a project:

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

OpenCode discovers project .opencode directories from the current directory up to the project root. A nested path becomes part of the agent ID:

.opencode/agents/team/reviewer.md  →  team/reviewer

Formats#

Markdown#

Frontmatter accepts the same fields as an agents configuration entry. The Markdown body becomes the agent’s system prompt:

---
description: Explains code without changing it
mode: subagent
---

Explain the relevant code with short examples. Do not edit files.

V1 frontmatter fields are deprecated. See Agent files for how files that still use them are read.

JSONC#

Define agents under agents in any OpenCode configuration file:

{
  "$schema": "https://opencode.ai/config.json",
  "agents": {
    "reviewer": {
      "description": "Reviews current changes",
      "mode": "subagent",
      "system": "Report findings in severity order.",
      "permissions": [
        { "action": "edit", "resource": "*", "effect": "deny" },
      ],
    },
  },
}

Selection#

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

{
  "$schema": "https://opencode.ai/config.json",
  "default_agent": "writer",
  "agents": {
    "writer": { "mode": "primary" },
  },
}

The selected default must exist, be visible, and support primary use. Otherwise OpenCode uses build, then the first visible primary-capable agent. Changing this setting does not replace the agent stored on an existing session.

Modes#

Set mode according to where the agent should run:

{
  "agents": {
    "reviewer": { "mode": "subagent" },
  },
}

Subagents run with fresh context in foreground or background child sessions. The parent agent’s subagent permissions control which agents it may launch; the child uses its own configured permissions.

{
  "agents": {
    "orchestrator": {
      "permissions": [
        { "action": "subagent", "resource": "*", "effect": "deny" },
        { "action": "subagent", "resource": "reviewer", "effect": "allow" },
      ],
    },
  },
}

Built-ins#

OpenCode includes these visible agents:

Override a built-in by using the same ID:

{
  "agents": {
    "build": {
      "permissions": [
        { "action": "shell", "resource": "git push *", "effect": "ask" },
      ],
    },
  },
}

Hidden compaction, title, and summary agents perform maintenance and cannot be selected directly. V2 has no built-in scout agent.

Merging#

Agent definitions merge in configuration order. Later scalar values replace earlier values, request maps merge by key, and permission rules append:

{
  "permissions": [
    { "action": "shell", "resource": "*", "effect": "ask" },
  ],
  "agents": {
    "build": {
      "permissions": [
        { "action": "shell", "resource": "git status", "effect": "allow" },
      ],
    },
  },
}

Global permissions apply before agent-specific rules, so later agent rules can refine them.

Options#

Description#

description explains the agent’s purpose. Add it to subagents because OpenCode shows it to the model choosing which agent to launch:

description: Reviews database migrations for safety

Mode#

mode accepts primary, subagent, or all. When omitted on a new custom agent, it defaults to primary:

mode: all

Model#

model uses provider/model with an optional #variant:

model: anthropic/claude-sonnet-5-5#high

JSON configuration also accepts the expanded form:

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

• A subagent uses its configured model, or inherits the parent session’s model when none is configured.
• A session stores its selected model separately. Selecting a primary agent by ID does not change that model.

System#

system sets the agent’s system prompt. A non-empty value replaces the provider’s base prompt for that agent:

{
  "agents": {
    "reviewer": { "system": "Review only. Do not modify files." },
  },
}

Project instructions, skills, references, and other instruction sources are still added. In a Markdown agent, put this text in the document body instead of a system frontmatter field.

Permissions#

permissions is an ordered list of matching rules:

{
  "agents": {
    "reviewer": {
      "permissions": [
        { "action": "*", "resource": "*", "effect": "deny" },
        { "action": "read", "resource": "src/**", "effect": "allow" },
      ],
    },
  },
}

The last matching rule wins, so put broad rules before exceptions. Common actions include:

For read, edit, and external_directory resources, OpenCode expands ~ and $HOME:

{ "action": "read", "resource": "~/notes/**", "effect": "allow" }

Shell resources remain raw command text and do not expand those values.

Steps#

steps sets a positive maximum number of model steps:

steps: 8

On the final step, OpenCode removes tools and asks the model to summarize in text. New user input resets the allowance.

Hidden#

hidden removes an agent from normal listings, interactive discovery, and the subagent catalog:

hidden: true

This controls visibility, not security. Use permissions to restrict behavior.

Color#

color sets the agent’s UI color using a six-digit hex value:

color: "#ff6b6b"

Disabled#

disabled removes a built-in or custom agent at that point in configuration loading:

{
  "agents": {
    "plan": { "disabled": true },
  },
}

Request#

request accepts per-agent header and JSON body overlays:

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

Do not use legacy top-level fields such as temperature, top_p, prompt, permission, tools, disable, or maxSteps in new V2 agent configuration.