Agents

Agents are specialized AI assistants that can be configured for specific tasks and workflows. They allow you to create focused tools with custom prompts, models, and tool access.

Tip

Use the Plan agent to analyze code and review suggestions without making any code changes.

Types

There are two types of agents in OpenCode: primary agents and subagents.

Primary Agents

Primary agents are the main assistants you interact with directly. You can cycle through them using the Tab key or your configured switch_agent keybind.

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

Subagents

Subagents are specialized assistants that primary agents can invoke for specific tasks. You can also manually invoke them by @ mentioning them in your messages.

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

Built-in

OpenCode comes with two built-in primary agents and three built-in subagents.

Use Build

Mode: primary

Build is the default primary agent with all tools enabled for development work.

Use Plan

Mode: primary

A restricted agent designed for planning and analysis. By default, file edits and bash are set to ask. Useful for analyzing code without making modifications.

Use General

Mode: subagent

A general-purpose agent for researching complex questions and executing multi-step tasks. Has full tool access for parallel work.

Use Explore

Mode: subagent

A fast, read-only agent for exploring codebases. Use this to quickly find files, search code, or answer questions about the codebase.

Use Scout

Mode: subagent

A read-only agent for external docs and dependency research. Use this to inspect library source or cross-reference local code against upstream implementations.

Use Compaction

Mode: primary | Hidden

System agent that compacts long context into a smaller summary. Runs automatically when needed.

Use Title

Mode: primary | Hidden

System agent that generates short session titles. Runs automatically.

Use Summary

Mode: primary | Hidden

System agent that creates session summaries. Runs automatically.

Usage

1. For primary agents, use Tab key to cycle through them during a session.
2. Subagents can be invoked:
   • Automatically by primary agents based on their descriptions
   • Manually by @ mentioning a subagent: @general help me search for this function
3. Navigation between sessions: When subagents create child sessions:
   • session_child_first (default: Leader+Down) to enter the first child
   • session_child_cycle (default: Right) to cycle to next child
   • session_parent (default: Up) to return to parent

Configure

Agents can be configured in two ways:

JSON

Configure agents in your opencode.json:

{
  "agent": {
    "build": {
      "mode": "primary",
      "model": "anthropic/claude-sonnet-4-20250514",
      "permission": {
        "edit": "allow",
        "bash": "allow"
      }
    },
    "plan": {
      "mode": "primary",
      "permission": {
        "edit": "deny",
        "bash": "deny"
      }
    }
  }
}

Markdown

Define agents using markdown files:

• Global: ~/.config/opencode/agents/
• Per-project: .opencode/agents/

---
description: Reviews code for quality
mode: subagent
permission:
  edit: deny
  bash: deny
---

You are in code review mode. Focus on security, performance, and maintainability.

Options

Description

Required - Brief description of what the agent does.

Temperature

Control randomness with temperature:

• 0.0-0.2: Very focused, ideal for code analysis
• 0.3-0.5: Balanced, good for general development
• 0.6-1.0: More creative, useful for brainstorming

Max Steps

Control maximum agentic iterations before forced text response.

{
  "agent": {
    "quick-thinker": {
      "steps": 5
    }
  }
}

Disable

Set disable: true to disable an agent.

Prompt

Specify custom system prompt file:

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

Model

Override the model for this agent:

{
  "agent": {
    "plan": {
      "model": "anthropic/claude-haiku-4-20250514"
    }
  }
}

Permissions

Configure permissions to manage what actions an agent can take:

• "ask" — Prompt for approval before running
• "allow" — Allow without approval
• "deny" — Disable the tool

Available permission keys: read, edit, glob, grep, list, bash, task, external_directory, todowrite, webfetch, websearch, lsp, skill, question, doom_loop

{
  "agent": {
    "build": {
      "permission": {
        "bash": {
          "git push": "ask",
          "git status *": "allow"
        }
      }
    }
  }
}

Mode

Control agent’s mode: primary, subagent, or all.

Hidden

Hide a subagent from the @ autocomplete menu with hidden: true. Useful for internal agents only invoked programmatically.

Task Permissions

Control which subagents an agent can invoke via the Task tool:

{
  "agent": {
    "orchestrator": {
      "permission": {
        "task": {
          "*": "deny",
          "orchestrator-*": "allow",
          "code-reviewer": "ask"
        }
      }
    }
  }
}

Color

Customize the agent’s visual appearance with color (hex or theme color: primary, secondary, accent, success, warning, error, info).

Top P

Alternative to temperature for controlling randomness (0.0 to 1.0).

Additional

Any other options are passed through to the provider directly for model-specific features.

Create Agents

Create new agents using:

opencode agent create

This interactive command will:

1. Ask where to save (global or project)
2. Ask for agent description
3. Generate system prompt and identifier
4. Let you select permissions
5. Create the markdown file

Examples

Documentation Agent

---
description: Writes and maintains project documentation
mode: subagent
permission:
  bash: deny
---

You are a technical writer. Create clear, comprehensive documentation.

Security Auditor

---
description: Performs security audits and identifies vulnerabilities
mode: subagent
permission:
  edit: deny
---

You are a security expert. Look for input validation vulnerabilities, authentication flaws, data exposure risks.