Claude Code Subagents, Explained Simply

Subagents are the Claude Code feature people either use constantly or have never touched. There is not much middle ground, and that is mostly a documentation problem rather than a complexity problem.

The concept is simple. Here it is in one sentence: a subagent is a fresh Claude session your main session can start, hand a task to, and get an answer back from. Everything else is detail.

What follows is the detail, plus the part that actually matters, which is knowing when a subagent is the right tool and when it is not.

The context window is the whole reason

To understand why subagents exist, you have to care about context.

Your main session has a finite context window holding your conversation, the files it has read, and every tool result. When you ask it to "find where authentication is handled," it might read eleven files to answer. All eleven files are now permanently in your context, forever, even though ten of them were dead ends.

Do that four times and your window is full of search debris. The agent gets slower, more forgetful, and eventually you compact and lose nuance.

A subagent solves this. It gets its own separate context window. It reads the eleven files in its window, figures out the answer, and returns a paragraph. Your main session receives the paragraph. The eleven files never touch your context.

That is the whole trick. Subagents are a context firewall. Delegate the messy, high-volume, low-signal work and keep only the conclusion.

What actually happens when one runs

The main agent decides a task is worth delegating, or you tell it to. It spawns a subagent with a prompt and a tool set. The subagent runs its own loop, reading files, running searches, doing whatever it needs. When it finishes, it writes a final message. That final message, and only that, comes back to the main agent.

Three consequences worth internalizing:

The subagent cannot ask you anything. It has no channel to you. If its instructions are ambiguous, it guesses and keeps going. Vague subagent prompts produce confidently wrong results.

Only the final message survives. Everything the subagent read, reasoned about, or discovered along the way is gone unless it said so explicitly. If you want the file paths, the prompt has to ask for the file paths.

It starts cold. No memory of your conversation. Whatever context it needs has to be in the prompt.

When to use a subagent

Good fits, in rough order of how often I reach for them:

Searching and exploring. "Find everywhere we validate email addresses." High file volume, small answer. Textbook case.

Independent parallel work. Three unrelated files each need the same mechanical change. Three subagents, one message, done at once instead of in sequence.

Focused review. A security pass or a style review on a finished diff, where you want a clean set of eyes rather than the same agent that just wrote the code marking its own homework.

Anything with a big noisy output. Reading a 4,000 line log to find one error. Let the subagent eat the log.

Bad fits:

Work needing back and forth. If you will want to redirect it halfway, keep it in the main session where you can interrupt.

Small tasks. Spawning has overhead. For a two-file edit the main agent is faster.

Sequential dependencies. If step two needs step one's output, one agent doing both is simpler than plumbing results between two.

Anything requiring your judgment mid-flight. The subagent cannot ask. It will decide for you.

Subagents versus parallel sessions

These get conflated and they are genuinely different tools.

	Subagents	Parallel sessions
Started by	The main agent	You
Context	Own window, isolated	Own window, isolated
You can talk to it	No	Yes
Returns to	The main agent	You
Good for	Bounded tasks with a clear answer	Ongoing work you supervise

Rule of thumb: subagents for tasks, sessions for projects.

"Audit our error handling and report back" is a task. Delegate it, take the report. "Build the new billing flow" is a project. It needs your judgment repeatedly, so it wants its own session, its own git worktree, and your attention. That side of the workflow is covered in how to run multiple Claude Code sessions at once.

You use both, often at the same time. Three sessions, each spawning subagents when it hits a search-heavy stretch.

Custom agent definitions

You can define named subagents with their own instructions, tools, and model. They live as markdown files in .claude/agents/ for a project, or ~/.claude/agents/ for everything you do.

A definition is frontmatter plus a system prompt:

---
name: security-reviewer
description: Reviews code for security issues. Use after writing anything that handles user input, auth, or secrets.
model: opus
tools: Read, Grep, Glob
---

You review code for security problems. Focus on:

- Injection: SQL, command, template
- Missing validation at trust boundaries
- Hardcoded secrets and credentials
- Auth and authorization gaps

Report findings with file path and line number, ordered by severity.
If you find nothing, say so plainly. Do not invent issues to seem useful.
Do not fix anything. Report only.

