OpenCode Agent Configuration Detailed Explanation

Agents are specialized AI assistants in OpenCode. Each agent can be configured with its own system prompt, model, tool access permissions, and behavioral constraints to handle specific types of tasks and workflows. You can switch agents at any time during a session, or by@ProxyNamedirectly invoking a specific agent.

Agent Types

Agents in OpenCode are divided into two types, each with different invocation methods and responsibilities:

Type Description Switching Method
Primary Agent The main assistant you interact with directly, handling the primary conversation flow. Tool access permissions are viapermissionconfiguration pressTabkey cycle switching, or use the configuredagent_cycleshortcut key
Subagent An assistant invoked by the primary agent to perform specialized tasks, running in an independent child session without affecting the main session context Automatically invoked by the primary agent, or manually invoked in a message using@ProxyNamemanually invoke

Built-in Agents

OpenCode includes 4 out-of-the-box agents, as well as 3 automatically running system agents:

1. Build (Primary Agent)

The default primary agent, with all tools enabled, suitable for daily development work that requires full file operations and system command access. This is the agent you will use most often.

2. Plan (Primary Agent)

A restricted agent designed specifically for code analysis and planning. By default, the following operations all trigger an approval prompt (set toask）：

  • file edits: all write, patch, and edit operations
  • bash: all bash commands

When you want the LLM to analyze code, make suggestions, or create an execution plan, but do not want it to make any actual modifications to the codebase, switch to the Plan agent.

3. General (Subagent)

A general-purpose subagent with full tool access (except the todo tool) and the ability to modify files. Suitable for researching complex problems and executing multi-step tasks, and can also run multiple independent work units in parallel.

4. Explore (Subagent)

A read-only subagent that cannot modify any files. Suitable for quickly finding files, searching code keywords, or answering questions about codebase structure. It is fast and has no side effects.

5. System Agents (Hidden)

The following three agents are automatically managed by OpenCode,and do not appear in the agent switching listThere is no need or way to manually select them:

Agent Name Responsibility Trigger Timing
Compaction Compresses overly long context into a smaller summary to prevent exceeding the model context limit Automatically runs when the context length reaches a threshold
Title Generates a short title for the session Automatically runs after a new session starts
Summary Creates a summary for the session Automatically runs when a session summary is needed

How to Use Agents

1. Switching Primary Agents

During a session, pressTabkey to cycle through all primary agents, pressShift+Tabto switch in reverse. You can also use<Leader>ato open the agent list and select directly.

2. Invoking Subagents

There are two ways to invoke subagents:

  • Automatic invocation: When the primary agent determines that a certain subagent is needed based on the nature of the task, it automatically invokes the subagent and delegates the task to it
  • Manual @ invocation: Use in a message@ProxyNameto directly specify which subagent should handle it
@general help me search for this function across the codebase

3. Navigating Between Parent and Child Sessions

When a subagent runs, it creates an independent child session. You can use shortcut keys to navigate between the parent session and each child session:

Shortcut Key Action
<Leader>+→（session_child_cycle） Cycle forward: Parent session → Child session 1 → Child session 2 → … → Parent session
<Leader>+←（session_child_cycle_reverse） Cycle backward: Parent session ← Child session 1 ← Child session 2 ← … ← Parent session
<Leader>+↑（session_parent） Return directly to the parent session

Two Configuration Methods

Agents can be defined either through JSON configuration or Markdown files. Both methods have the same effect; choose as needed:

Method 1: Configure in opencode.json

Example

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "build": {                                           // Override the built-in build agent configuration
      "mode": "primary",
      "model": "anthropic/claude-sonnet-4-20250514",
      "prompt": "{file:./prompts/build.txt}",           // Load system prompt from file
      "tools": {
        "write": true,
        "edit": true,
        "bash": true
      }
    },
    "code-reviewer": {                                   // Custom subagent
      "description": "Reviews code for best practices and potential issues",
      "mode": "subagent",
      "model": "anthropic/claude-sonnet-4-20250514",
      "prompt": "You are a code reviewer. Focus on security, performance, and maintainability.",
      "tools": {
        "write": false,
        "edit": false
      }
    }
  }
}

Method 2: Markdown File

