Subagents in Claude Code — When to Spawn One, When to Stay in the Main Loop

You're mid-session, Claude has built up a solid picture of your project, and now you need it to do something big and self-contained — say, read fifty files and produce a report. You could just ask. But you might regret it.

The jargon

Subagent — a second Claude process that Claude Code spins up to handle a discrete task. It gets its own context window, runs independently, and returns a result to the parent session.

Main loop — the primary Claude Code session: your conversation history, the code it's already read, your instructions so far. Everything lives here unless you explicitly move it elsewhere.

Task tool — the built-in Claude Code tool that spawns a subagent. Claude calls it when you ask it to delegate, or you can instruct it to do so directly.

The lesson

Every subagent starts with a clean, empty context. That is both the point and the trade-off. A subagent won't be confused by everything that came before — but it also won't know anything about your project unless you tell it explicitly in the prompt you hand it.

The main loop, meanwhile, is finite. Dump a large task into it and you eat context you can't get back. If that task produces a lot of intermediate output — file reads, tool calls, scratch-work — it pushes earlier, useful context out of the window. Future turns get worse because the model has less to work with.

A subagent handles the mess in isolation. It finishes, hands a compact result back to the main loop, and the main session stays clean.

How it works

You don't call the Task tool yourself — Claude does. You instruct it to delegate. The simplest pattern:

Spawn a subagent to read every file in /src/utils, then summarise what each function does. Return a single markdown table. Do not do this work in our current session.

Claude calls the Task tool, which starts a fresh process with a prompt you (or Claude) compose. That process runs to completion and returns its output as a single message back to the parent session.

You can also instruct Claude to give the subagent specific tools — file read access, web search, a bash shell — or restrict them. If you don't specify, it inherits sensible defaults.

When to reach for it / when not to

Reach for it when: - The task is large, exploratory, and produces a lot of intermediate noise (file scanning, log parsing, research). - The task is genuinely independent — it doesn't need the conversation history to do its job. - You want the result summarised, not streamed into your main session line by line.

Leave it in the main loop when: - The task needs context from earlier in the conversation — a subagent won't have it. - The task is small. Spawning a subagent for a two-file edit is overhead with no benefit. - You need tight back-and-forth. A subagent is a one-shot call, not a dialogue.

Try it

Pick a folder in a current project with ten or more files. Ask Claude Code: "Spawn a subagent to read all the files in [folder] and return a one-paragraph summary of what this module does. Don't do the reading in this session." Watch what comes back — then check your main session's context. It should look almost untouched.