Claude Code subagents, explained

A subagent in Claude Code is a separate agent instance you dispatch from your main session to go do a self-contained chunk of work, then report back. It runs with its own context window, its own tool access, and its own read of the task, and it hands the parent session a summary rather than a live transcript of everything it did along the way.

The reason this exists is context management. A long-running Claude Code session accumulates context as it reads files, runs commands, and gets responses back — and that context is finite. If your main session is in the middle of a feature and you also need to go answer “where in this codebase is authentication handled,” doing that lookup in the main thread burns context on file reads you don’t need to keep around once you have the answer. Dispatching it to a subagent means only the answer comes back, not every file it opened to find it.

The pattern that benefits most is open-ended research inside a task that’s otherwise well-scoped: “find every place this deprecated function is called” or “figure out why this test is flaky” are good subagent candidates because they involve exploration whose byproduct (a bunch of files read, false leads followed) isn’t itself useful to keep. A subagent that specializes in code review or test-running can also be configured with restricted tool access, so it can read and run tests but can’t edit files — useful when you want a second opinion that hasn’t already committed to a fix.

Subagents aren’t free, and treating every small task as subagent-worthy adds overhead without benefit. Dispatching one has real latency and coordination cost, and for something you could just do directly in three tool calls, it’s slower than doing it yourself. I default to subagents when a task is genuinely parallel to what I’m already doing (I can keep working while it runs in the background) or genuinely exploratory (I don’t know the answer and don’t want the search itself cluttering my main context). If it’s short, sequential, and I need the result before my next step anyway, I just do it inline.