Claude Code subagents are specialized assistants that take a side task off the main conversation, work in their own context window and hand back only a summary. As of October 2026 each one has its own system prompt, tool access and permissions, and you create them as Markdown files in .claude/agents/ for a project or ~/.claude/agents/ for all your projects.
The catch: subagents save context, not usage
People reach for subagents thinking they'll stretch their plan further. They won't. A subagent sends its own requests, and those requests count toward the same usage limits as your main conversation. Hand three subagents a job each and you've spent three jobs' worth of usage.
What you do save is room in your main conversation. Searching a codebase, reading logs or opening dozens of files fills the context with material you'll never look at again. A subagent does that work in its own context window and returns a short summary, so your main session stays focused.
There's a smaller cost too. Claude decides when to delegate by reading each subagent's description, and those descriptions take up context. When the combined descriptions of your non-built-in subagents go past 15,000 tokens, Claude Code shows a warning at startup with the total. Keep descriptions short and clear.
When a subagent is the right call
The docs give a simple test. Use one when a side task would flood the main conversation with search results, logs or file contents you won't reference again. Good examples:
- Searching a large codebase to find where something is defined.
- Reading long build or test logs to find the one error that matters.
- Working through many files to answer a single question about them.
- Running a routine job on a faster, lower-cost model such as Haiku, by setting the model field.
Subagents work within a single session. If you need several sessions running side by side, the docs point you to background agents. For sessions that message each other there's cross-session messaging, and for a supervised group there are agent teams.
The built-in subagents you already have
Claude Code ships with three you can use straight away.
- Explore: fast and read-only, for finding files and searching code. It has three thoroughness levels: quick, medium and very thorough.
- Plan: read-only research while you're in plan mode.
- General-purpose: complex, multi-step work that mixes exploring with taking action.
Explore and Plan start without your CLAUDE.md files and the git status snapshot. That keeps them lean, but it means any house rules you've written in CLAUDE.md won't reach them. If you'd like your own version, a user-defined subagent named Explore overrides the built-in one and keeps its own model.
Where subagent files live and which one wins
The same subagent name can exist in more than one place. When that happens, the higher-priority location wins. Here's the order, highest first, as of October 2026.
| Location | Scope | Priority | How you create it |
|---|---|---|---|
| Managed settings | Organization-wide | 1 (highest) | Deployed via managed settings |
| --agents CLI flag | Current session | 2 | Pass JSON when launching; not saved |
| .claude/agents/ | Current project | 3 | Ask Claude or create the file, then commit it |
| ~/.claude/agents/ | All your projects | 4 | Ask Claude or create the file |
| Plugin agents/ folder | Where the plugin is enabled | 5 (lowest) | Installed with plugins |
Project subagents have one more rule. Claude Code walks up from your working directory, scanning every .claude/agents/ folder up to the repository root, and the definition closest to where you're working wins. Folders are scanned recursively too.
A subagent's identity comes only from its name field, not the file name. Two files with the same name inside them load only one, which is a quiet way to lose a subagent you thought you'd added. If you install subagents through plugins, my guide to Claude plugins covers how those get added.
What to put in a subagent file
Each subagent carries four things of its own: a context window, a custom system prompt, specific tool access and independent permissions. That's what makes them useful beyond saving context. You can give a reviewer read-only tools so it can look but never change a file, and give a different subagent the permissions it needs to act.
Want AI doing the heavy lifting in your marketing?
I build the systems that handle the boring 80 percent, so you get your week back. Done properly, with the human kept in.
The description does the most work. Claude reads it to decide when to hand a task over, so say plainly what the subagent is for and when to use it. A vague description means Claude either ignores the subagent or calls it for jobs it wasn't built for, and a long one eats into the 15,000-token startup budget for no gain.
There's a separate write-up on this in the Claude Mobile App guide.
How to set one up and call it
- Ask Claude to create a subagent, or write a Markdown file in .claude/agents/ for the project or ~/.claude/agents/ for your own use.
- Write a short, clear description so Claude knows when to delegate to it.
- Ask Claude to use it by name, for example: use the code-improver agent to suggest improvements in this project.
- If Claude can't find a new subagent and the folder is new, restart Claude Code.
That last step catches lots of people. If ~/.claude/agents/ didn't exist before your session started, the running session won't detect it. Restart and it'll appear. Running /agents now prints a reminder to ask Claude or edit the folders directly; on version 2.1.197 and earlier it opens an interactive wizard instead.
If you're comparing options, Claude Code Review fills in the rest.
My verdict on Claude Code subagents
I'd use subagents for any noisy side job, codebase searches and log reading above all, because keeping that out of your main conversation makes the rest of the session sharper. I'd point routine ones at Haiku with the model field. I'd skip them if you're hoping to save usage, because every subagent request counts against the same limits. If you're watching how far your plan stretches, this guide to Claude Code plans and limits is the place to check.
Frequently asked questions
Do Claude Code subagents use my usage limits?
Yes. Each subagent sends its own requests, and they count toward the same usage limits as your main conversation.
Where do I put a Claude Code subagent file?
In .claude/agents/ for the current project, or ~/.claude/agents/ for all your projects.
Why can't Claude find my new subagent?
If ~/.claude/agents/ didn't exist before the session started, the running session won't detect it. Restart Claude Code.
Which subagent wins if two have the same name?
The higher-priority location wins: managed settings first, then the --agents flag, then the project, then your personal folder, then plugins.
Can a subagent use a cheaper model?
Yes. Set the model field to route a task to a faster, lower-cost model such as Haiku.
