OpenCode Subagents: Setup Guide + Background Mode (2026)

Julian Goldie — founder, AI Profit Boardroom
By Julian Goldie · 8 min read
Get The AI Profit Stack Join AIPB →
🎯 1,000+ done-for-you AI agent workflows 📅 4 live coaching calls every week 🛡️ 7-day refund + 30-day ROI guarantee 👥 3,400+ AI operators inside

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:

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:

AgentModeWhat it does
BuildprimaryThe default coding agent
PlanprimaryExplores and plans without editing normal project files
GeneralsubagentResearch and multi-step work with broad tool access; it cannot launch more subagents
ExploresubagentSearches 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:

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:

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

  1. 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.
  2. Review while you build. Keep coding in the parent while a reviewer subagent checks the last change with edit and shell access denied.
  3. 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.
  4. Cheaper models for grunt work. Give a "docs-writer" subagent a smaller model, and keep your best model for the parent.
  5. 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/:

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

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.

What members say about the AI Profit Boardroom

Read all 114 reviews on Skool →

★ 4.9 out of 5 from 114 member reviews on Skool

Yosuke Sato, AI Profit Boardroom member review (5 stars, paying member for 17 months): The best Skool course you get for AI! I have attended a few Skool courses before, but AI Profit Boardroom is the most active community and has great support from the management team, including Julian! You can get the most up-to-date information and practical implementations in this community. I highly recommend this!Mazzie T, AI Profit Boardroom member review (5 stars, paying member for 10 months): My mind is blown everyday with all the content and the incredible information. So much support and I love the personalised attention and quick responses. The community is great and people are very responsive and helpful.Rene Clayton, AI Profit Boardroom member review (5 stars, paying member for 9 months): The AI Profit Boardroom is a GAME CHANGER people. I could not be more thrilled that I joined!! So much support, more information than you can even consume, a huge value for what the small fee was. I have grown my business, my knowledge and my FUN!. SUCH a fantastic leader and group of humans. I am incredibly honored to be a part of this fantastic group of intelligent humans :-) THANK YOU!Arpiet Malpani, AI Profit Boardroom member review (5 stars, paying member for 8 months): Incredible learning from Julian and team. I started out in march and was able to build end to end SAAS with the help and learning from this group. I am incredibly thankful to Julian for crazy support and prompt response.James Grimm, AI Profit Boardroom member review (5 stars, paying member for 7 months): I asked Julian for help finding local business websites with little to no traffic. Julian was gracious in providing me my personal "how-to" video instruction. Wow, this is the pinnacle of customer service! I am just one of 3,400 subscribers and Julian took the time to help me personally. Thank you Julian for your assistance and outstanding custoemr support and care. James (Jim) GrimmNick Good, AI Profit Boardroom member review (5 stars, paying member for 4 months): I’m part of many AI groups and hands down, what Julian Goldie, has built here…the classroom trainings are amazing, but the community he has created is second to none (the community is worth the cost of joining!). If you’re looking to become the AI expert and build/create something meaningful, then AI Profit Boardroom is for YOU!Steven Gray, AI Profit Boardroom member review (5 stars, paying member for 4 months): Been in awhile. I’m a dad on a factory shift, not a tech bloke. Julian’s lot showed me how to use AI without drowning in tools. Avatar, voice, the workflow thinking — that’s what I needed. If you’re stuck on “where do I start,” this group’s worth it. I always read them.Steve Erickson, AI Profit Boardroom member review (5 stars, paying member for 4 months): I asked Julian a simple question, and he ended up creating a 10-minute video and a guide breaking down in extreme detail what I had asked. Amazing response!Rod Martin, AI Profit Boardroom member review (5 stars, paying member for 3 months): Julian is brilliant, and more prolific than I can keep up with (which is a great thing). His AgentOS is remarkable, and he is THE go-to guy for what you can really do (and not do) with the ever-increasing deluge of new AI upgrades and tools. HIGHLY recommend.Daniel Shulman, AI Profit Boardroom member review (5 stars, paying member for 4 months): Julian is very helpful. He doesn't try sell stuff you dont need and will give you a straight answer to your questions.Rj Herzog, AI Profit Boardroom member review (5 stars, paying member for 5 months): Top notch. If you are searching & searching thinking there is always something better out there.... You just found it. No need to look any further. Goldie covers it all & is super helpful. Can't beat the group either. Really can't recommend this group enough.Jermey Matthews, AI Profit Boardroom member review (5 stars, paying member for 6 months): While he has the capacity to do it, Julian is definitely doing the unscalable things to support his community.

Ready To Join The #1 AI Community?

Join 3,400+ entrepreneurs inside the AI Profit Boardroom. Get the Agent OS, 1,000+ plug-and-play AI agent workflows, daily Q&A with Julian and 4 live coaching calls every week.

Join The AI Profit Boardroom →

7-Day No-Questions Refund • 30-Day ROI Guarantee

← Back to all posts