Create a.mdfile in the following path,The file name is the agent name(e.g.,review.mdcorresponds to agent namereview）：

  • Global:~/.config/opencode/agents/(Valid for all projects)
  • Project-level:.opencode/agents/(Valid only for the current project)

Example

# File path: ~/.config/opencode/agents/review.md
---
description: Reviews code for quality and best practices
mode: subagent
model: anthropic/claude-sonnet-4-20250514
temperature: 0.1
tools:
  write: false
  edit: false
  bash: false
---

You are in code review mode. Focus on:

- Code quality and best practices
- Potential bugs and edge cases
- Performance implications
- Security considerations

Provide constructive feedback without making direct changes.

Configuration Options Explained

description (Description)

A description of the agent's functionality, displayed in the agent list and@auto-completion menu. It helps users and the primary agent decide when to invoke this agent. For custom agents, this field isrequired：

Example

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

mode (Mode)

Controls how the agent is used. It can be set to one of the following three values:

Value Description
"primary" Primary agent, appears in the Tab switching list, used for the main conversation
"subagent" Subagent, not in the Tab switching list, invoked by the primary agent or manually via @
"all" Used as both a primary agent and a subagent (default value when mode is not specified)

Example

{
  "agent": {
    "review": {
      "mode": "subagent"    // Used only as a subagent, does not appear in the primary agent switching list
    }
  }
}

model (Model)

Specifies a specific model for the agent, overriding the default model in the global configuration. The format isprovider/model-id. Suitable for using different models for different tasks, for example, a faster small model for planning tasks and a more powerful large model for code generation:

Example

{
  "agent": {
    "plan": {
      "model": "anthropic/claude-haiku-4-20250514"    // Use the faster Haiku model for planning tasks
    },
    "build": {
      "model": "anthropic/claude-sonnet-4-20250514"   // Use the more capable Sonnet model for development tasks
    }
  }
}

If not specifiedmodel, the primary agent will use the default model from the global configuration, and subagents will inherit the model used by the primary agent that invoked them. Runningopencode modelsYou can view the list of all available models.

prompt (System Prompt)

Specify a custom system prompt for the agent. You can write a string directly, or use the{file:./路径}syntax to load from an external file. The path is relative to the location of the configuration file:

Example

{
  "agent": {
    "review": {
      "prompt": "{file:./prompts/code-review.txt}"
      // Read the prompt from prompts/code-review.txt in the same directory as opencode.json
      // Suitable for long prompts; keep them maintained separately in a text file
    }
  }
}

temperature

Controls the randomness of model output. Lower values produce more deterministic output, suitable for tasks requiring precise results; higher values produce more diverse output, suitable for creative tasks:

Temperature range Output characteristics Applicable scenarios
0.0 – 0.2 Highly focused, highly deterministic Code analysis, planning, debugging, review
0.3 – 0.5 Balanced, combining accuracy and flexibility General development tasks, documentation writing
0.6 – 1.0 More creative and diverse Brainstorming, solution exploration, creative writing

Example

{
  "agent": {
    "analyze": {
      "temperature": 0.1,                          // Analysis tasks: high determinism
      "prompt": "{file:./prompts/analysis.txt}"
    },
    "build": {
      "temperature": 0.3                           // Development tasks: balanced
    },
    "brainstorm": {
      "temperature": 0.7,                          // Brainstorming: more creative
      "prompt": "{file:./prompts/creative.txt}"
    }
  }
}

When not specifiedtemperature, OpenCode uses the model's default value — most models default to0, while Qwen series models default to0.55。

steps (Maximum Steps)

Controls the maximum number of iterations (i.e., rounds of tool calls) the agent can execute before being forced to respond with plain text. Suitable for scenarios where you need to control costs or prevent the agent from looping indefinitely:

Example

{
  "agent": {
    "quick-thinker": {
      "description": "Fast reasoning with limited iterations",
      "prompt": "You are a quick thinker. Solve problems with minimal steps.",
      "steps": 5    // Execute at most 5 iterations; after that, the agent will output a summary of current progress and remaining suggested tasks
    }
  }
}

When not setsteps, the agent will continue iterating until the model stops on its own or the user manually interrupts.

LegacymaxStepsfield is deprecated, please usesteps。

tools (Tool Access)

Controls which tools this agent can use. Set the tool name totrueorfalse. Agent-level configuration willoverride global configuration：

Example

{
  "$schema": "https://opencode.ai/config.json",
  "tools": {
    "write": true,     // Global: allow file writing
    "bash": true       // Global: allow bash commands
  },
  "agent": {
    "plan": {
      "tools": {
        "write": false,    // plan agent: override global settings, disable file writing
        "bash": false      // plan agent: override global settings, disable bash
      }
    }
  }
}

You can also use wildcards to control tools in bulk, for example, disable all tools from a particular MCP server:

Example

{
  "agent": {
    "readonly": {
      "tools": {
        "mymcp_*": false,    // Disable all tools from the mymcp server (Glob matching)
        "write": false,
        "edit": false
      }
    }
  }
}

permission (Permissions)

Configure finer-grained permission control for the agent. You can set each operation to"allow"(allow),"ask"(ask), or"deny"(deny):

Example

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "edit": "deny"         // Global: deny all file editing by default
  },
  "agent": {
    "build": {
      "permission": {
        "edit": "ask"      // build agent: override global settings, require approval before editing
      }
    }
  }
}

Forbashtools, you can further refine to specific commands, with Glob wildcard support, andthe last matching rule takes precedence(It is recommended to put*wildcard rules first, and specific rules later):

Example

{
  "agent": {
    "build": {
      "permission": {
        "bash": {
          "*": "ask",             // Fallback: all bash commands require approval by default
          "git status *": "allow",// git status related commands are allowed directly (more specific, takes precedence)
          "grep *": "allow"       // grep search commands are allowed directly
        }
      }
    }
  }
}