Four fields carry the weight.

description is the most important and the most neglected. This is what the main agent reads when deciding whether to delegate. Write it as a trigger condition, not a job title. "Reviews code for security issues. Use after writing anything that handles user input" gets invoked. "Security expert" does not.

tools restricts what it can do. Giving a reviewer read-only tools is not paranoia, it is a guarantee. A reviewer that cannot write cannot decide to helpfully "fix" something on its way past.

model lets you match cost to difficulty. Haiku for mechanical work like reformatting or extracting a list. Sonnet for most real work. Opus for anything needing actual judgment. Anthropic changes model availability and pricing regularly, so check their current docs rather than hardcoding assumptions.

The body is the system prompt. Be specific about output format. "Report findings with file path and line number, ordered by severity" produces something you can act on. "Review the code" produces an essay.

Writing prompts that survive isolation

Since a subagent cannot ask questions, the prompt has to carry everything.

State the deliverable, not the activity. "Return a list of file paths and line numbers where we call the payments API" beats "look into the payments API usage."

Say what to leave out. Subagents love to be thorough. "Do not summarize the code you read, only report the matches" saves you a wall of text.

Give it the starting point. "Start in src/api/" prevents it from reading your entire node_modules.

Ask for paths. You will want to look at the code yourself. If the prompt does not ask for locations, you get prose with no way back to the source.

Do not stack sequential steps. One clear objective per subagent. If you need two phases, run two subagents and let the main agent pass results between them.

Watching several at once

Here is where it gets practical, and where the tooling matters.

Fan out five subagents and your terminal becomes a wall of interleaved status output. Meanwhile the main agent is blocked until they finish, so the session looks frozen while a lot is happening. If you have several sessions each doing this, you have lost track entirely.

Some things that help:

Hook SubagentStop. Claude Code fires it every time a subagent finishes. Wire it to a quiet sound or a log line and you get a heartbeat instead of silence. Configs are in the notifications guide.

Fan out in small batches. Three subagents you can hold in your head. Nine you cannot, and when the results come back you will not remember what you asked for.

Delegate on read volume, not vibes. The clean signal for "this should be a subagent" is that the task reads a lot and returns a little.

For the multi-session side, MOLTamp is what I use, and it is our app so weigh it accordingly. Since v3.2.0 it holds up to 50 tabbed sessions and reads Claude Code's hook stream to badge each tab: amber when that session is blocked on you, green when it finished its turn while you were looking elsewhere, cleared automatically when the agent starts running tools again. When a session is deep in a subagent fan-out, the absence of a badge is the useful signal. It is still working, leave it alone. The badge colors come from your terminal palette, so any skin from the community gallery inherits sensible ones, and the skinning docs cover the rest.

The mental model, one more time

Subagents are not a way to make Claude smarter. They are a way to keep your main session's context clean by sending the messy work somewhere else and keeping only the answer.

Delegate the reading. Keep the thinking. That is the whole feature.

FAQ

What is a Claude Code subagent?

A separate Claude session your main agent spawns to handle one bounded task. It gets its own context window, does the work, and returns a single final message. Everything it read stays out of your main context.

When should I use a subagent instead of just asking Claude?

When the task will read a lot and return a little, like a codebase-wide search, a log analysis, or a focused review. For small edits or anything where you will want to redirect midway, stay in the main session.

Where do custom agents go?

Markdown files in .claude/agents/ for a single project, or ~/.claude/agents/ to make them available everywhere. Frontmatter sets the name, description, tools, and model; the body is the system prompt.

Can subagents run in parallel?

Yes. The main agent can spawn several at once, and they run concurrently. Keep batches small enough that you can still make sense of the results.

Do subagents cost more tokens?

Each one has its own context and its own turns, so yes, more tokens in total. The tradeoff is that your main session stays clean and useful for longer. Check Anthropic for current pricing on your plan.

---

Start with one custom agent for whatever you keep asking for by hand, and pay attention to the description field since that is what decides whether it ever gets used. More workflow patterns in Claude Code tips and tricks, and the multi-agent view in running multiple AI agents in one terminal. If you are running enough of them that "which one needs me" is a real question, MOLTamp is free.