ClaudeFolio
Tools

When to use a Claude Code subagent, and when not to

Edward Kwun··3 min read
When to use a Claude Code subagent, and when not to

See more of our writing in your Google results.

Key points

  • A subagent has its own context window and reports back an answer
  • Delegate large reads so file contents stay out of your window
  • Rewind cannot undo a subagent's file edits, so commit first
  • Subagents do not inherit your session's auto memory
  • Opus 5 delegates to subagents more readily by default
  • Delegate reading, and keep writing in your own session

Subagents are the Claude Code feature people either use constantly or have never touched. A subagent is a separate Claude with its own context window that your main session hands a task to, and it reports back an answer rather than everything it read on the wa

The real reason to delegate is context, not speed

Say you need to figure out how authentication works across eleven files. If you read all eleven in the main session, that code now takes up space in the same context window you need for the actual work. Give the job to a subagent instead and it can do the reading in its own window, then come back with the answer. You keep the useful part without carrying all eleven files with you.

Anthropic's own guidance recommends delegating large reads as one way to preserve context, and that is probably the subagent use I reach for most. Anything that sounds like "go figure this out and report back" fits well: trace how a feature works, see whether the same pattern appears elsewhere, read through a long log, or inspect a dependency.

The other useful setup is writer-verifier. One agent does the work and another reviews it. Anthropic points to multi-agent coordination and writer-verifier workflows as a strength of Opus 5, and it is close to the review process I already use across two different models. The limitation is worth keeping in mind: a verifier trained in much the same way as the writer is not as independent a check as a different model, or a human review.

Three things that surprise people

Rewind won't undo a subagent's edits. A subagent edits with the same file tools, but those edits usually aren't captured in your session's checkpoints, so /rewind can't restore them. Git is your recovery path there, which is one more reason to commit before you start a session. The exception is a foreground forked skill, which edits during your own turn and does get restored.

They don't inherit your memory. The main conversation's auto memory isn't loaded into subagents. A subagent starts without the accumulated notes your main session has, so a task that depends on project-specific context needs that context in the prompt you give it. The exception is a fork, which inherits the parent conversation.

Recent models delegate on their own. Anthropic's Opus 5 notes say that in multi-agent frameworks it delegates to subagents more readily than before. If sessions started spawning helpers you didn't ask for, that's intended behavior, not a bug.

When it's the wrong tool

Delegation costs a handoff. You write a prompt, the subagent works without the context you have in your head, and you get back a summary you have to trust. For a small task that's slower and worse than doing it yourself.

Skip it when the task is two files and a question, when it needs judgment that depends on conversation you've had and the subagent hasn't, or when you'd have to explain more context than the task is worth. And be careful running several in parallel on the same files, since the failure mode is agents overwriting each other's work. Anthropic claims few such cases on Opus 5, which is a claim about frequency rather than impossibility.

The way I think about it: use a subagent when you want an answer, and keep the work in your own session when you want to watch it happen. Reading is the thing worth delegating. Writing, mostly, isn't.
 

Sources

Claude Code docs: Explore the context window - Delegating large reads to a subagent so file contents stay in its context window rather than yours.

Claude Code docs: Checkpointing - Subagent edits usually not captured in session checkpoints so rewinding does not restore them, with the foreground forked skill exception, and the direction to use git instead.

Claude Code docs: Memory - The main conversation's auto memory not loading into subagents, with forks inheriting the parent conversation as the exception.

Anthropic: What's new in Claude Opus 5 - Delegating to subagents more readily in multi-agent frameworks, and multi-agent coordination with writer-verifier patterns and few cases of agents overwriting each other's work.

Found this article useful?

Add ClaudeFolio as a preferred source on Google to see our articles first.

FAQ

What is a subagent in Claude Code?
A separate Claude instance with its own context window that your main session delegates a task to. It reports back a result, so the files and output it worked through never enter your main conversation.
When should I use a subagent?
For tasks shaped like go find out and tell me: tracing a feature across many files, reading long logs, or surveying a dependency. Delegating those keeps large file contents out of your own context window.
Can I undo changes a subagent made?
Not with /rewind. Subagent edits usually are not captured in your session's checkpoints, so recovery goes through git instead. A foreground forked skill is the exception, since it edits during your own turn.

Related posts

Comments