A subagent is a separate agent your main agent hands a task to. It works in its own context window and sends back a summary. Used well, subagents keep your main conversation focused and run work in parallel. Used badly, they burn tokens and lose the context that made the task make sense.
What a subagent actually is
- It starts fresh. A subagent doesn't see your conversation, the files already read, or the decisions you've made. It works only from the task message it receives.
- It has its own setup. Its instructions, tools, model and permissions can differ from the main agent's.
- It returns a summary. The noisy work stays in its context. Only the result comes back.
Both tools ship built-in subagents you can use without setup:
| Claude Code | Codex |
|---|---|
| Explore: read-only codebase search | explorer: read-heavy codebase exploration |
| Plan: read-only research for planning | worker: implementation and fixes |
| General-purpose: multi-step work that can edit files | default: general-purpose fallback |
When to use one
| Use a subagent when | Stay in the main conversation when |
|---|---|
| The task produces output you won't need again, like logs, test runs or search results | You're going back and forth to refine something |
| The work is self-contained and can return a summary | Planning, building and testing share a lot of context |
| You want to restrict tools, like read-only access | It's a quick, targeted change |
| Independent parts can run at the same time | You need the answer fast, since a fresh subagent has to gather context first |
For a quick question about something already in the conversation, Claude Code's /btw is cheaper. It sees your context but has no tools.
Four patterns that work
1. Isolate noisy work. Keep logs and test output out of your main thread.
Use a subagent to run the test suite and report only the failing tests, with their error messages.
2. Research in parallel. Split investigations that don't depend on each other.
Use separate subagents to research the auth module, the database layer and the API routes in parallel. Each one returns a short summary with file references.
3. Chain specialists. Pass one subagent's findings to the next.
Have the reviewer subagent find performance issues, then have a second subagent fix only the issues it confirmed.
4. Review with fresh eyes. A subagent that didn't write the work doesn't share the assumptions behind it.
Use a read-only subagent to review this change against the original requirements. It should list what's missing or wrong, not rewrite anything.
Set one up in Claude Code
Create a Markdown file in .claude/agents/ for a project, or ~/.claude/agents/ for all your projects. You can also ask Claude to write it for you.
---
name: code-reviewer
description: Reviews recent code changes for bugs, security issues and missing tests. Use after meaningful code changes.
tools: Read, Grep, Glob
model: sonnet
---
Review the changed files only. Report issues by severity with file and line references.
Don't edit files. Flag anything you're unsure about instead of guessing.
| Field | What it controls |
|---|---|
name and description | Required. The description is how Claude decides when to delegate |
tools | Which tools it can use. Omit it to inherit all available tools |
model | sonnet, opus, haiku, fable or inherit |
isolation: worktree | Runs it in a separate git worktree so its edits don't collide with yours |
Run it three ways:
- Name it: "Use the code-reviewer subagent on my recent changes." Claude decides whether to delegate.
- Mention it: type
@and pick it. That guarantees it runs. - Make it the session:
claude --agent code-reviewerruns the whole session with its instructions and tools.
To hand off a side task with your full context instead of a fresh start, use /subtask, which forks the current conversation.
Set one up in Codex
Create a TOML file in .codex/agents/ for a project, or ~/.codex/agents/ for all your projects. Three fields are required.
name = "reviewer"
description = "Reviews code changes for correctness, security and missing tests."
sandbox_mode = "read-only"
developer_instructions = """
Review the changed files only. Report issues by severity with file references.
Don't propose rewrites unless asked.
"""
Codex delegates when you ask it to, or when your AGENTS.md or a skill tells it to. In the CLI, use /agent to switch between agent threads while they run. In the desktop app, each subagent thread opens so you can inspect its work.
Costs and gotchas
- They cost more. Each subagent does its own model and tool work, so the same task uses more tokens than a single agent.
- Summaries still add up. Every result returns to your main conversation. Many detailed reports can fill it anyway, so ask for short ones.
- Brief them well. A subagent only knows what's in its task message. Include the goal, constraints and what a good result looks like.
- Be careful with parallel edits. Parallel agents are safest for reading. Agents editing the same files at once can conflict, so isolate them or run them in sequence.
- Keep descriptions short. Every description loads into context. Claude Code warns once your subagents' descriptions pass 15,000 tokens combined.
- Restrict what they can reach. A subagent may read web pages or files you never saw. Give reviewers read-only access, and don't give any subagent more tools than its job needs.
Using both tools? Write each role once and point each tool's agent file to it. See Stop Building Your AI System Inside One Tool.
Go deeper: Claude Code Commands I Use on Repeat · Claude Code vs Codex · How I Keep My Claude Code Setup From Drifting