Claude Code Subagents: How to Delegate Work to Specialized Agents

At some point, every serious Claude Code user hits the same wall: one conversation, one context window, one agent trying to hold your whole task in its head. You ask for a refactor, then a code review, then a test run, and somewhere along the way the conversation gets long, the context gets muddy, and quality drifts.

Subagents are Claude Code's answer to that. Instead of one generalist doing everything in one thread, the main agent can hand pieces of work to specialized helpers — each with its own instructions, its own tool permissions, and crucially its own fresh context window. This guide covers what subagents actually are, when they help (and when they're overkill), and how to build your own in a few minutes.

What a subagent actually is

A subagent is a separate Claude instance that the main agent can launch to handle a delegated task. It receives a prompt — "find every place we parse dates and check for timezone bugs" — works in its own context, and reports back only its conclusion. The main conversation never sees the hundred files the subagent read; it just gets the answer.

That last part is the magic. Context is the scarcest resource in any long Claude Code session. When a search-heavy or read-heavy job runs in a subagent, all of that noise stays out of your main thread. The main agent stays sharp because it only accumulates results, not research.

Claude Code ships with general-purpose subagents out of the box — you may have seen it "launch an agent" on its own when you ask for a broad codebase search. The real power move is defining your own.

Custom subagents: a prompt, a toolset, a job title

Custom subagents live as small Markdown files in your project (under .claude/agents/) or in your home folder for personal ones — and you can create them interactively with the /agents command instead of writing files by hand. Each file has a short frontmatter header — the agent's name, a description of when it should be used, and optionally which tools it may touch — followed by its system prompt: the standing instructions that make it a specialist.

Three examples that earn their keep in real projects:

• A code reviewer that is told to be adversarial, check error handling and security, and report findings as a ranked list — and that gets read-only tools, so it can never "helpfully" edit while reviewing.
• A test runner whose prompt says: run the test suite, and if something fails, fix only the failure without touching unrelated code.
• A researcher that digs through the codebase (or the web) and returns a summary, keeping hundreds of file reads out of your main context.

Because the description tells the main agent when to use each specialist, delegation starts happening automatically: ask for a review, and Claude routes the job to your reviewer with its stricter rules — no extra prompting from you.

The parallelism dividend

Subagents can also run in parallel. Ask Claude Code to investigate three unrelated flaky tests, and it can spin up three subagents that dig simultaneously instead of sequentially. For wide tasks — auditing many modules, migrating many files, researching several approaches at once — the wall-clock difference is dramatic.

This pairs naturally with running multiple Claude Code sessions, but it's a different axis: multiple sessions are you working several projects; subagents are one task fanning out inside a single session. Heavy users do both.

When not to use them

Subagents are not free. Each one starts from a clean slate — it doesn't know what you discussed for the last hour, so the delegation prompt has to carry the context, and anything it learns is gone when it finishes. They also consume tokens faster: a fleet of agents reading files in parallel adds up quickly.

• Skip them for small, single-file edits — delegation overhead exceeds the work itself.
• Skip them for tightly coupled changes where every step depends on decisions made in the previous one; that's a job for one agent with full context.
• Use them for anything search-heavy, review-shaped, parallelizable, or noisy enough that you want it out of your main thread.

The catch: delegated work is invisible work

Here's what nobody mentions about subagent workflows: they make Claude Code sessions longer and quieter. A task that fans out to four specialists can run for ten or twenty minutes with nothing happening in your terminal that requires you — followed by one moment where everything finishes (or one agent hits a permission prompt and the whole pipeline waits for your answer).

Sitting there watching is exactly the wrong way to spend those minutes — and missing the permission prompt is worse, because the run sits blocked until you notice. This is the problem AI Done Now exists for: a Mac menu bar app that fires a native notification the moment Claude Code finishes or needs your input, with distinct alerts for "done" and "waiting for you." The longer and more autonomous your agent runs get, the less optional that becomes.

A starter recipe

1. Run /agents in a project you work in daily and create one agent: a read-only code reviewer with an adversarial prompt.
2. Use it for a week. Every time you ask for a review, note that your main conversation stays clean.
3. Add a second specialist for whatever you delegate most — tests, research, dependency updates.
4. Then try one genuinely parallel task: "use subagents to investigate these three bugs at the same time."

Start small, let the specialists earn their place, and combine them with hooks and notifications so the whole system runs while you do something better with your attention. That's the actual promise of subagents: not a fancier chatbot, but a small team that works while you don't watch.