> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/anomalyco/opencode/llms.txt
> Use this file to discover all available pages before exploring further.
# Agents
> Configure and use specialized agents for different workflows.
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.
Use the Plan agent to analyze code and review suggestions without making any code changes.
You can switch between agents during a session or invoke them with the `@` mention.
***
## 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. These agents handle your main conversation. Tool access is configured via permissions — for example, Build has all tools enabled while Plan is restricted.
You can use the **Tab** key to switch between primary agents during a session.
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 two built-in subagents: **General** and **Explore**.
***
## Built-in Agents
OpenCode comes with two built-in primary agents and two built-in subagents.
***
### Build
**Mode:** Primary
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 and system commands.
**Features:**
* Full tool access (read, write, edit, bash, etc.)
* Ideal for active development and implementation
* Can modify files and execute commands without restrictions
* Best for building features, fixing bugs, and refactoring code
***
### Plan
**Mode:** Primary
A restricted agent designed for planning and analysis. The permission system gives you more control and prevents unintended changes.
By default, all of the following are set to `ask`:
* **File edits**: All writes, patches, and edits
* **Bash commands**: All bash/shell commands
This agent is useful when you want the AI to analyze code, suggest changes, or create plans without making any actual modifications to your codebase.
**Use cases:**
* Code analysis and review
* Architecture planning
* Proposing refactoring strategies
* Exploring implementation options
***
### General
**Mode:** Subagent
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 cases:**
* Running multiple units of work in parallel
* Complex research tasks requiring file exploration
* Multi-step implementation tasks
* Tasks requiring both reading and writing
Use this to run multiple units of work in parallel by invoking it multiple times.
***
### Explore
**Mode:** Subagent
A fast, read-only agent for exploring codebases. Cannot modify files.
**Use cases:**
* Quickly find files by patterns
* Search code for keywords and patterns
* Answer questions about the codebase structure
* Code exploration without risk of modification
**Features:**
* Read-only access (read, grep, glob, ls)
* Fast and efficient for code discovery
* Safe for exploration without side effects
***
## Usage
### Switching Primary Agents
Use the **Tab** key to cycle through primary agents during a session. You can also use your configured `switch_agent` keybind.
### Invoking Subagents
Subagents can be invoked in two ways:
1. **Automatically** by primary agents for specialized tasks based on their descriptions
2. **Manually** by @ mentioning a subagent in your message:
```txt theme={null}
@general help me search for this function
```
```txt theme={null}
@explore find all React components in the src directory
```
### Navigation Between Sessions
When subagents create their own child sessions, you can navigate between the parent session and all child sessions:
* **Leader+Right** (or your configured `session_child_cycle` keybind) to cycle forward through parent → child1 → child2 → ... → parent
* **Leader+Left** (or your configured `session_child_cycle_reverse` keybind) to cycle backward
This allows you to seamlessly switch between the main conversation and specialized subagent work.
***
## Configure
You can customize the built-in agents or create your own through configuration. Agents can be configured in two ways:
***
### JSON Configuration
Configure agents in your `opencode.json` config file:
```json title="opencode.json" theme={null}
{
"$schema": "https://opencode.ai/config.json",
"agent": {
"build": {
"mode": "primary",
"model": "anthropic/claude-sonnet-4-20250514",
"prompt": "{file:./prompts/build.txt}",
"tools": {
"write": true,
"edit": true,
"bash": true
}
},
"plan": {
"mode": "primary",
"model": "anthropic/claude-haiku-4-20250514",
"tools": {
"write": false,
"edit": false,
"bash": false
}
},
"code-reviewer": {
"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
}
}
}
}
```
***
### Markdown Configuration
You can also define agents using markdown files. Place them in:
* **Global**: `~/.config/opencode/agents/`
* **Per-project**: `.opencode/agents/`
```markdown title="~/.config/opencode/agents/review.md" theme={null}
---
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.
```
The markdown file name becomes the agent name. For example, `review.md` creates a `review` agent.
***
## Configuration Options
### Description
Provide a brief description of what the agent does and when to use it.
```json title="opencode.json" theme={null}
{
"agent": {
"review": {
"description": "Reviews code for best practices and potential issues"
}
}
}
```
This is a **required** config option for custom agents.
***
### Mode
Control the agent's mode. The `mode` option determines how the agent can be used.
```json title="opencode.json" theme={null}
{
"agent": {
"review": {
"mode": "subagent"
}
}
}
```
The `mode` option can be set to `primary`, `subagent`, or `all`. If no `mode` is specified, it defaults to `all`.
***
### Model
Override the model for this agent. Useful for using different models optimized for different tasks.
If you don't specify a model, primary agents use the globally configured model while subagents will use the model of the primary agent that invoked them.
```json title="opencode.json" theme={null}
{
"agent": {
"plan": {
"model": "anthropic/claude-haiku-4-20250514"
}
}
}
```
The model ID uses the format `provider/model-id`. For example, if you're using OpenCode Zen, you would use `opencode/gpt-5.1-codex` for GPT 5.1 Codex.
***
### Prompt
Specify a custom system prompt file for this agent.
```json title="opencode.json" theme={null}
{
"agent": {
"review": {
"prompt": "{file:./prompts/code-review.txt}"
}
}
}
```
The path is relative to where the config file is located. This works for both the global OpenCode config and the project-specific config.
***
### Temperature
Control the randomness and creativity of the AI's responses.
```json title="opencode.json" theme={null}
{
"agent": {
"plan": {
"temperature": 0.1
},
"creative": {
"temperature": 0.8
}
}
}
```
Temperature values typically range from 0.0 to 1.0:
* **0.0-0.2**: Very focused and deterministic responses, ideal for code analysis and planning
* **0.3-0.5**: Balanced responses with some creativity, good for general development tasks
* **0.6-1.0**: More creative and varied responses, useful for brainstorming and exploration
If no temperature is specified, OpenCode uses model-specific defaults (typically 0 for most models, 0.55 for Qwen models).
***
### Tools
Control which tools are available to this agent.
```json title="opencode.json" theme={null}
{
"$schema": "https://opencode.ai/config.json",
"tools": {
"write": true,
"bash": true
},
"agent": {
"plan": {
"tools": {
"write": false,
"bash": false
}
}
}
}
```
The agent-specific config overrides the global config.
You can also use wildcards to control multiple tools at once:
```json title="opencode.json" theme={null}
{
"agent": {
"readonly": {
"tools": {
"mymcp_*": false,
"write": false,
"edit": false
}
}
}
}
```
[Learn more about tools](/tools).
***
### Permissions
Configure permissions to manage what actions an agent can take. Permissions for `edit`, `bash`, and `webfetch` tools can be configured to:
* `"ask"` — Prompt for approval before running the tool
* `"allow"` — Allow all operations without approval
* `"deny"` — Disable the tool
```json title="opencode.json" theme={null}
{
"$schema": "https://opencode.ai/config.json",
"permission": {
"edit": "deny"
},
"agent": {
"build": {
"permission": {
"edit": "ask"
}
}
}
}
```
You can set permissions for specific bash commands:
```json title="opencode.json" theme={null}
{
"agent": {
"build": {
"permission": {
"bash": {
"*": "ask",
"git status *": "allow",
"git push": "ask"
}
}
}
}
}
```
[Learn more about permissions](/permissions).
***
### Max Steps
Control the maximum number of agentic iterations an agent can perform before being forced to respond with text only.
```json title="opencode.json" theme={null}
{
"agent": {
"quick-thinker": {
"description": "Fast reasoning with limited iterations",
"prompt": "You are a quick thinker. Solve problems with minimal steps.",
"steps": 5
}
}
}
```
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.
***
### Task Permissions
Control which subagents an agent can invoke via the Task tool. Uses glob patterns for flexible matching.
```json title="opencode.json" theme={null}
{
"agent": {
"orchestrator": {
"mode": "primary",
"permission": {
"task": {
"*": "deny",
"orchestrator-*": "allow",
"code-reviewer": "ask"
}
}
}
}
}
```
When set to `deny`, the subagent is removed from the Task tool description entirely, so the model won't attempt to invoke it.
Rules are evaluated in order, and the **last matching rule wins**. In the example above, `orchestrator-planner` matches both `*` (deny) and `orchestrator-*` (allow), but since `orchestrator-*` comes after `*`, the result is `allow`.
Users can always invoke any subagent directly via the `@` autocomplete menu, even if the agent's task permissions would deny it.
***
### Hidden
Hide a subagent from the `@` autocomplete menu with `hidden: true`. Useful for internal subagents that should only be invoked programmatically by other agents via the Task tool.
```json title="opencode.json" theme={null}
{
"agent": {
"internal-helper": {
"mode": "subagent",
"hidden": true
}
}
}
```
Only applies to `mode: subagent` agents.
***
### Other Options
Customize the agent's visual appearance in the UI.
Use a valid hex color (e.g., `#FF5733`) or theme color: `primary`, `secondary`, `accent`, `success`, `warning`, `error`, `info`.
```json title="opencode.json" theme={null}
{
"agent": {
"creative": {
"color": "#ff6b6b"
},
"code-reviewer": {
"color": "accent"
}
}
}
```
Control response diversity with the `top_p` option. Alternative to temperature for controlling randomness.
```json title="opencode.json" theme={null}
{
"agent": {
"brainstorm": {
"top_p": 0.9
}
}
}
```
Values range from 0.0 to 1.0. Lower values are more focused, higher values more diverse.
Set to `true` to disable the agent.
```json title="opencode.json" theme={null}
{
"agent": {
"review": {
"disable": true
}
}
}
```
Any other options you specify in your agent configuration will be passed through directly to the provider as model options. This allows you to use provider-specific features.
For example, with OpenAI's reasoning models, you can control the reasoning effort:
```json title="opencode.json" theme={null}
{
"agent": {
"deep-thinker": {
"description": "Agent that uses high reasoning effort for complex problems",
"model": "openai/gpt-5",
"reasoningEffort": "high",
"textVerbosity": "low"
}
}
}
```
***
## Creating Agents
You can create new agents using the CLI command:
```bash theme={null}
opencode agent create
```
This interactive command will:
1. Ask where to save the agent (global or project-specific)
2. Request a description of what the agent should do
3. Generate an appropriate system prompt and identifier
4. Let you select which tools the agent can access
5. Create a markdown file with the agent configuration
***
## Use Cases
Here are some common use cases for different agents:
* **Build agent**: Full development work with all tools enabled
* **Plan agent**: Analysis and planning without making changes
* **Review agent**: Code review with read-only access plus documentation tools
* **Debug agent**: Focused on investigation with bash and read tools enabled
* **Docs agent**: Documentation writing with file operations but no system commands
***
## Examples
Do you have an agent you'd like to share? [Submit a PR](https://github.com/anomalyco/opencode).
### Documentation Agent
```markdown title="~/.config/opencode/agents/docs-writer.md" theme={null}
---
description: Writes and maintains project documentation
mode: subagent
tools:
bash: false
---
You are a technical writer. Create clear, comprehensive documentation.
Focus on:
- Clear explanations
- Proper structure
- Code examples
- User-friendly language
```
### Security Auditor
```markdown title="~/.config/opencode/agents/security-auditor.md" theme={null}
---
description: Performs security audits and identifies vulnerabilities
mode: subagent
tools:
write: false
edit: false
---
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
```