OpenCode agents and model routing

OpenCode routes work through primary agents (Plan, Build) and subagents (@explore, @scout, @general). Each agent can use a different model, step cap, and permission set — the main cost-control surface after opencode stats.

This page answers opencode plan build, opencode agent, opencode max steps, and subagent overhead.

Hub: Tokenminning in OpenCode.

Plan vs Build

Press Tab to cycle primary agents. Plan is read-only by default (edits and bash set to ask); Build has full tool access.

Agent	Mode	Typical model	When to use
Plan	`primary`	Haiku / mid-tier	Analysis, architecture, review plans
Build	`primary`	Sonnet-class	Edits, refactors, implementation

Start in Plan; switch to Build only when you approve the approach. See Intro: Plan mode .


{
  "$schema": "https://opencode.ai/config.json",
  "default_agent": "plan",
  "model": "anthropic/claude-sonnet-4-5",
  "small_model": "anthropic/claude-haiku-4-5",
  "agent": {
    "plan": { "model": "anthropic/claude-haiku-4-20250514" },
    "build": { "model": "anthropic/claude-sonnet-4-5", "steps": 25 }
  }
}

Setting	Token effect
`default_agent`	Every new session starts in Plan — avoids accidental Build loops
`small_model`	Cheaper model for hidden `title`, `summary`, `compaction` agents
`agent.build.steps`	Hard cap on agentic iterations before forced text reply

Built-in subagents

Invoke with @ mention or let the Task tool delegate. Each subagent spawns a child session with fresh context and its own model calls.

Subagent	Access	Cost profile	Prefer when
`@explore`	Read-only	Low — no edit loop	File patterns, codebase search
`@scout`	Read-only	Medium — may clone dependency repos	Upstream library research
`@general`	Full tools	High — parallel child sessions	Multi-step work only

Do not @general for simple grep. Use built-in grep / @explore instead.

Limit subagent depth and spawning


{
  "subagent_depth": 1,
  "agent": {
    "build": {
      "permission": {
        "task": {
          "*": "deny",
          "explore": "allow",
          "scout": "allow"
        }
      }
    }
  }
}

Setting	Effect
`subagent_depth`	`1` (default) — subagents cannot spawn nested subagents
`permission.task`	Deny `@general` by default; allow read-only subagents only

Hidden system agents (compaction, title, summary) also call the model when triggered. Route them to small_model via global config — see Providers.

Cap agentic loops with steps

From Agents: max steps :


{
  "agent": {
    "build": { "steps": 25 },
    "quick-thinker": { "steps": 5 }
  }
}

When the limit is hit, OpenCode forces a text summary instead of more tool calls. Pair with permission.bash: "ask" if shell loops dominate spend.

Custom agents

Define agents in opencode.json or markdown under .opencode/agents/:


{
  "agent": {
    "code-reviewer": {
      "description": "Reviews code without edits",
      "mode": "subagent",
      "model": "anthropic/claude-haiku-4-20250514",
      "permission": { "edit": "deny", "bash": "deny" },
      "steps": 10
    }
  }
}

Keep custom agent prompts short. Set steps on any looping agent. Use mode: "subagent" for specialized work you invoke with @review.

Interactive scaffold: opencode agent create.

Troubleshooting

Frontier model on every question — Set default_agent: "plan" and cheaper agent.plan.model.

Parallel subagent spike — Restrict permission.task; prefer @explore over @general.

Hidden agent cost — Assign small_model; disable unnecessary auto-compaction if sessions are short (Context).