Skip to content
agents.cli

Subagents

What a subagent is

Section titled “What a subagent is”

A subagent is an isolated worker the main agent spawns to do a discrete task. It runs its own loop — reading files, running searches, making tool calls — in a fresh context window that doesn’t touch yours. When it finishes, the parent receives only a summary. Whatever the subagent read, tried, backtracked through, or threw away never lands in your conversation.

Why you’d want one

Section titled “Why you’d want one”

You asked the agent to debug a flaky test. Forty messages later, it’s read seventeen files, tried four hypotheses, run the test six times with different env vars, and finally pinned it down. Now you want to actually fix the test and ship the feature you originally came in to build — and your context window is full of debug noise. Stack traces. Trial fixes. Failed reproductions. The agent is now somewhat less coherent than it was an hour ago, because half its context is rabbit-hole.

The cost wasn’t the debugging. It was that the debugging happened in the same window as the rest of your work. Everything the agent learned to find the bug is now polluting the context it needs to write the fix.

That’s the gap subagents close. Hand the debug task to a subagent: it spawns fresh, burns through whatever context it needs, and returns “the bug is in auth/session.ts:142, the session token is being mutated by the middleware before the test asserts on it.” One sentence back. Forty messages of investigation: gone. Your main context stays clean for the actual fix.

Real-world examples of what teams use subagents for:

  • Codebase exploration — “find every place we call the auth API and how each one handles errors.” Dozens of file reads collapse into a one-paragraph map.
  • Code review — give a subagent the diff plus a checklist (security, perf, naming) and let it return findings. The 200-line diff and 50 lines of analysis don’t enter your conversation.
  • Verification / audit — “go check that every endpoint in the new router has a corresponding test.” Returns a list of gaps, not a tour of the test suite.
  • Parallel work — spawn three subagents at once: one writes the migration, one writes the seed data, one drafts the rollback. Merge results.
  • Specialised personas — a “security reviewer” subagent with a tighter tool surface (read-only, no shell) and a system prompt focused on threat modelling.
  • Research and synthesis — “read the last six release notes and summarise the breaking changes we need to handle.” Returns the summary, not the raw notes.

The test: if a task would generate a lot of intermediate noise but you only care about the final answer, it’s a subagent task.

What “isolated context” actually looks like

Section titled “What “isolated context” actually looks like”

The subagent’s defining property is that it runs in its own context window — separate from yours. Picture two windows:

┌─ parent context ──────────────────┐    ┌─ subagent context ───────────┐
│                                   │    │                              │
│  rules, skills, conversation,     │    │  (fresh window)              │
│  the work you actually came       │    │   system prompt              │
│  here to do                       │    │   subagent's instructions    │
│                                   │    │   task: "debug the flaky     │
│  ── you delegate a task ──────────┼───►│    test in auth/session.ts"  │
│                                   │    │                              │
│                                   │    │   reads 17 files             │
│                                   │    │   runs the test 6 times      │
│                                   │    │   tries 4 hypotheses         │
│                                   │    │   ↓                          │
│  "the bug is in session.ts:142,   │◄───┼── returns ONE sentence ──    │
│   token mutated by middleware"    │    │                              │
│                                   │    │  (window discarded)          │
│                                   │    │                              │
└───────────────────────────────────┘    └──────────────────────────────┘

The seventeen reads, the four hypotheses, the six test runs — none of them enter your parent window. The parent receives the one-sentence summary and nothing else. Whatever the subagent learned to find the answer is gone the moment it returns; whatever you needed to act on the answer is still there, uncluttered.

The trade-off is also right there in the picture. The subagent starts with no shared history. It doesn’t know what you discussed earlier, what you’ve already ruled out, what you care about. You have to brief it in the task description — the more precisely, the better. Subagents shine for self-contained work; they’re a poor fit for tasks that need ongoing back-and-forth with you, because every “wait, also…” is a fresh subagent with no memory of the last one.

A worked example

Section titled “A worked example”

You’re mid-flow on a feature when CI flags a flaky test. Without a subagent:

you:       why is auth/session.test.ts flaky on CI?
agent:     [reads session.test.ts]
agent:     [reads session.ts]
agent:     [runs the test locally — passes]
agent:     [reads the test runner config]
agent:     [reads the middleware]
agent:     [tries a hypothesis: timezone? — runs again, still passes]
agent:     [reads the CI workflow file]
agent:     [tries another hypothesis: ordering? — runs in --random]
... 30 messages later ...
agent:     found it — middleware mutates the session token.
you:       great, now back to the feature.
agent:     [main context now full of debugging trail; coherence dropping]

