Files
opencode-primer/docs/agents.md
T
Wesam Abousaid 9522c859fd docs(guides): add 10 deep-dive guides verified against opencode.ai/docs
- quickstart.md: 5-minute path from curl to first commit
- zen.md: model gateway with full lineup, pricing, BYOK, patterns
- tui.md: keybinds, leader chords, themes, customization, sessions
- agents.md: custom agents and subagents, full frontmatter, permission map
- commands.md: custom slash commands, placeholders, patterns, override rules
- skills.md: discoverable workflows, SKILL.md format, description-as-trigger
- plugins.md: lifecycle hooks, full event catalog, four real patterns
- mcp.md: local/remote MCP, OAuth (DCR), token budget, featured servers,
  with mermaid N×M → N+M diagram
- migration.md: Claude Code, Cursor, Copilot, Aider — with "what X does
  better" subsections so the comparisons aren't one-sided
- workflows.md: seven real recipes (TDD, bug investigation, multi-agent
  review, cross-repo research, migrations, CI, visual iteration) — CI
  example shows GitHub Actions + GitLab CI to avoid platform bias

Every model slug, permission key, config key, env var, and CLI flag
verified against the JSON schema or the live docs site.
2026-05-18 19:59:28 +02:00

6.8 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
---
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 Boolean per tool — {"websearch": false}
prompt (JSON form only) string System prompt; alternative to markdown body
maxSteps number Hard cap on agent steps in one invocation
steps array Scripted step sequence (advanced)
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
repo_clone · repo_overview repo-level operations
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: most specific patterns first.

{
  "permission": {
    "bash": {
      "rm -rf*": "deny",
      "git push --force*": "deny",
      "git status*": "allow",
      "git diff*": "allow",
      "pnpm test*": "allow",
      "*": "ask"
    }
  }
}

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-7" },
    "build":        { "model": "opencode/claude-sonnet-4-6" },
    "deep-thinker": { "model": "openai/gpt-5", "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 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 10 production-ready prompts in specialized-agents/. Copy any of them to .opencode/agents/<name>.md to use as a starting point.

📚 Full agent reference: opencode.ai/docs/agents.