Field notes · AI agents, Hermes & Claude Code By Julian Goldie

OpenCode Subagents: Setup, Permissions and What Changed in v2.3

An operator guide to OpenCode subagents after the v2.3.0 switch to background runs.

Get The AI Profit Stack Join AIPB →
  • 01 1,000+ done-for-you AI agent workflows
  • 02 5 live coaching calls / week with me
  • 03 7-day refund, cancel anytime
  • 04 3,400+ AI operators inside

OpenCode subagents are named helper agents that your main agent launches into their own child sessions, and since v2.3.0 they always run in the background while you keep working.

Get Your Backlink Gameplan →Try Polar Rank Free for 3 Days →

This operator guide covers the built-in subagents, how to write your own in Markdown or JSONC, how to lock their permissions down, and the release changes that matter this week.

If you want agents like these running your SEO and content work, get your Backlink Gameplan and see how Goldie Agency uses them, or try Polar Rank free for 3 days.

Everything below is taken from OpenCode's agents documentation and its official release notes.

What changed in v2.3.0 and v2.3.1

The v2.3.0 release made background subagents the default: they return immediately, keep running, and report back whenever they become idle.

The change landed in pull request 63382, and the parent now gets each child's session ID straight away, so you can run several at once.

The same release fixed a subtle problem: if a subagent goes idle while its own background work is still running, its report now says it is still running, so the parent waits for the final answer.

Then v2.3.1 changed shell timeouts: a command still running when its timeout expires now moves to the background instead of being killed, and a foreground timeout: 0 now means the default 120 seconds.

It also made background compaction the default, which you can switch off with compaction.background: false.

The built-in subagents

AgentModeWhat it does
General (general)subagentResearch and multi-step work with broad tool access; cannot launch more subagents
Explore (explore)subagentSearches and reads code or web sources without editing files
Build (build)primaryThe default coding agent
Plan (plan)primaryExplores and plans without editing normal project files

V2 has no built-in scout agent, so any guide that tells you to call one is out of date.

Where subagent files live

~/.config/opencode/agents/<name>.md     # every project
.opencode/agents/<name>.md              # this project only
.opencode/agents/team/reviewer.md       # becomes team/reviewer

OpenCode discovers .opencode folders from your current directory up to the project root, and a nested path becomes part of the agent ID.

Write your first subagent in Markdown

The frontmatter holds the settings, and the body becomes the agent's system prompt.

Get Your Backlink Gameplan →Try Polar Rank Free for 3 Days →

---
description: Checks database migrations for unsafe changes
mode: subagent
model: anthropic/claude-sonnet-5-5#high
steps: 12
permissions:
  - action: edit
    resource: "*"
    effect: deny
  - action: shell
    resource: "*"
    effect: deny
---

Read every new migration file. Flag dropped columns, missing
indexes and long table locks. Report in severity order with
file and line references. Do not edit anything.

Save it as .opencode/agents/migration-check.md, then ask your main agent: "Use the migration-check subagent on my latest changes."

The description matters more than it looks, because OpenCode shows it to the model when it decides which subagent to launch.

📞 Want agents like this running your SEO? Get your Backlink Gameplan and we will show you how Goldie Agency uses subagents for audits and content checks, or try Polar Rank free for 3 days. Backlink Gameplan or try Polar Rank free for 3 days

The same subagent in JSONC

If you prefer config files, define agents under agents in any OpenCode configuration file.

{
  "$schema": "https://opencode.ai/config.json",
  "agents": {
    "migration-check": {
      "description": "Checks database migrations for unsafe changes",
      "mode": "subagent",
      "system": "Flag unsafe migrations. Do not edit files.",
      "permissions": [
        { "action": "edit", "resource": "*", "effect": "deny" }
      ]
    }
  }
}

Modes: primary, subagent or all

ModeBehaviour
primaryRuns as the main agent; the default for a new custom agent
subagentRuns only in a child session through the subagent tool
allCan run either way

