Subagent

What it is

A subagent is an AI assistant that runs in its own session, invoked by a parent agent (or directly by you) to handle a focused task. Unlike a primary agent, a subagent does not sit in the main conversation loop. It spawns, does its work, and returns results. Think of it as a specialist you hire for a job — they work independently and report back.

What it is in real OpenCode terms

In OpenCode, subagents are specialized assistants that primary agents launch via the Task tool. They create child sessions separate from the main conversation. You can also invoke them directly by typing @ followed by the agent name.

OpenCode ships with three built-in subagents:

When a primary agent delegates work to a subagent, it creates a child session. You can navigate between sessions using keyboard shortcuts:

• Leader+Down — Jump into a subagent session
• Right / Left — Cycle between sibling subagent sessions
• Up — Return to the parent session

Why it exists

Primary agents handle the main conversation, but not every task belongs in that context. A primary agent trying to explore an entire codebase, research external docs, and write code simultaneously loses focus and burns context window on noise. Subagents solve this by:

• Isolating context — Each subagent gets its own session. Research results don't clutter the main conversation.
• Running in parallel — Multiple subagents can work simultaneously on different parts of a problem.
• Limiting scope — A read-only Explore subagent cannot accidentally modify files while investigating.
• Enabling specialization — A Scout subagent is optimized for external research. An Explore subagent is optimized for codebase traversal. Each does one thing well.

Anatomy / main elements

Subagents share the same configuration fields as primary agents, with these key distinctions:

The nesting depth of subagents is controlled by subagent_depth in your config (default: 1). This prevents infinite recursion where subagents spawn subagents indefinitely.

Where it lives

Custom subagent configurations live in the same locations as primary agents:

Or inline in opencode.json:

{
  "agent": {
    "test-writer": {
      "description": "Writes unit tests for a given module",
      "mode": "subagent",
      "model": "anthropic/claude-sonnet-4",
      "prompt": "You write thorough unit tests.",
      "permissions": {
        "read": true,
        "edit": true,
        "bash": false
      }
    }
  }
}

The subagent_depth config controls how many levels deep subagents can nest:

{
  "subagent_depth": 1
}

How to create one

1. Decide what focused task this subagent handles (e.g., writing tests, exploring a codebase, researching docs).
2. Create a Markdown file in .opencode/agents/ with mode: subagent in the frontmatter.
3. Write a focused system prompt. Subagents work best with narrow, clear instructions.
4. Set permissions appropriately. A research-only subagent should have edit: false.
5. The subagent becomes available for the primary agent to invoke via the Task tool, or you can call it with @test-writer.

Minimal example

Create a subagent that only researches documentation and returns findings:

---
name: doc-researcher
description: Researches external documentation and returns structured findings
mode: subagent
permissions:
  read: true
  edit: false
  bash: false
---

You are a documentation researcher. When given a topic or library name:

1. Search for official documentation
2. Find the most relevant pages
3. Extract key API details, gotchas, and examples
4. Return findings as structured markdown with source URLs

Do not write code. Do not modify files. Only gather and summarize information.

Save as .opencode/agents/doc-researcher.md. A primary agent can now invoke it with the Task tool, or you can type @doc-researcher research the Prisma ORM migration API.

Related concepts

Common confusion