---
title: "Subagents: When to Split the Work and How to Set Them Up"
author: "Ecem Karaman"
source: "https://aiwithecem.com/guides/subagents"
published: 2026-09-17
tools: ["Claude","Codex"]
topics: ["AI Agents","Workflows"]
---

# Subagents: When to Split the Work and How to Set Them Up

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.

**Details checked against [Claude Code's subagent docs](https://code.claude.com/docs/en/sub-agents) and [OpenAI's Codex subagent docs](https://learn.chatgpt.com/docs/agent-configuration/subagents) on September 17, 2026.**

> **In this guide**
>
> 1. [What a subagent actually is](#what-a-subagent-actually-is)
> 2. [When to use one](#when-to-use-one)
> 3. [Four patterns that work](#four-patterns-that-work)
> 4. [Set one up in Claude Code](#set-one-up-in-claude-code)
> 5. [Set one up in Codex](#set-one-up-in-codex)
> 6. [Costs and gotchas](#costs-and-gotchas)

## 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.

```text
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.

```text
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.

```text
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.

```text
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.

```markdown
---
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-reviewer` runs 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.

```toml
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](/guides/tool-agnostic-ai-system).

**Go deeper:** [Claude Code Commands I Use on Repeat](/guides/claude-code-commands) · [Claude Code vs Codex](/guides/claude-code-vs-codex) · [How I Keep My Claude Code Setup From Drifting](/guides/claude-code-maintenance)