- Bump every version pin, pricing table, and model ID to the verified 2026-07-05 state (v1.17.13): Claude Fable 5 / Sonnet 5 on Zen, new free tier, deprecation sunset table, v1.17.x changelog section - Cover gaps: OpenCode Go vs Zen billing, Anthropic subscription-login removal (PR #18186), MCP resources, --mini mode, --auto flag, yolo mode - Fix correctness bugs: command-template !`cmd` syntax in docs and .opencode/commands, protect-secrets regex missing 'cat .env', dual plugin exports, quickstart PATH fix, Playwright MCP flags, ctrl+d keybind conflict, agent/command required-field claims - Fix links: cursor.com, windsurf.com, platform.claude.com, code.claude.com, opencode.ai/discord, Vercel Grep announcement - Rebrand: banner (Images/banner.svg), 1280x640 social preview asset, hero redesign with star CTA, ecosystem stats, private vulnerability reporting channel, CI-matching local checks, MD060 lint opt-out
7.6 KiB
Agents — Custom Agents & Subagents
Custom agents let you bake a role, model choice, and permission profile into a markdown file. They show up in the Tab cycle (primary) or as
@mentions(subagent).
The agent zoo
Five OpenCode-built-in agents you should know:
| Name | Mode | Tools | Reach for it when… |
|---|---|---|---|
build |
primary (default) | All | Default daily-driver — implementation, refactors |
plan |
primary | edit & bash set to "ask" |
Read-only-ish analysis — exploration, design |
general |
subagent | All minus todowrite |
Big sub-tasks you want isolated from main context |
explore |
subagent | read, grep, glob, list |
"Where is X?" code search |
scout |
subagent | webfetch, websearch, + read tools |
External docs and dependency research |
Hit Tab to cycle primaries. Use @<name> in your prompt to invoke a subagent.
Custom agents — file format
Two locations, same format:
| Scope | Path |
|---|---|
| Project | .opencode/agents/<name>.md |
| Global | ~/.config/opencode/agents/<name>.md |
🆕 File-based agent loading is GA as of v1.16. Scaffold one interactively with
opencode agent create(it prompts for location, description, mode, and permissions), or just write the markdown by hand.
---
description: Senior frontend engineer — Tailwind + React + TypeScript expert
mode: all
model: anthropic/claude-sonnet-5
temperature: 0.2
permission:
edit: allow
bash:
"*": "ask"
"pnpm test*": "allow"
"pnpm lint*": "allow"
"git status*": "allow"
webfetch: deny
tools:
websearch: false
---
You are a senior frontend engineer. Specifics:
- Use Tailwind for styling. Reach for CSS modules only when Tailwind can't express it.
- Components are TypeScript with named exports and explicit Props types.
- Tests use Vitest + @testing-library/react.
- Match existing patterns in `src/components/Button/` for new components.
Frontmatter keys
Verified against the config JSON schema's AgentConfig:
| Key | Type | Purpose |
|---|---|---|
description |
string | Shown in /agents and surfaced to the LLM |
mode |
primary | subagent | all |
How the agent can be invoked |
model |
provider/model-id |
Per-agent model override |
temperature · top_p |
number | Sampling controls |
permission |
object | Per-tool allow/ask/deny (see below) |
tools |
object | Deprecated — prefer permission. Boolean per tool — {"websearch": false} |
prompt (JSON form only) |
string | System prompt; alternative to markdown body |
steps |
number | Max agentic iterations before a forced text-only response |
maxSteps |
number | Deprecated — use steps. |
disable |
boolean | Disable an agent entirely |
hidden |
boolean | Hide from the UI but keep available |
color |
string | UI accent color |
variant · options |
string · object | Model variant + per-provider options |
Only description is effectively required — mode is optional and defaults to all.
Filename → agent name
The filename (minus .md) becomes the agent name. security-auditor.md → @security-auditor.
Naming rules: lowercase, alphanumeric, hyphens. No spaces, no underscores.
Mode reference
mode |
Where it appears | Use when |
|---|---|---|
primary |
Tab cycle alongside build/plan |
A persistent role you'll inhabit for hours |
subagent |
@<name> mentions, task tool |
A focused helper for a specific sub-task |
all |
Both | You want flexibility (most custom agents) |
Permission model
Permission keys (verified against PermissionConfig in the config JSON schema):
| Key | Tools / behavior gated |
|---|---|
read |
read tool |
edit |
write, edit, apply_patch |
bash |
shell — supports glob-pattern overrides |
glob · grep · list |
search and listing |
task |
spawning subagents |
todowrite |
the in-session todo list |
question |
the question tool |
external_directory |
files outside the project root |
webfetch · websearch |
network access |
lsp |
language server tools |
skill |
agent skill loading |
doom_loop |
runaway-loop safeguards |
Three values everywhere: "allow" (no prompt) · "ask" (prompt user) · "deny" (block).
Glob-pattern bash
The bash key can be a single value or a glob-map. Order matters: rules are matched in order and the last matching rule wins, so put the catch-all * first and the more specific overrides after it.
{
"permission": {
"bash": {
"*": "ask",
"git status*": "allow",
"git diff*": "allow",
"pnpm test*": "allow",
"git push --force*": "deny",
"rm -rf*": "deny"
}
}
}
Use this to keep an agent productive (no constant prompting for safe reads) while still gating destructive commands.
Choosing a model per agent
{
"agent": {
"explore": { "model": "opencode/qwen3.6-plus" },
"scout": { "model": "opencode/qwen3.6-plus" },
"plan": { "model": "opencode/claude-opus-4-8" },
"build": { "model": "opencode/claude-sonnet-4-6" },
"deep-thinker": { "model": "openai/gpt-5", "options": { "reasoningEffort": "high" } }
}
}
If unspecified:
- Primary agents inherit the global
model. - Subagents inherit the model from whatever agent invoked them.
Tools per agent
⚠️ The
toolsmap is deprecated in favor of thepermissionfield (set a tool to"deny"to disable it). It still works and remains the simplest way to gate MCP tools by glob, but preferpermissionfor new configs.
The tools map enables/disables individual tools by name, including MCP tools (use glob patterns):
{
"agent": {
"doc-writer": {
"tools": {
"bash": false,
"edit": true,
"websearch": false,
"github_*": false
}
}
}
}
Note: tools is independent from permission. A tool can be enabled but still require "ask" per the permission map.
Patterns
Read-only reviewer
A subagent that reviews diffs but never writes. See specialized-agents/system-prompts/code-reviewer-prompt.md for the full prompt.
---
description: Reviews code without modifying files
mode: subagent
permission:
edit: deny
bash:
"*": "ask"
"git diff*": "allow"
---
Specialist primary
A daily-driver agent with a baked-in role. Different model, different prompt, different defaults.
---
description: Backend engineer — TypeScript, Postgres, REST
mode: primary
model: anthropic/claude-sonnet-5
permission:
bash:
"*": "ask"
"pnpm test*": "allow"
"pnpm typecheck*": "allow"
"psql*": "deny"
---
You're a backend engineer working on this monorepo's API…
Cheap research subagent
Read-only, cheap model — @scout-replacement scoped to a specific knowledge area.
---
description: Looks up React Router v7 patterns and idioms
mode: subagent
model: opencode/qwen3.6-plus
permission:
edit: deny
bash: deny
---
Drop-in specialists
This repo ships 7 production-ready prompts in specialized-agents/ — backend, frontend, code reviewer, security reviewer, tech lead, database, and UX. Copy any of them to .opencode/agents/<name>.md to use as a starting point.
📚 Full agent reference: opencode.ai/docs/agents.
Last reviewed: 2026-07-05 · Canonical source: opencode.ai/docs/agents.