With a subagent:

you:       spawn a subagent: investigate why auth/session.test.ts is
           flaky on CI, return the root cause in one paragraph.
agent:     [spawns subagent — fresh context]
                       ... 30 messages happen elsewhere ...
subagent:  Root cause: middleware in src/auth/middleware.ts:64
           mutates session.token before the test asserts on it.
           Reproduces locally only under --random-order.
agent:     [receives the paragraph, parent window otherwise untouched]
you:       great, now back to the feature.
agent:     [main context still clean; full coherence on the feature]

Same work happens. Same answer returns. The difference is what your conversation looks like afterward.

Why this and not…

Section titled “Why this and not…”
You want to…Reach forNot
Isolate a side-quest’s context so it doesn’t bloat the main threadSubagentSkill
Encode reusable instructions the model picks up on its ownSkillSubagent
Run two or more pieces of work in parallelSubagent (one per piece)Single agent serially
Enforce a deterministic rule on every tool callHookSubagent
Restrict a worker to a narrow tool surface (read-only, etc.)Subagent with tool restrictionsPermissions alone
Have peer agents coordinate and message each otherAgent teams (Claude Code, experimental)Subagent

A subagent returns once. It doesn’t continue the conversation. If you need a back-and-forth peer, you want an agent team (Claude Code) or the Agents SDK (Codex), not a subagent.

How it works in each tool

Section titled “How it works in each tool”

Subagents are spawned via the Agent tool. Custom subagents live at:

  • .claude/agents/<name>.md — project
  • ~/.claude/agents/<name>.md — user
  • Plugin-bundled
  • Managed-policy

Frontmatter:

---
name: code-reviewer
description: Reviews a diff for bugs, performance, and security issues.
tools: [Read, Grep, Glob]      # restrict the subagent's tool surface
skills: [security-checklist]   # preload these skills into its context
---

Precedence (most-wins): managed > CLI flag > project > user > plugin.

What the subagent inherits: the system prompt (shared for cache efficiency), CLAUDE.md content, git status, plus whatever the parent passes in the prompt. It does not inherit the parent’s conversation history.

Agent teams (experimental) are different — independent peer Claude Code sessions that message each other and share a task list. Use a subagent when only the result matters; use an agent team when teammates need to discuss and coordinate.

Comparison

Section titled “Comparison”
AspectClaude CodeCodexopencodeCursorCopilot
Built-in subagentsNone by defaultdefault, worker, explorergeneral, explore, scoutNone by default— (no in-IDE subagent)
Custom subagent path.claude/agents/*.md.codex/agents/*.toml.opencode/agents/*.md.cursor/agents/*.md (also reads .claude/agents/, .codex/agents/)— (.agent.md custom agents are personas, not sub-contexts)
InvocationVia Agent tool from parentNatural-language dispatch from parent@<name> mentionAuto-delegation, /name, or natural-language mentionChat picker (custom agents)
Tool restrictionFrontmatter tools: fieldNo explicit allowlist field; shape via mcp_servers / sandbox_modepermission (preferred) or deprecated toolsFrontmatter readonly flag—
Skill preloadFrontmatter skills: fieldTOML skills.config fieldVia permission.skill rules——
Inherits parent historyNoNoNoNo—
Peer-to-peer coordinationAgent teams (experimental)Via Agents SDK——Custom-agent handoffs

Name collisions

Section titled “Name collisions”
  • “Agent” vs “subagent” — in opencode, “agent” alone usually means a primary agent (build, plan) you switch into with Tab. “Subagent” means a worker the primary spawns. In Claude Code, “agent” colloquially means a subagent unless someone says “agent team.” In Copilot, a custom agent (.agent.md) is a persona you switch the chat into — not an isolated sub-context.
  • Subagent vs Agent team (Claude Code) — a subagent returns a summary; an agent team is a set of independent peer sessions that communicate directly and share a task list.
  • Don’t confuse the Codex CLI’s child agents with the OpenAI Agents SDK, which is a separate framework for production multi-agent orchestration.
  • Cursor Cloud Agents (formerly Background Agents) and Copilot Coding Agent both run in isolated remote sandboxes and return a PR — they’re closer to “async hand-off” than “in-session subagent.” Treat them as a separate primitive when comparing.