Opencode Agents

OpenCode Agents — Complete Reference

> 📚 Official Docs: For the latest information, always refer to the official documentation: > https://opencode.ai/docs/agents/

OpenCode supports a multi-agent architecture where specialized AI assistants handle different aspects of development. Agents come in two types — primary agents (direct user interaction, switchable via Tab) and subagents (invoked by other agents or via @mention/Task tool). There are also hidden agents (internal-use only, not user-selectable).

This guide covers every agent type, all built-in agents, every configuration option, the complete permission system, and how to create custom agents.

---

1. Agent Types

Primary Agents

Primary agents are the main assistants you interact with directly. They appear in the agent selector and can be cycled through using the Tab key (or your configured switch_agent keybind). Each primary agent has its own system prompt, tool permissions, temperature, and behavioral configuration.

OpenCode ships with two built-in primary agents: Build and Plan.

Primary agents are suitable for:

• Direct user conversation and coding
• Multi-step development tasks
• Planning and architecture analysis
• Read-only exploration

You can switch between primary agents mid-session by pressing Tab.

Subagents

Subagents are specialized assistants that primary agents can invoke for specific tasks. They run in isolated contexts and return results to the invoking agent. You can invoke them:

• Automatically — the primary agent decides when to delegate based on subagent descriptions
• Manually — by @mentioning them in your message (e.g., @explore find all auth functions)
• Programmatically — via the Task tool from another agent's configuration

OpenCode ships with three built-in subagents: General, Explore, and Scout.

Hidden Agents

Hidden agents are internal system agents not visible in the UI or @ autocomplete. They handle behind-the-scenes operations and run automatically when triggered by system events. You cannot select them directly, but they perform critical maintenance functions.

OpenCode ships with three hidden agents: Compaction, Title, and Summary.

---

2. Built-in Agents (Complete Reference)

Build — Primary Agent

| Property | Value | |----------|-------| | Mode | primary | | Tools | All enabled | | Default temperature | Model default (typically 0) | | Use case | General development, file creation, editing, debugging, building features |

Build is the default primary agent with all tools enabled. This is the standard agent for development work where you need full access to file operations, system commands, and all available tools. It is the agent you will use for most coding tasks.

What it can do:

• Read, write, and edit any file in the project
• Run any shell command
• Search codebases with glob and grep
• Fetch external URLs and web pages
• Invoke subagents via the Task tool
• Load and use skills
• Ask the user questions

Configuration (built-in defaults):

{
  "agent": {
    "build": {
      "description": "Default build agent with all tools",
      "mode": "primary"
    }
  }
}

Plan — Primary Agent

| Property | Value | |----------|-------| | Mode | primary | | Tools | All read tools enabled; edit and bash set to ask | | Default temperature | Model default (typically 0) | | Use case | Code analysis, planning, architecture review, reconnaissance |

A restricted agent designed for planning and analysis. By default, all file edits and bash commands are set to ask mode, meaning they require user confirmation before execution. This agent excels at reading code, analyzing architecture, and producing plans without making unintended changes.

What it can do:

• Read any file in the project
• Search with glob and grep
• Suggest changes (but requires approval to apply them)
• Run bash commands (requires approval)
• Fetch external documentation

What it cannot do without approval:

• Edit or write files
• Execute bash commands

Configuration (built-in defaults):

{
  "agent": {
    "plan": {
      "description": "Restricted agent for planning and analysis",
      "mode": "primary",
      "permission": {
        "edit": "ask",
        "bash": "ask"
      }
    }
  }
}

General — Subagent

| Property | Value | |----------|-------| | Mode | subagent | | Tools | All enabled except todo | | Default temperature | Model default | | Use case | Complex delegated tasks, multi-file refactors, bulk operations |

A general-purpose agent for researching complex questions and executing multi-step tasks. Has full tool access (except todo), so it can make file changes when needed. Use this to run multiple units of work in parallel.

What it can do:

• Read, write, and edit files
• Run shell commands
• Search codebases
• Fetch external URLs
• Load skills
• Ask the user questions

What it cannot do:

• Write to the todo list

Invocation:

@general help me refactor the authentication module

Explore — Subagent

| Property | Value | |----------|-------| | Mode | subagent | | Tools | read, grep, glob, webfetch (no edit, write, or bash) | | Default temperature | Model default | | Use case | Fast codebase exploration, finding definitions, understanding architecture |

