OpenCode: OpenCode Agent Mode
Last updated: 2026-08-31
--- title: OpenCode Agents description: Understand the agent system with built-in agents, custom agents, and subagent configuration order: 13 lang: en
Agents are specialized AI assistants in OpenCode, each configurable with independent prompts, models, tools, and permissions.
1. What You Will Learn
- Agent types: primary and subagent
- Built-in agents
- Custom agent configuration
- Agent usage methods
2. Agent Types
| Type | Description | Switching |
|---|---|---|
| Primary agent | Main assistant for direct interaction | Tab key |
| Subagent | Specialized assistant called by primary | @agent_name or auto-called |
3. Built-in Agents
| Agent | Type | Description |
|---|---|---|
| Build | Primary | Default agent with all tools enabled |
| Plan | Primary | Analysis and planning only—edits/bash set to ask |
| General | Subagent | Full tools, can modify files |
| Explore | Subagent | Read-only, cannot modify files |
System agents (hidden): Compaction, Title, Summary
4. Switching and Calling Agents
- Switch primary: Tab / Shift+Tab
- Call subagent:
@explore find all Redis usage - Navigate sub-sessions: Leader+→ / Leader+← / Leader+↑
5. Custom Agent Configuration
JSON config:
JSON
{
"agent": {
"code-reviewer": {
"description": "Reviews code for best practices",
"mode": "subagent",
"model": "anthropic/claude-sonnet-4-20250514",
"prompt": "You are a code reviewer. Focus on security and performance.",
"tools": { "write": false, "edit": false }
}
}
}
Markdown file:
Place in ~/.config/opencode/agents/ (global) or .opencode/agents/ (project). Filename becomes the agent name.
6. Configuration Options
| Option | Description |
|---|---|
description |
Agent function description (required) |
mode |
primary / subagent / all |
model |
Specify model (provider/model-id) |
prompt |
System prompt, supports {file:./path} |
temperature |
Output randomness (0.0-1.0) |
steps |
Maximum iteration count |
tools |
Tool access permissions |
permission |
Fine-grained permission control |
hidden |
Hide from @ menu |
color |
UI display color |
disable |
Disable agent |
7. Quick Create
BASH
opencode agent create
Interactive guided agent creation.
❓ FAQ
Q When to use Plan instead of Build?
A When you want AI to analyze and advise without modifying files. Plan's edit/bash permissions are set to ask.
Q Can subagents call subagents?
A Yes, via Task tool. Avoid circular calls. Use permission.task to control.
📖 Summary
- Agents: primary (Tab switch) and subagent (@ call)
- 4 usable built-in + 3 system agents
- JSON or Markdown configuration
- Specify model, prompt, tools, temperature per agent
- Quick create with
opencode agent create
📝 Exercises
-
Basic: Switch between Build and Plan agents in TUI using Tab.
-
Intermediate: Create a read-only code review agent with low temperature and appropriate tool permissions.
-
Advanced: Design a complete agent system (primary + subagents) for a full development workflow.
