OpenCode subagents are helper agents your main OpenCode agent launches into their own child sessions, each with fresh context, its own model and its own permissions. Since OpenCode v2.3.0 (released 13 November 2026) they always run in the background: the parent gets their session ID straight away, keeps working, and receives a report whenever a subagent goes idle. This guide shows how to set them up, the built-in ones you already have, and real ways to use them.
📺 Watch: OpenCode Just Made AI Coding Automation INSANE!
🔥 Get the Agent OS as a free bonus: AI Profit Boardroom members get the full Agent OS zip, prompt libraries, daily tutorials and weekly live coaching calls. → Get inside
Everything here comes from the OpenCode agents documentation and the official release notes for v2.3.0 and v2.3.1.
What Changed for OpenCode Subagents in November 2026
Two releases changed how subagents feel day to day:
- v2.3.0, 13 November 2026: background subagents by default. Subagents now return immediately, continue in the background, and report back whenever they become idle. You can keep working in the parent session while several subagents run at once. 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 report instead of treating a partial answer as done.
- v2.3.1, 18 November 2026: timed-out shell commands keep running. A shell command still running when its timeout expires now moves to the background instead of being killed, so long builds and test runs finish and report back. A foreground timeout of 0 now means the default 120 seconds. Background compaction is also on by default, so your next prompt doesn't wait for a session summary.
Together these make subagents far more useful for long jobs: a subagent can kick off a full test run, keep going while it runs, and report when everything is done.
Want ready-made agent setups? The AI Profit Boardroom is where Julian Goldie shares the agent workflows he runs every day, with weekly live coaching calls.
The Built-In Agents You Already Have
OpenCode ships with four visible agents, two primary and two subagents:
| Agent | Mode | What it does |
|---|---|---|
| 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 cannot launch more subagents |
| Explore | subagent | Searches and reads code or web sources without editing files |
You can use these right away. Ask your main agent something like "use the explore subagent to find every place we call the payments API" and it will launch one in the background.
📺 Watch: Omniroute + OpenCode: 100% FREE AI Coding Setup!
How to Create Your Own OpenCode Subagents
The simplest way is a Markdown file. Save it globally or inside a project:
- Global, for every project:
~/.config/opencode/agents/NAME.md - Project only:
.opencode/agents/NAME.md
The frontmatter sets the options and the body becomes the agent's system prompt. Here is a read-only code reviewer, based on the example in the docs:
---
description: Reviews changes for correctness and regressions
mode: subagent
model: anthropic/claude-sonnet-5-5#high
permissions:
- action: edit
resource: "*"
effect: deny
- action: shell
resource: "*"
effect: deny
---
Review the current changes. List findings in severity order
with file and line references.
Then ask your primary agent: "Use the reviewer subagent to review my current changes."
A few details worth knowing:
- mode can be primary, subagent or all. A new custom agent defaults to primary, so set subagent if you only want it launched by another agent.
- description matters. OpenCode shows it to the model choosing which agent to launch, so write it like a job title.
- model is optional. Without it, a subagent inherits the parent session's model.
- Nested folders become part of the ID, so
.opencode/agents/team/reviewer.mdbecomes team/reviewer.
You can also define agents in your OpenCode config file under an agents section; the docs show the same fields there.
Control Which Subagents Can Run
The parent agent's permissions decide which subagents it may launch. The child then uses its own permissions. That lets you build an orchestrator that can only call the agents you trust. In Markdown frontmatter, an orchestrator that may only launch the reviewer looks like this:
---
description: Coordinates work and delegates reviews
mode: primary
permissions:
- action: subagent
resource: "*"
effect: deny
- action: subagent
resource: reviewer
effect: allow
---
Plan the work, then ask the reviewer subagent to check it.
Rules are read in order, so the general deny comes first and the specific allow refines it.
📺 Watch: How to Rank #1 with Hermes AI SEO Subagents!
Real Ways to Use OpenCode Subagents
- Parallel research. Launch two explore subagents at once: one maps the database code, the other reads the API docs. You keep planning in the parent.
- Review while you build. Keep coding in the parent while a reviewer subagent checks the last change with edit and shell access denied.
- Long test runs. Since v2.3.1, a subagent can start a slow test suite that outlives its timeout. The command moves to the background and the report arrives when it finishes.
- Cheaper models for grunt work. Give a "docs-writer" subagent a smaller model, and keep your best model for the parent.
- Safe sandboxes. Give an "investigator" subagent read access only, so it can never change files while it digs through a bug.
If you use OpenCode alongside other agents, the same pattern works in the Agent OS: one lead agent hands focused jobs to specialists. To choose which model each subagent should use, compare options on Goldie Bench.
A Starter Team of Three Subagents
If you want a setup you can copy today, start with three small agents in .opencode/agents/:
- reviewer.md: mode subagent, edit and shell denied, a prompt that lists findings by severity with file and line references.
- tester.md: mode subagent, shell allowed, a prompt that runs the test suite, then summarizes failures with the exact command to reproduce each one.
- docs.md: mode subagent, a cheaper model, a prompt that updates the README and changelog after a feature lands.
Then work with the default Build agent as usual and hand off as you go: "tester, run the full suite", "reviewer, check this diff", "docs, update the changelog". Because each one runs in the background, you can send all three and keep coding while their reports come in. Keep the descriptions short and specific so the parent knows exactly which helper to pick for each job.
Troubleshooting OpenCode Subagents
- The parent never uses my subagent. Improve the description so the model knows when to pick it, or name it in your prompt.
- My subagent can't be launched. Check the parent's subagent permissions; a deny rule may block it.
- It uses the wrong model. Set model in the subagent's frontmatter; otherwise it inherits the parent's.
- The answer looks unfinished. Since v2.3.0, a subagent's report says when its own background work is still running. Wait for the final report.
- A build got killed at 120 seconds. Update to v2.3.1 or later, where timed-out shell commands move to the background instead.
OpenCode Subagents vs Other Coding Agents
Most modern coding agents now let a lead agent delegate to helpers. What stands out in OpenCode is how plain the setup is: one Markdown file per agent, permission rules you can read top to bottom, and background runs by default since 13 November 2026. If you already write agent instructions for other tools, moving them into OpenCode is mostly a copy and paste.
Want to see these workflows in action and copy them? Join the AI Profit Boardroom for step-by-step agent tutorials and weekly live calls.
FAQ
What are OpenCode subagents?
They are agents that run only in a child session through OpenCode's subagent tool, with fresh context and their own model and permissions. Your primary agent launches them and gets a report back.
Do OpenCode subagents run in parallel?
Yes. Since v2.3.0 they always run in the background, so several can run at once while you keep working in the parent session.
Can a subagent launch other subagents?
It depends on its permissions. The built-in General subagent cannot launch more subagents. Your own agents follow whatever subagent rules you give them.
Where do I put a custom subagent file?
Use ~/.config/opencode/agents/ for every project, or .opencode/agents/ inside one project, with mode set to subagent in the frontmatter.











