Files
opencode-primer/docs/agents.md
Wesam Abousaid a3f328c043 docs: refresh for OpenCode v1.17.13, add Go coverage, and rebrand
- 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
2026-07-05 14:11:51 +02:00

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 tools map is deprecated in favor of the permission field (set a tool to "deny" to disable it). It still works and remains the simplest way to gate MCP tools by glob, but prefer permission for 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.