In a Markdown agent file, you can also configure permissions in the frontmatter:

Example

# File path: ~/.config/opencode/agents/review.md
---
description: Code review without edits
mode: subagent
permission:
  edit: deny          # Deny all file editing
  bash:
    "*": ask          # bash commands require approval by default
    "git diff": allow # Allow git diff
    "git log*": allow # Allow git log and its variants
    "grep *": allow   # Allow grep search
  webfetch: deny      # Deny access to external URLs
---

Only analyze code and suggest changes.

permission.task (Task Permissions)

Controls which subagents this agent can call via the Task tool. Supports Glob matching. Set to"deny", the subagent will be completely removed from the Task tool description, and the model will not attempt to call it:

Example

{
  "agent": {
    "orchestrator": {
      "mode": "primary",
      "permission": {
        "task": {
          "*": "deny",                  // Fallback: deny calling all subagents by default
          "orchestrator-*": "allow",   // Allow calling subagents starting with orchestrator-
          "code-reviewer": "ask"        // Calling code-reviewer requires user confirmation
          // The last matching rule takes precedence: orchestrator-planner matches both * and orchestrator-*,
          // Because orchestrator-* is later, the result is allow
        }
      }
    }
  }
}

hidden (Hidden)

Hides the subagent from the@autocomplete menu, and only allows it to be called programmatically via the Task tool. Suitable for tool subagents that should only be called internally by other agents:

Example

{
  "agent": {
    "internal-helper": {
      "mode": "subagent",    // hidden only works for subagents
      "hidden": true         // After hiding, this agent will not appear in the user's @ completion menu,
                             // but when permissions allow, the model can still call it via the Task tool
    }
  }
}

color

Customizes the agent's display color in the UI. Supports hex color values or theme color keywords (primary、secondary、accent、success、warning、error、info）：

Example

{
  "agent": {
    "creative": {
      "color": "#ff6b6b"      // Use a hex color
    },
    "code-reviewer": {
      "color": "accent"       // Use a theme color keyword
    }
  }
}

top_p (Sampling Diversity)

top_pYestemperatureAnother parameter for controlling output diversity, with a value range of 0.0 – 1.0. Lower values produce more focused output, higher values produce more diverse output:

Example

{
  "agent": {
    "brainstorm": {
      "top_p": 0.9    // Higher top_p increases output diversity
    }
  }
}

disable (Disable)

Sets the agent to a disabled state. Once disabled, the agent will not appear in the selection list:

Example

{
  "agent": {
    "review": {
      "disable": true    // Disable this agent without affecting other agents
    }
  }
}

Other Model Parameters

Any unrecognized fields in the agent configuration will be passed directly to the service provider as model parameters. This allows you to use provider-specific advanced features:

Example

{
  "agent": {
    "deep-thinker": {
      "description": "Agent that uses high reasoning effort for complex problems",
      "model": "openai/gpt-5",
      "reasoningEffort": "high",    // OpenAI reasoning effort parameter, passed directly to the OpenAI API
      "textVerbosity": "low"        // OpenAI response verbosity parameter
    }
  }
}

Pass-through parameters vary by service provider and model. Please consult the corresponding provider's API documentation to confirm the available parameter names.

Quickly Creating Agents

In addition to manually writing configuration files, you can also use the interactive command-line tool to quickly generate an agent:

opencode agent create

This command will guide you through the following steps in order:

  1. Choose where to save the agent (global~/.config/opencode/agents/or project-level).opencode/agents/）
  2. Describe the agent's responsibilities and goals
  3. Automatically generate an appropriate system prompt and agent identifier
  4. Choose which tools the agent can access
  5. Generate a Markdown file with the full configuration at the selected location

Agent Examples

Documentation Writing Agent

Example

# File path: ~/.config/opencode/agents/docs-writer.md
---
description: Writes and maintains project documentation
mode: subagent
tools:
  bash: false    # Disable bash; documentation writing does not need to execute commands
---

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

Focus on:
- Clear explanations
- Proper structure
- Code examples
- User-friendly language

Security Audit Agent

Example

# File path: ~/.config/opencode/agents/security-auditor.md
---
description: Performs security audits and identifies vulnerabilities
mode: subagent
tools:
  write: false    # Read-only: do not write files
  edit: false     # Read-only: do not edit files
---

You are a security expert. Focus on identifying potential security issues.

Look for:
- Input validation vulnerabilities
- Authentication and authorization flaws
- Data exposure risks
- Dependency vulnerabilities
- Configuration security issues

Common Use Cases

Scenario Recommended agent configuration
Daily development, requires full tool permissions Use the built-inBuildagent
Analyze code and create plans without modifying files Switch to the built-inPlanagent
Read-only query of codebase structure or keywords Via@explorecall the built-inExploresubagent
Execute multiple independent tasks in parallel Via@generalcall multipleGeneralsubagents for parallel processing
Perform security or quality review on code Custom read-only subagent (disable write/edit), set low temperature (0.1)
Control costs, limit AI execution steps Configurestepsparameter to limit the maximum number of iterations
Other extensions