Forgetting to set mode: subagent is the most common reason a custom agent never gets launched, because new agents default to primary.

Control which subagents a parent may launch

The parent's subagent permission decides which children it may start; the child then uses its own permissions. The rules follow OpenCode's permissions system, where the last matching rule wins.

{
  "agents": {
    "orchestrator": {
      "permissions": [
        { "action": "subagent", "resource": "*", "effect": "deny" },
        { "action": "subagent", "resource": "migration-check", "effect": "allow" },
        { "action": "subagent", "resource": "explore", "effect": "allow" }
      ]
    }
  }
}

Put broad rules first and exceptions after them, or the broad rule will override your exception.

🔥 Want ready-made agent setups for your business? Inside the AI Profit Boardroom you get step-by-step video trainings, the installable Agent OS, four coaching calls a week and 3,400+ members. Members get agent workflows they can install and adapt. → Join the AI Profit Boardroom

Get Your Backlink Gameplan →Try Polar Rank Free for 3 Days →

Operator settings worth knowing

  • steps: a cap on model steps; on the last step tools are removed and the agent summarises.
  • model: provider/model#variant; with none set, a subagent inherits the parent session's model.
  • hidden: true: hides an agent from listings and the subagent catalogue, but it is visibility, not security.
  • disabled: true: removes a built-in or custom agent at that point in config loading.
  • color: a six-digit hex value for the UI.

Running several subagents at once

Because children now run in the background, you can ask for three jobs in one prompt: "Use explore to map the auth code, migration-check on the new migrations and general to draft release notes."

Each returns a session ID immediately, and reports arrive as each one goes idle.

Keep each subagent narrow, with a clear description, so the parent picks the right one every time.

Common mistakes

  • Using V1 fields such as tools, permission or maxSteps; OpenCode's migration guide explains how old files are read.
  • Relying on hidden to stop an agent doing something; use permissions instead.
  • Giving the General subagent work that needs more subagents; it cannot launch any.
  • Forgetting that shell commands now move to the background on timeout; check the tools docs if a long job seems to vanish.

Where to go from here

Once one read-only helper is working, add a second with a different job, and let the parent run both in the background.

Keep a short README in .opencode/agents explaining what each helper does, so teammates know which one to call.

For agent workflows built around business tasks rather than code, see the AI Profit Boardroom.

Get Your Backlink Gameplan →Try Polar Rank Free for 3 Days →

FAQ: OpenCode Subagents

Do OpenCode subagents run in the background?

Yes. Since v2.3.0 they always run in the background, return their session ID immediately and report to the parent when they go idle.

Which subagents come built in?

General, for research and multi-step work (it cannot launch more subagents), and Explore, which searches and reads without editing files.

How do I create a custom OpenCode subagent?

Add a Markdown file to .opencode/agents/ with mode: subagent and a clear description in the frontmatter, or define it under agents in opencode.jsonc.

Can a subagent use a different model?

Yes, set model as provider/model#variant; without it, the subagent inherits the parent session's model.

How do I stop a parent launching certain subagents?

Add subagent permission rules on the parent, denying * and then allowing specific agent IDs, because the last matching rule wins.

📺 Video notes + links to the tools 👉

🎥 Learn how I make these videos 👉

🆓 Get a FREE AI Course + Community + 1,000 AI Agents 👉

About Julian

I'm Julian Goldie, an SEO entrepreneur, author and founder of the AI Profit Boardroom, which has 3,400+ members.

I help business owners scale with AI agents, automation and SEO.

  • I've built a 7-figure SEO and link building agency, Goldie Agency, with a team of 70+ SEO experts.
  • I've grown a YouTube channel to 400,000+ subscribers.
  • I wrote "Link Building Mastery".
  • My Udemy courses have taught over 29,000 students.

→ Get my best AI training inside the AI Profit Boardroom

Start with one narrow, read-only helper and you will see why OpenCode subagents change how you work; to put agents to work on your SEO, get your Backlink Gameplan, or try Polar Rank free for 3 days.

