12. OpenCode Agents and Subagents

12.1 Agent types

OpenCode supports primary agents and subagents.

Primary agent

The main agent you interact with directly.

Subagent

A specialized agent that can be delegated work.

12.2 Built-in concepts

OpenCode's documented workflows include primary agents such as:

• Build
• Plan

and specialized/subagent workflows.

Exact built-in agents and defaults can change between OpenCode versions, so inspect the current installation and official documentation.

12.3 Switching primary agents

The official documentation describes using the Tab key to cycle through primary agents during a session.

Use the current OpenCode keybindings/help for your installation.

12.4 Invoking subagents

Subagents can be invoked automatically when appropriate and can also be manually mentioned with @.

Example:

@general help me find the authentication implementation

The exact available subagent names depend on the installed/configured agents.

12.5 Custom agent

Create:

.opencode/agents/reviewer.md

Example using the current documented Markdown agent format:

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

# Code Reviewer

Review the current changes.

Focus on:

- Correctness
- Bugs
- Security
- Performance
- Maintainability
- Test coverage

Do not modify files.

Return:
1. Finding
2. Severity
3. File
4. Explanation
5. Recommendation

The Markdown filename becomes the agent name.

12.6 Read-only reviewer

A reviewer should normally not need editing permission.

Conceptually:

Reviewer
 |
 +--> Read
 +--> Search
 +--> Analyze
 |
 X--> Edit

This separation reduces accidental modifications.

12.7 Testing agent

Example:

---
description: Runs and analyzes tests
mode: subagent
permission:
  edit: deny
---

# Testing Agent

Analyze the current implementation.

Identify missing tests.

Run relevant tests.

Report:
- Tests executed
- Failures
- Likely causes
- Missing coverage

12.8 Security agent

Example:

---
description: Performs a security review
mode: subagent
permission:
  edit: deny
---

# Security Agent

Review the current code for:

- Authentication
- Authorization
- Secrets
- Input validation
- Injection risks
- File access
- Dependency risks
- Error disclosure

Do not modify files.

12.9 Agent delegation

A useful team model:

Main Agent
 |
 +--> Architect
 +--> Explorer
 +--> Tester
 +--> Reviewer
 +--> Security
 +--> Documentation

The main agent coordinates; specialized agents focus on specific tasks.

Exercise

Create:

architect.md
tester.md
reviewer.md
security.md
documentation.md

Decide for each:

• Primary or subagent?
• Model?
• Tools?
• Permissions?
• Expected output?