Subagents and parallel work

Up to now, every Claude Code session has been one Claude instance — one context window, one stream of conversation. That's fine for most work. But there's a class of tasks where it actively hurts: anything that requires a long, messy investigation that you don't want polluting your main thread. The fix is spawning a subagent.

What a subagent is

A subagent is a separate Claude instance that you launch from inside your main session, hand a specific task to, and wait for a single summarised reply. The subagent has its own fresh context window. It can read files, search the codebase, run commands — but everything it does stays in its own thread. When it's done, you get back one message: the result.

Think of it like delegating a research question to a colleague. You don't need to follow them around while they do the work. You want the answer.

Why this is a big deal

Two reasons.

Context hygiene.The main Claude session has a finite context window. Every file it reads, every tool result it sees, takes up space. A wide exploration — "find all the places we use the deprecated logging library" — can fill thousands of lines of output. Doing that in your main session leaves much less room for the actual task. A subagent absorbs all that exploration in its own context and returns just the summary.

Parallelism. You can launch multiple subagents at once. Three of them digging into three different angles, all running while you keep working. Hours-of-thinking-in-minutes.

When to use the general-purpose subagent

The default subagent type is called general-purpose (or sometimes "Explore" for read-only investigation). It's a clean Claude with all the same tools. Tasks that fit:

• "Find every file in this codebase that imports library X and report back which ones could be safely migrated."
• "Read these five technical specs and summarise the requirements as a checklist."
• "Audit the test coverage of the auth module and report gaps."
• "Look through git log for the last six months and find all commits that touched the billing code."

Each one of those would burn a lot of main-context if you did it inline. As subagent work, they cost almost nothing.

Custom agents

Claude Code also lets you define custom agents— specialised subagent types with their own pre-loaded instructions, their own tool allowlists, even their own model preferences. You write a small definition file that says "the code-reviewer agent gets these tools, has this prompt, can't edit files, and should think hard before answering."

Custom agents are how teams encode roles. "Reviewer." "Migration tool." "Doc writer." Each one a focused subagent with the right defaults baked in.

Foreground vs. background subagents

You can launch a subagent in two ways:

• Foreground.Your main session waits for the subagent to finish before continuing. Right when the subagent's answer is what you need to do anything next.
• Background.Your main session keeps going. The subagent runs in parallel; Claude Code notifies you when it's done. Right when you have other useful work you can do in the meantime.

Background subagents are how you turn one Claude into a small team. Three independent investigations going at once, notifications coming in as each one completes.

How to delegate well

Subagents start fresh. They don't see your conversation, your project context, your earlier discussion. The prompt you hand them is everything they know about the task.

The good-delegation habits:

1. State the goal in one sentence. What do you want at the end?
2. Give the necessary context.Project name, which folder, what tech stack. The subagent doesn't know unless you say.
3. Specify the output format."Reply with a markdown checklist of files and line numbers." "Report in under 200 words." Format matters because your main session will paste it back in.
4. Set a scope boundary."Only look at the auth code, don't expand the investigation." Prevents drift.

The mindset shift this enables

Once you're comfortable spawning subagents, your role starts changing. You stop being the person typing requests and start being the person assigning work. You're running a small fleet of focused tasks, each producing a piece of the final result.

This is the foundation for everything else in Module 4. Hooks, skills, scheduled runs — they all start to compose into a workflow where you're directing rather than executing. Module 4's final lesson, "from prompter to manager," is the explicit version of this idea.