A fast, read-only agent for exploring codebases. Cannot modify files. Use this when you need to quickly find files by patterns, search code for keywords, or answer questions about the codebase without any risk of changes.

What it can do:

• Read files (with line ranges)
• Search with glob patterns (**/*.ts, etc.)
• Search content with grep (regex)
• Fetch external URLs for documentation

What it cannot do:

• Write or edit any files
• Run shell commands
• Load skills

Invocation:

@explore find all TypeScript files that handle user authentication

Scout — Subagent

| Property | Value | |----------|-------| | Mode | subagent | | Tools | webfetch, read, grep, glob (no edit, write, or bash) | | Default temperature | Model default | | Use case | External documentation, dependency research, cross-referencing upstream code |

A read-only agent for external docs and dependency research. Use this when you need to clone a dependency repository into OpenCode's managed cache, inspect library source code, or cross-reference local code against upstream implementations without modifying your workspace.

What it can do:

• Fetch and read external URLs (documentation, GitHub repos, API references)
• Read files in OpenCode's managed cache
• Search cached content with grep and glob

What it cannot do:

• Write or edit files in the project
• Run shell commands
• Load skills

Invocation:

@scout look up the latest Stripe API docs for payment intents

Compaction — Hidden Primary Agent

| Property | Value | |----------|-------| | Mode | primary (hidden) | | Tools | System-managed | | Use case | Automatic context window compaction |

Handles context window compaction when conversations grow too long. Automatically summarizes older messages to preserve context while staying within token limits. Runs automatically when the context window approaches its limit. Not selectable in the UI.

Trigger: Automatic when context window is near capacity.

Behavior: Compacts the conversation history by summarizing older messages into a condensed form, preserving the most important context for continued work.

Title — Hidden Primary Agent

| Property | Value | |----------|-------| | Mode | primary (hidden) | | Tools | System-managed | | Use case | Automatic session title generation |

Generates short session titles based on conversation content. Runs automatically to create descriptive names for chat sessions, making it easier to identify and navigate between sessions. Not selectable in the UI.

Trigger: Automatic when a new session starts or after initial messages.

Behavior: Analyzes the conversation and produces a concise title (typically 3-7 words) that captures the session's purpose.

Summary — Hidden Primary Agent

| Property | Value | |----------|-------| | Mode | primary (hidden) | | Tools | System-managed | | Use case | Session persistence and resumption |

Creates session summaries for persistence and retrieval. Used when saving or loading session state. Not selectable in the UI.

Trigger: Automatic during session save/persistence operations.

Behavior: Generates a structured summary of the session's key points, decisions, and outcomes for later retrieval.

---

3. Configuration Methods

Agents can be configured through two methods: JSON configuration in opencode.json or Markdown files in agent directories.

JSON Configuration

Define agents in the agent field of opencode.json. This method is best for simple agent definitions and quick overrides of built-in agents.

Project-level config (.opencode/config.json):

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "build": {
      "description": "Custom build agent",
      "mode": "primary",
      "model": "anthropic/claude-sonnet-4-20250514",
      "temperature": 0.7,
      "steps": 100
    },
    "plan": {
      "description": "Custom plan agent",
      "mode": "primary",
      "model": "anthropic/claude-haiku-4-20250514",
      "permission": {
        "edit": "ask",
        "bash": "ask"
      }
    }
  }
}

Global config (~/.config/opencode/config.json):

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "build": {
      "model": "openai/gpt-5"
    }
  }
}

Markdown Files

Create agent definitions as Markdown files in one of these directories:

• Global: ~/.config/opencode/agents/ — available in all projects
• Per-project: .opencode/agents/ — available only in the current project

Each Markdown file defines a single agent. The filename (without extension) becomes the agent name. For example, review.md creates a review agent.

Markdown file structure:

---
description: What this agent does and when to use it
mode: subagent
model: anthropic/claude-sonnet-4-20250514
temperature: 0.1
steps: 50
permission:
  read: "allow"
  edit: "ask"
  bash: "ask"
  glob: "allow"
  grep: "allow"
  webfetch: "allow"
  task: "allow"
color: "#ef4444"
hidden: false
---

You are a specialized agent. Your system prompt goes here.

Instructions and behavioral guidelines for the agent.

Example: .opencode/agents/security.md

---
description: Security-focused agent that audits code for vulnerabilities
mode: subagent
model: anthropic/claude-sonnet-4-20250514
temperature: 0.2
steps: 50
permission:
  edit: "deny"
  bash: "ask"
  read: "allow"
  webfetch: "allow"
  glob: "allow"
  grep: "allow"
color: "#ef4444"
---

You are a security auditor. Your role is to:

1. Scan code for common vulnerabilities (SQL injection, XSS, CSRF, etc.)
2. Check for hardcoded secrets and credentials
3. Review authentication and authorization patterns
4. Assess dependency security
5. Report findings with severity ratings

Never modify files. Read-only analysis only.

CLI Creation

Use the opencode agent create command to create a new agent interactively:

opencode agent create

This launches an interactive prompt that:

1. Asks where to save the agent (global or project-specific)
2. Asks for a description of what the agent should do
3. Generates an appropriate system prompt and identifier
4. Lets you select which permissions the agent should be allowed (anything not selected is denied)
5. Creates a Markdown file with the agent configuration

The file is saved to either ~/.config/opencode/agents/ (global) or .opencode/agents/ (project).

---

4. All Agent Options (Complete Reference)

description (required)

A plain-text description of what the agent does and when to use it. This appears in the agent selector UI and is used by the system to understand the agent's purpose (including for automatic subagent selection).

{
  "description": "Reviews code for best practices and potential issues"
}

{
  "description": "Database administration agent for migrations and queries"
}

In Markdown files:

---
description: Writes and maintains project documentation
---

mode

Controls how the agent is accessed. Values:

| Value | Behavior | |-------|----------| | "primary" | Appears in Tab cycle, directly selectable by user | | "subagent" | Invoked via @mention or Task tool | | "all" | Available both as primary and subagent (default) |

{
  "mode": "subagent"
}

{
  "mode": "primary"
}

If no mode is specified, it defaults to "all".

model

Override the model used by this agent. Format: provider/model-id.

If you don't specify a model:

• Primary agents use the globally configured model
• Subagents inherit the model of the primary agent that invoked them

{
  "model": "anthropic/claude-sonnet-4-20250514"
}

{
  "model": "openai/gpt-5"
}

{
  "model": "opencode/gpt-5.1-codex"
}

Use opencode models to see available models.

temperature

Controls randomness and creativity of the LLM's responses. Range: 0.0 to 1.0.

| Range | Behavior | Best for | |-------|----------|----------| | 0.0 - 0.2 | Very focused, deterministic | Code analysis, planning, debugging | | 0.3 - 0.5 | Balanced with some creativity | General development tasks | | 0.6 - 1.0 | Creative and varied | Brainstorming, exploration, creative writing |

{
  "temperature": 0.3
}

If no temperature is specified, OpenCode uses model-specific defaults (typically 0 for most models, 0.55 for Qwen models).

{
  "agent": {
    "analyze": { "temperature": 0.1 },
    "build": { "temperature": 0.3 },
    "brainstorm": { "temperature": 0.7 }
  }
}

steps

Maximum number of agentic iterations (tool calls) before the agent is forced to produce a text-only response. Prevents infinite loops and controls task scope and cost.

{
  "steps": 100
}

When the limit is reached, the agent receives a special system prompt instructing it to respond with a summarization of its work and recommended remaining tasks.

If not set, the agent continues to iterate until the model chooses to stop or the user interrupts.

> Note: The legacy maxSteps field is deprecated. Use steps instead.

disable

Set to true to completely disable an agent. The agent will not appear anywhere in the UI.

{
  "disable": true
}

prompt

Path to a custom system prompt file. Supports the {file:...} syntax to reference files relative to the config file location (works for both global and project config).

{
  "prompt": "{file:./prompts/code-review.txt}"
}

{
  "prompt": "{file:.opencode/prompts/db-migrator.md}"
}

In Markdown agent files, the body content after the frontmatter becomes the system prompt directly — no separate file needed.

tools (deprecated)

> Deprecated: Use permission instead. The tools config is still supported for backwards compatibility but may be removed in a future version.

Enable or disable specific tools. true is equivalent to {"*": "allow"} permission; false is equivalent to {"*": "deny"}.

{
  "tools": {
    "write": true,
    "bash": true,
    "webfetch": false
  }
}

Agent-specific tools override the global config. Supports wildcards:

{
  "agent": {
    "readonly": {
      "tools": {
        "mymcp_*": false,
        "write": false,
        "edit": false
      }
    }
  }
}

permission

Granular permissio

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Timmy6942025
• Source: Timmy6942025/opencode-builder-skill
• License: MIT

Install and usage instructions live in the source repository linked above.