When sub-agents help vs. just add overhead
Claude Code has an Agent tool that can spin up independent sub-agents mid-conversation to handle tasks. Each sub-agent gets its own context, does its work, and returns results to the main agent.
Sounds powerful — but in practice, you don't need it most of the time. This article breaks down when sub-agents genuinely help, and when they just get in the way.
You can't call the Agent tool directly from CLAUDE.md or slash commands — it's an internal tool that Claude Code decides whether to use on its own. But you can nudge its decisions through your prompts.
Here's the workflow:
Key characteristics:
This is the classic use case. You ask Claude Code to investigate something that requires looking in multiple directions at once.
Say you ask: "How is authentication implemented in this project?"
Without sub-agents, Claude Code works sequentially: read the auth controller → read middleware → read routes → read the model → read config... one step at a time. Slow.
With sub-agents:
Launch 3 sub-agents simultaneously:
- Agent 1: Examine controller and middleware layers for auth logic
- Agent 2: Examine user and session design at the model layer
- Agent 3: Check config files and env vars for auth-related settings
Three directions at once, results consolidated. You can guide this in CLAUDE.md:
## Research Tasks
When investigating issues that span multiple modules, prefer launching
multiple sub-agents in parallel to research different areas,
then consolidate findings.
Claude Code's context window is finite. If a subtask requires reading tons of files but ultimately just needs to produce a conclusion, a sub-agent keeps all that "process waste" out of the main context.
Typical examples:
These tasks share a pattern: large input, small output. The sub-agent digests the bulk internally and returns only the essentials.
Some tasks might go sideways. Using a sub-agent with isolation: "worktree" runs it in a separate git worktree. If it breaks things, your current working directory stays clean.
## High-Risk Refactoring
For large-scale refactoring, use sub-agents with worktree isolation.
Merge only after confirming the results are correct.
Good fits:
"Rename this function from camelCase to snake_case" — just do it directly. The overhead of spinning up a sub-agent (building context, waiting for return, parsing results) is slower than just making the change.
Rule of thumb: If one Grep + one Edit can handle it, don't split it into an agent.
"Read the config → update code based on the config → update tests based on the code changes"
Each step here depends on the previous step's output. Splitting this across sub-agents means passing intermediate results around via prompts — clunky and error-prone. Just run it sequentially.
Sub-agents return summary text, not structured data. If you need a sub-agent to make a precise edit (like inserting specific code at line 47), having the main agent do it directly is more reliable.
Sub-agents are great for "research and report back." They're not great for "execute this exact change."
If you've just started a conversation and the context window is wide open, there's no reason to split off agents to "protect context." Wait until the conversation grows long and the main agent starts compacting message history — that's when sub-agents earn their keep for heavy lifting.
Here's a concrete example: investigating every controller in a Rails project that uses before_action, analyzing authentication and authorization patterns.
Without sub-agents:
Claude Code reads controller files one by one, each consuming main context. With 20 controllers, the file contents alone can burn through a significant chunk of tokens. By the time it delivers the analysis, earlier details may have been lost to context compaction.
With a sub-agent:
Launch sub-agent: "Read all controllers under app/controllers/,
find every before_action callback, analyze authentication
and authorization patterns, and return a categorized summary."
The sub-agent reads everything in its own context and returns a clean summary. The main agent's context is barely touched — it gets the conclusion and moves on.
You can't force Claude Code to use or not use sub-agents, but you can express preferences in CLAUDE.md:
## Agent Usage Preferences
### Good candidates for sub-agents
- Cross-module research (searching 3+ directories)
- Large-scale code search and analysis
- Exploratory refactoring (with worktree isolation)
### Don't use sub-agents for
- Single-file edits
- Multi-step operations with sequential dependencies
- Bug fixes where you already know exactly what to change
Is the "process" of this task much larger than the "conclusion"?
If yes — use a sub-agent. Let it digest the process and return just the conclusion.
If no — do it directly. Don't add a middle layer.
Sub-agents aren't a case of "more is better." They're a context management tool, not a concurrency framework. Used well, they keep Claude Code sharp on large projects. Used poorly, they're just wasted startup time.