Files
opencode-primer/docs/agents.md
T
Wesam AbousaidandClaude Opus 4.8 29a69a35b0 docs: refresh for OpenCode v1.16.2 and fix correctness bugs
Update the guide to the current release (v1.16.2, 2026-06-05), verified
against opencode.ai/docs and github.com/anomalyco/opencode.

Correctness fixes:
- Plugins: tool.execute.before/after and shell.env are top-level hooks
  with an (input, output) signature, not event.type values. Rewrite both
  shipped example plugins plus the docs/migration examples so they fire.
- Permissions: bash glob maps resolve last-matching-rule-wins (catch-all
  "*" first), not most-specific-wins. Fix prose, reorder examples, and fix
  the shipped opencode.json (rm -rf* deny was shadowed by a later rm *).
- Drop non-existent permission keys repo_clone/repo_overview (15 keys, not
  17); fix steps (integer), deprecate maxSteps/tools, move reasoningEffort
  into model options; fix the `mise` install command.

Currency updates:
- v1.15.4 -> v1.16.2; add v1.16 highlights and a changelog section.
- Refresh OpenCode Zen lineup/pricing (Claude Opus 4.8, gpt-5.4,
  gemini-3.5-flash, qwen3.7, grok-build-0.1; correct free-tier IDs).
- Add `opencode mcp add`, run --replay, extra skill paths, shift+tab, and
  native GitHub commands; correct the specialist-prompt count; bump dates.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-08 19:00:39 +02:00

7.4 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, model, and permissions), or just write the markdown by hand.

---
description: Senior frontend engineer — Tailwind + React + TypeScript expert
mode: all
model: anthropic/claude-sonnet-4-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 and mode are required.

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-4-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.