Sub-agents explained: how coding agents split a task
Short answer: a sub-agent is a helper agent that the main coding agent starts for one part of a task. It works in its own context window, often at the same time as other sub-agents, and returns only its result. That keeps the main agent's memory clean, lets independent parts run in parallel, and makes big tasks faster and more reliable. Sub-agents use the same plan limits as the main agent, so they cost more tokens in total.
The problem sub-agents solve
A coding agent can only hold so much in its context window: the conversation, the files it has read, command output. On a big task that window fills with noise, such as search results, long logs and files it read once. The agent starts forgetting the instructions that matter.
Sub-agents fix this by delegation. The main agent says, in effect, "search the codebase for every place we format dates and tell me what you find". A sub-agent does the searching in its own window and hands back a short answer. The main agent keeps the conclusion, not the ten files.
How it works
- The main agent plans the task and spots parts that can be done separately.
- It starts a sub-agent per part, each with its own instructions, tools and a fresh context window.
- Sub-agents work, in parallel when the parts are independent.
- Each returns a summary of what it found or changed.
- The main agent combines the results and carries on.
In Claude Code you can also define your own named sub-agents, such as a reviewer, a test writer or a researcher, each with its own prompt and allowed tools.
When sub-agents help
| Good fit | Why |
|---|---|
| Searching a large codebase | Noisy output stays out of the main context |
| Independent changes in separate areas | They can run at the same time |
| Review or test-writing after a change | A fresh agent isn't biased by how the code was written |
| Research before a decision | Several options explored at once, one summary back |
When they don't
- Small tasks. Starting a sub-agent has overhead; a one-line fix doesn't need one.
- Tightly coupled changes. If two parts edit the same files, running them at once causes conflicts. Do them in sequence.
- Tight budgets. Each sub-agent sends its own requests, which count against the same plan or API limits as the main agent.
Sub-agents vs parallel tasks
These are two different kinds of parallelism:
- Sub-agents split one task inside one agent session, usually on one branch.
- Parallel tasks are separate tasks, each with its own agent, worktree and branch; see running several agents with git worktrees.
You can use both: several tasks in parallel, each using sub-agents inside.
Seeing who did what
The hard part of sub-agents is following them. In a terminal their work is summarised; details are easy to miss. In Zokie, sub-agents are free on every plan and each one talks in the task's chat under its own name, so you can see which helper did what before you review the diff.
FAQ
What is a sub-agent in Claude Code?
A separate Claude instance that the main session starts for part of a task, with its own system prompt, tools and context window. It returns its result to the main session.
Do sub-agents cost more?
They use more tokens overall, because each one sends its own requests, and these count toward the same usage limits as the main conversation. They often save time and retries on big tasks.
Can sub-agents edit files at the same time?
They can, but they shouldn't edit the same files. Give parallel sub-agents independent areas of the code, or run them in sequence.
Do Codex and Gemini CLI have sub-agents?
Multi-agent features vary by tool and change quickly. Check each tool's current docs. The idea is the same: delegate parts, keep the main context clean.