opencode-map
中文
← guides/

Agents in opencode: build, plan, and custom subagents

IntermediateLast updated: Oct 21, 2026

opencode splits work across two kinds of agents: primary agents you talk to directly, and subagents they delegate to. Both are configurable — this guide covers the built-ins and how to write your own.

Built-in primary agents

Press Tab to cycle primary agents during a session (Shift+Tab goes backwards).

  • build — the default. All tools enabled; the everyday development agent.
  • plan — restricted for planning and analysis. By default it denies file edits, writes, and patches outside its plan directory ~/.opencode/plan/ (refused without prompting), keeps the question tool so it can ask clarifying questions, and runs shell commands under your normal permission config.

Use plan to review code or design a change read-only; Tab back to build to execute it.

Plan’s defaults apply before your top-level permission config, and the last matching rule wins — a global "edit": "allow" unlocks plan too. To keep it read-only, set its permissions explicitly:

{
  "agent": {
    "plan": {
      "permission": {
        "edit": { "*": "deny", "~/.opencode/plan/*": "allow" },
        "shell": "ask"
      }
    }
  }
}

Built-in subagents

Primary agents invoke subagents automatically based on their descriptions, or you can invoke one manually by @-mentioning it:

@general help me search for this function
  • general — full tool access, for complex questions and multi-step tasks; can run units of work in parallel.
  • explore — fast, read-only codebase exploration: find files by pattern, grep for keywords, answer code questions.
  • scout — read-only external research: clones a dependency repo into opencode’s managed cache and inspects library source without touching your workspace.

Three hidden system agents — compaction, title, summary — handle context compaction and session metadata automatically; they aren’t selectable.

Subagent work runs in child sessions. From the parent: leader+down enters the first child (session_child_first), right/left cycles between children, up returns to the parent. These defaults come from tui.json keybinds.

Custom agents

Two ways to define one. Markdown — drop a file in .opencode/agents/ (project) or ~/.config/opencode/agents/ (global); the filename becomes the agent name:

---
description: Reviews code for quality and best practices
mode: subagent
model: anthropic/claude-sonnet-4-20250514
temperature: 0.1
permission:
  edit: deny
  shell: deny
---

You are in code review mode. Focus on quality, bugs, performance, and security.
Provide constructive feedback without making direct changes.

Or JSON — the agent key in opencode.json:

{
  "agent": {
    "code-reviewer": {
      "description": "Reviews code for best practices",
      "mode": "subagent",
      "model": "anthropic/claude-sonnet-4-20250514",
      "prompt": "You are a code reviewer. Focus on security, performance, and maintainability.",
      "permission": { "edit": "deny" }
    }
  }
}

The interactive opencode agent create command produces the same result: pick global or project, describe the agent, get a generated system prompt, select permissions, and it writes the markdown file.

Options worth knowing

Key Effect
description What the agent does and when to use it. Required. Primary agents read it to pick subagents.
mode primary, subagent, or all (default).
model provider/model-id override. Unset subagents inherit the invoking agent’s model.
prompt Custom system prompt — inline or {file:./prompts/x.txt} relative to the config file.
permission Per-tool allow/ask/deny, with glob patterns for keys like shell and edit.
steps Cap on agentic iterations; the agent must then summarize in text.
temperature / top_p Sampling control.
hidden Hide a subagent from the @ autocomplete; still invocable via the Task tool.
color UI color — hex value or a theme color name.
disable Turn the agent off.

tools is deprecated — use permission for new configs. Permission keys include read, edit, glob, grep, list, shell, task, webfetch, websearch, lsp, skill, question, external_directory, and doom_loop. permission.task glob-rules which subagents an agent may launch; users can always @-mention a subagent regardless.

v2 differences

The v2 docs rework agent config: the agents (plural) key replaces agent, prompt becomes system, permission and tools fold into an ordered {action, resource, effect} list under permissions, disable becomes disabled, variant joins the model ref as provider/model#high, temperature/top_p/options move under request.body (preserved but not yet sent with requests — configure active request settings on the provider/model/variant), and maxSteps becomes steps. v2 has no built-in scout and keeps default_agent for picking the startup primary; nested directories name agents — .opencode/agents/team/reviewer.md creates team/reviewer.

Further reading