§ Member reviews

What members say about the AI Profit Boardroom

Read the member reviews on Skool →
Ahmad Bukhari: Julian doesn't gatekeep. That's why I'd recommend this group. He's extremely active here, sharing what's working right now and jumping in to help anyone who's stuck. If he can give it away, he does. He keeps the vibe positive and pushes everyone to help each other. His challenges reward members for getting people unstuck, so the whole room shares knowledge, not just him. Want a generous, positive place to learn AI and actually use it? This is it. Thanks Julian!
Ahmad Bukhari
Julian doesn't gatekeep. That's why I'd recommend this group. He's extremely active here, sharing what's working right now and jumping in to help anyone who's stuck. If he can give it away, he does. He keeps the vibe positive and pushes everyone to help each other. His challenges reward members for getting people unstuck, so the whole room shares knowledge, not just him. Want a generous, positive place to learn AI and actually use it? This is it. Thanks Julian!

Still a paying member after 1 month

Jay Parsons: There are so many helpful members in this amazing community ready to help out with suggestions and solutions whenever someone asks a question. I am amazed at the progress I have made in learning AI. I came here to learn how to use AI better and apply what I learned to my business. I am learning so much more than I even dreamed of. I have built an Agentic OS and use it every day, and I have no background in coding. There are an incredible amount of useful tutorials on everything AI.
Jay Parsons
There are so many helpful members in this amazing community ready to help out with suggestions and solutions whenever someone asks a question. I am amazed at the progress I have made in learning AI. I came here to learn how to use AI better and apply what I learned to my business. I am learning so much more than I even dreamed of. I have built an Agentic OS and use it every day, and I have no background in coding. There are an incredible amount of useful tutorials on everything AI.

Still a paying member after 11 months

Brian O'Connor: At 47, with 30 years in sales and finance, embracing AI was exciting but overwhelming. While building a business to help others adopt AI, I found myself chasing tools and fearing I was falling behind. Julian and the AI Profit Boardroom helped me refocus through practical, personalized advice and a supportive community. I now feel more confident adapting to change while staying focused on my goals. Thank you, Julian, for bringing this community together!
Brian O'Connor
At 47, with 30 years in sales and finance, embracing AI was exciting but overwhelming. While building a business to help others adopt AI, I found myself chasing tools and fearing I was falling behind. Julian and the AI Profit Boardroom helped me refocus through practical, personalized advice and a supportive community. I now feel more confident adapting to change while staying focused on my goals. Thank you, Julian, for bringing this community together!

Still a paying member after 2 months

Neil Martin: This is a truly amazing community, thanks in no small part to Julian's prodigious output and tireless efforts to provide value to his subscribers. Nothing is too much trouble for him. If you ask a question it gets answered in short order usually with a custom video. I have been in quite a few groups and this level of service is unparalleled. If you are serious about getting an AI education, you need to be in this group!
Neil Martin
This is a truly amazing community, thanks in no small part to Julian's prodigious output and tireless efforts to provide value to his subscribers. Nothing is too much trouble for him. If you ask a question it gets answered in short order usually with a custom video. I have been in quite a few groups and this level of service is unparalleled. If you are serious about getting an AI education, you need to be in this group!

Still a paying member after 7 months

Crystal Hill: AIPB has inspired me to go beyond learning AI as individual tools, skills, and prompts, and start thinking in terms of larger systems. What I really appreciate is how responsive Julian is and how quickly the material evolves with the technology. You’re being exposed to the right tools and ideas as they emerge. AIPB has given me the confidence to learn, experiment, build, and think much bigger about what’s really possible with AI.
Crystal Hill
AIPB has inspired me to go beyond learning AI as individual tools, skills, and prompts, and start thinking in terms of larger systems. What I really appreciate is how responsive Julian is and how quickly the material evolves with the technology. You’re being exposed to the right tools and ideas as they emerge. AIPB has given me the confidence to learn, experiment, build, and think much bigger about what’s really possible with AI.

