The first time I used a subagent, I used it wrong. I spun one up to rename a variable. A variable. It was like hiring a contractor to change a lightbulb — slower, more expensive, and faintly ridiculous. So before I show you how to set up a subagent in Claude Code, let me be blunt about when you shouldn't.
A subagent is a separate Claude instance your main session can hand a task to. It gets its own context window — a clean slate — does the job, and reports back a summary. The key word is separate. The subagent's work doesn't clutter your main conversation. It explores, churns through ten files, and your main session only sees the conclusion.
That's the entire point of subagents, and it's why most beginners misuse them.
When subagents actually help
They help when a task would otherwise flood your main context with stuff you don't need to keep.
Think about searching a large codebase for "where do we handle auth?" Without a subagent, Claude reads fifteen files into your main conversation, and now those fifteen files sit in context for the rest of the session, costing tokens on every turn. With a subagent, that exploration happens in a throwaway window. You get back "auth lives in src/auth/, here's how it flows" — three sentences instead of fifteen files.
So: subagents earn their keep when the work is exploratory (lots of reading, small conclusion) or parallel (several independent things at once). Searching, investigating, running a big test suite and summarizing failures, reviewing a diff against a checklist — these are perfect.
Here's the test I use now. Ask yourself: will this task read a lot but produce a little? If yes, subagent. If the task is a direct edit you can already see how to make, do it inline. Renaming a variable reads nothing and produces a precise change. No subagent.
When NOT to use them
Don't use a subagent for a single-file edit you understand. Don't use one for sequential work where each step depends on seeing the last. And don't use one just because it sounds sophisticated. Every subagent has overhead — it spins up, builds its own context, reports back. For small jobs that overhead costs more than it saves.
Newer Claude models are also pretty conservative about spawning subagents on their own, which is usually right. If you want delegation, you often have to ask for it or set it up explicitly. Which brings us to the how.
Setting up a custom subagent
Claude Code lets you define named subagents as files. Drop a markdown file in .claude/agents/ in your project (or in your home config for a global one). Here's a real one I use for code review:
---
name: reviewer
description: Reviews a diff for bugs and missing edge cases. Use after writing code, before committing.
tools: Read, Grep, Bash
---
You are a focused code reviewer. Given a diff or a set of changed files:
1. Read the changed code and the files it touches.
2. Look for actual bugs — off-by-one, null handling, wrong async behavior.
3. Check for missing edge cases and untested paths.
4. Report findings as a short list, each with a severity (high/medium/low).
Don't rewrite the code. Don't nitpick style. Report what you find and stop.
A few things worth pointing at. That description line isn't decoration — it's how Claude decides when to delegate to this agent. Write it the way you'd write a tool description: say when to reach for it, not just what it does. "Use after writing code, before committing" gives Claude a concrete trigger.
The tools line scopes what the subagent can touch. My reviewer gets Read, Grep, and Bash — enough to inspect and run tests, nothing to edit. That's deliberate. A reviewer shouldn't be changing your code. Narrowing the tool list keeps the subagent on task and is one less thing to worry about.
The body is the subagent's system prompt — its whole personality and job. Notice it's specific and bounded. "Report what you find and stop" matters, because otherwise an eager subagent starts fixing things, and now you've got changes you didn't ask for.
Using it
Once the file exists, you can invoke it in a session:
Use the reviewer subagent on my last commit.
Claude launches it, the subagent does its read-and-report thing in its own context, and you get back a clean list of findings — without fifteen files landing in your main conversation. For exploration, you don't even need a custom file; the built-in general subagent handles ad hoc "go find out X" tasks fine.
The mental shift
Here's what finally made subagents click for me. Stop thinking of them as "a more powerful Claude." They're not smarter. They're a way to keep your main context clean by sending the messy work somewhere else.
Once you see it that way, the when-to-use question answers itself. Messy, read-heavy, throwaway work? Delegate it. Precise work you can already picture? Just do it. A reviewer that runs your tests and hands back a findings list — great. A contractor to change a lightbulb — not so much.
Write one subagent this week. Make it the reviewer above. Run it on your next commit. Then you'll feel the difference, and you'll know exactly when to reach for the next one.