OpenCode subagents are helper agents that your main OpenCode agent can hand a task to. Each one works in its own child session with fresh context, then reports back. Since OpenCode v2.3.0 on 13 November 2026, subagents run in the background by default, so you can keep working while several of them run at once. In the video below I show an OpenCode plugin running six AI agents together. Below I’ll show how subagents work and how to make your own.
Key takeaways
- Subagents run in their own child sessions with fresh context.
- Since v2.3.0 (13 Nov 2026) they always run in the background and report back when idle.
- Built-in subagents: General and Explore.
- Make your own with a Markdown file in
.opencode/agents/andmode: subagent. - Want the full agent setup done with you? Join the AI Profit Boardroom.
What are OpenCode subagents?
In OpenCode, an agent is a named profile: a system prompt, a model, permissions and display details. The OpenCode agents docs describe three modes:
| Mode | What it does |
|---|---|
| primary | Runs as the main agent for a session (the default for a new custom agent) |
| subagent | Runs only in a child session, launched through the subagent tool |
| all | Can run either way |
A subagent gets a fresh context in its own child session. That keeps your main conversation clean: the subagent does the digging, and your main agent only sees its report.
What changed in OpenCode v2.3.0 and v2.3.1
The v2.3.0 release (13 November 2026) made background subagents the default:
- Subagents now return their session ID immediately, keep working in the background, and report to the parent whenever they go idle.
- You can keep working in the parent session while several subagents run at the same time.
- If a subagent goes idle while its own background work is still running, its report now says so, so the parent waits for the final answer instead of treating a partial one as done.
- Agents are now told when their session is a fork.
Then v2.3.1 (18 November 2026) added another background upgrade: a shell command still running when its timeout expires now moves to the background instead of being killed, so long builds and test runs can finish and report back.
Want help running OpenCode subagents in your business? Inside the AI Profit Boardroom you get the Agent OS — Hermes, OpenClaw, OpenCode, Claude and Codex in one place — plus step-by-step Hermes training and four live coaching calls a week.
Want a plan for your business first? Claim your free strategy session.
Join the AI Profit Boardroom →Claim Your Free SEO Strategy Session →
The built-in OpenCode subagents
| Agent | Mode | What it’s for |
|---|---|---|
| Build | primary | The default coding agent |
| Plan | primary | Explores and plans without editing normal project files |
| General | subagent | Research and multi-step work with broad tool access (it can’t launch more subagents) |
| Explore | subagent | Searches and reads code or web sources without editing files |
So out of the box you can ask Build to “use the explore subagent to find every place we call the payments API” and keep chatting while it works.
How to create your own OpenCode subagent
The quickest way is a Markdown file. Save it in your project at .opencode/agents/reviewer.md, or globally at ~/.config/opencode/agents/reviewer.md:
---
description: Reviews current changes without editing files
mode: subagent
permissions:
- action: edit
resource: "*"
effect: deny
---
Review the current changes. List findings in severity order
with file and line references.
The Markdown body becomes the subagent’s system prompt. Then just ask your main agent: “Use the reviewer subagent to review my current changes.”
Always add a description. OpenCode shows it to the model when it decides which subagent to launch, so a clear description means the right helper gets picked.
Give a subagent its own model
A subagent can use a different model from your main session. Set model in the frontmatter using provider/model, with an optional #variant. If you leave it out, the subagent inherits the parent session’s model.
A common setup: a strong model for your main Build agent, and a cheaper, faster model for an Explore-style research subagent that reads lots of files.
Want this set up for you instead of doing it yourself? Claim your free strategy session →
Control which subagents can run
Permissions are an ordered list of rules, and the last matching rule wins. The subagent action controls which child agents a parent may launch. For example, an orchestrator agent that may only call your reviewer:
{
"agents": {
"orchestrator": {
"permissions": [
{ "action": "subagent", "resource": "*", "effect": "deny" },
{ "action": "subagent", "resource": "reviewer", "effect": "allow" }
]
}
}
}
The child subagent then uses its own configured permissions, so a read-only reviewer stays read-only even if the parent can edit.
Good jobs for OpenCode subagents
- Code review of your current changes while you keep building.
- Codebase search with Explore: “find every place we handle refunds”.
- Research with General: compare two libraries and summarise.
- Tests: one subagent runs and reads the test suite while another fixes a bug.
- Docs: a writer subagent updates the README after a change.
My verdict on OpenCode subagents
Background subagents by default is a real upgrade. Your main chat stays clean, several helpers can work at once, and long shell jobs no longer die on a timeout. Start with the built-in Explore subagent, then add one custom reviewer. That’s the fastest way to see what OpenCode subagents can do.
About Julian Goldie
I’m Julian Goldie — founder of Goldie Agency and the AI Profit Boardroom. I test new AI agents almost every day for 432K+ YouTube subscribers and run Hermes, OpenClaw, OpenCode, Claude and Codex side by side in my own Agent OS. Claim your free strategy session or join the AI Profit Boardroom.
FAQ: opencode subagents
What are OpenCode subagents?
Helper agents that run in their own child sessions with fresh context and report back to your main agent.
Do OpenCode subagents run in the background?
Yes. Since v2.3.0 (13 November 2026) subagents always run in the background, return their session ID immediately and report when they go idle.
How do I create an OpenCode subagent?
Add a Markdown file in .opencode/agents/ with a description and mode: subagent in the frontmatter. The body becomes its system prompt.
Can a subagent use a different model?
Yes. Set model in its config as provider/model. Without it, the subagent inherits the parent session’s model.
What subagents come built in?
General, for research and multi-step work, and Explore, for searching and reading code without editing files.
Can I stop an agent launching subagents?
Yes. Use permission rules with the subagent action to deny all, then allow only the subagents you want.
Ready to put Hermes to work in your business? Join the AI Profit Boardroom for the Agent OS, setup training and daily updates.
Or claim your free strategy session and we’ll map out your setup.
Starting from zero? Get the free AI course and community.
Join the AI Profit Boardroom →Claim Your Free SEO Strategy Session →Get the FREE AI Course + Community →
Related reading
Last updated November 2026. This page is a living guide to opencode subagents — the facts here move fast and it is updated as they do.