Still a paying member after 5 months

Maurice Morrison: AI Profit Board Room has been a game-changer. The insights are practical, timely, and focused on turning AI into real business results—not just theory or hype. The community is supportive, the guidance is clear, and I leave every session with ideas I can actually apply. If you’re serious about using AI to grow smarter and move faster, this is absolutely worth joining.
Maurice Morrison
AI Profit Board Room has been a game-changer. The insights are practical, timely, and focused on turning AI into real business results—not just theory or hype. The community is supportive, the guidance is clear, and I leave every session with ideas I can actually apply. If you’re serious about using AI to grow smarter and move faster, this is absolutely worth joining.

Still a paying member after 2 months

Jeremy Murdock: I have truly enjoyed my experience here. The group of folks on the calls is quite diverse and I find it comforting to know that I am not the only one going through the changes that are happening at a faster and faster pace. I have chosen to embrace the change and go full force into integrating AI and what I have learned form the group and Julian. I am also impressed and appreciative that he actually takes the time to help with challenges I have along the way and get involved personally!
Jeremy Murdock
I have truly enjoyed my experience here. The group of folks on the calls is quite diverse and I find it comforting to know that I am not the only one going through the changes that are happening at a faster and faster pace. I have chosen to embrace the change and go full force into integrating AI and what I have learned form the group and Julian. I am also impressed and appreciative that he actually takes the time to help with challenges I have along the way and get involved personally!

Still a paying member after 10 months

Michael Lovitch: I have been a part of a million ai groups in Skool for years now. They are all okay and have helped, but usually they get out of date and don't offer real service to help you through especially at the beginning. This group is different, Julian actually answers questions which is crazy! And although ai marketing moves at the speed of light, they stay current and actually help you keep up… Highly recommended!
Michael Lovitch
I have been a part of a million ai groups in Skool for years now. They are all okay and have helped, but usually they get out of date and don't offer real service to help you through especially at the beginning. This group is different, Julian actually answers questions which is crazy! And although ai marketing moves at the speed of light, they stay current and actually help you keep up… Highly recommended!

Still a paying member after 3 months

Hoebing Lo: I don't know of any other community that is as active and sharing. Julian is a star and he answers so many questions in lightning speed. If you want a great place to start with AI here it is. No question too simple. No workflow too complicated. The community is about action and results not education so if you are looking to win at AI then come for the ride of a lifetime!
Hoebing Lo
I don't know of any other community that is as active and sharing. Julian is a star and he answers so many questions in lightning speed. If you want a great place to start with AI here it is. No question too simple. No workflow too complicated. The community is about action and results not education so if you are looking to win at AI then come for the ride of a lifetime!

Still a paying member after 5 months

Darren Wagstaff: Very responsive... great personal support (not an ai chat bot). Very clear straight forward trainings in easy to understand actionable language. I'm in numerous Skool groups but this one has the most human and real community by far. No question gets ignored. You never fell like just another number. It's great to see so many members getting great results with Ai.
Darren Wagstaff
Very responsive... great personal support (not an ai chat bot). Very clear straight forward trainings in easy to understand actionable language. I'm in numerous Skool groups but this one has the most human and real community by far. No question gets ignored. You never fell like just another number. It's great to see so many members getting great results with Ai.

Still a paying member after 2 months

Rod Martin: 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.
Rod Martin
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.

Still a paying member after 5 months

Yosuke Sato: 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!
Yosuke Sato
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!

Still a paying member after 19 months

⚑ Next step

Ready to run AI agents that actually do the work?

Join 3,400+ operators inside the AI Profit Boardroom. Get 1,000+ plug-and-play AI agent workflows, 5 coaching calls a week, and a community that holds you accountable.

Join The AI Agent Community →

7-day no-questions refund · Cancel anytime

Found this useful? Get more of this site in your Google.

One tap adds us as a preferred source — Google then shows you our posts more often in Search, Top Stories, and AI Overviews.

← Back to all posts