Claude Code Subagents vs. Agents: Differences & How to Use Each Effectively

Every long Claude Code session runs into the same wall. The conversation fills with file contents, search results, and test output, and somewhere past the halfway mark, the answers start getting vaguer. Claude Code subagents exist to solve that problem, and most developers who try them either use them for the wrong jobs or give up before seeing the payoff.

This guide covers what actually works in 2026: how subagents work under the hood, how to build your own, what they cost in tokens, where they fall short, and how subagents compare to agent teams, since the two get confused constantly.

One note before you start. Claude Code changed how subagent creation works in version 2.1.198, released in 2026. Most guides you'll find still describe the old interactive wizard. The steps below reflect the current behavior.

Read: The 5 Best AI Coding Agents: Pros & Cons, Reviews, & Which is Best for You

What Are Claude Code Subagents?

A subagent is one of the specialized AI assistants that your main session spawns to handle a bounded task. It runs with its own context window, its own system prompt, and its own tool access. When it finishes, it reports back to the main agent with a result. That is the entire relationship.

Claude Code implements this through the Agent tool, which was previously called the Task tool. Both names still work. When Claude encounters a task that matches a subagent's description, it can delegate the work instead of handling it in the current session. The subagent reads files, runs searches, and makes tool calls inside its own context. None of that activity touches your main conversation.

Think of the pattern as a manager with contractors. The manager assigns different tasks, each contractor works independently, and each one hands back a finished result. Contractors never talk to each other. All communication flows through the main Claude agent.

Why Context Isolation Is the Whole Point

The core value of code subagents is context isolation, which protects your main session from filling up with noise. Parallelism and specialization are useful side benefits, but isolation is the reason the architecture exists.

Here's the problem it solves. A standard Claude Code session gives you a 200K token context window. That sounds like plenty until you're deep into a multi-hour session with a dozen open files, a long conversation history, and stacks of tool outputs. By the time the window hits two-thirds capacity, response quality degrades in a way most developers can feel. The model starts losing track of decisions made earlier. Answers get vaguer. This happens because the context is full of low-value tokens that the model still has to attend to.

Subagents fix this by design. Each spawned agent gets its own context window, does the messy work there, and returns only its final output. A subagent might read forty files and run thirty searches to answer one question. All the intermediate noise stays inside the subagent's context and never reaches the parent. The main session receives a short summary, a recommendation, or a structured report. The parent gets the signal without the noise.

This is why experienced users reach for subagents on read-heavy research first and parallel coding second. A subagent sent to find every caller of a function, summarize a subsystem, or check whether a change breaks an existing contract produces a small, clean result while keeping its exploration cost internal. That is the use case the architecture rewards.

Built-In Claude Code Subagents in 2026

Claude Code ships with three primary built-in subagent types, and Claude routes work to them automatically based on task characteristics. You don't need to configure anything to benefit from them.

Explore is a fast, read-only agent for searching and analyzing codebases. Write and Edit are denied at the tool level. As of version 2.1.198, Explore inherits the main conversation's model, capped at Opus on the Claude API. Older guides say Explore always runs on Haiku, and that's no longer true. If you want cheap exploration back, define your own agent named Explore with the model: haiku, and it overrides the built-in.

Plan gathers context during plan mode. When Claude needs to understand your codebase before presenting a strategy, it delegates the research to Plan so the exploration output stays in a separate context window while your main conversation remains read-only.

General-purpose handles complex multi-step work that requires both exploration and modification. It has access to all tools and inherits the session model.

The auto-routing works reasonably well for these built-ins. For custom agents, it's less reliable, which we'll get to below.

How to Create a Custom Subagent

You create a custom subagent by asking Claude to write the agent file for you, or by writing the Markdown file yourself in .claude/agents/ for a project or ~/.claude/agents/ for your user scope. As of Claude Code v2.1.198, the /agents command no longer opens an interactive creation wizard. Running it just prints a reminder to ask Claude or edit the directory directly.

The fastest path is a plain-language request inside Claude Code:

Claude writes the file with a name, a description, a tools list, a model, and a system prompt. Open the result and confirm it matches what you asked for:

Claude Code watches both agent directories, so edits take effect within seconds without a restart. The one exception is creating a scope's very first agent file. If ~/.claude/agents/ didn't exist when your session started, restart Claude Code to load it.

A few practical notes on scope. Project subagents live in .claude/agents/ and are the right choice for project-specific knowledge, like your test conventions or your deployment setup. Check them into version control, so your team can use and improve them together. User scope agents in ~/.claude/agents/ follow you across every project on your machine. You can also pass agent definitions as JSON through the --agents CLI flag for a single session, which works well for workflow automation and CI scripts since nothing gets saved to disk.

The Configuration Fields That Matter

Only name and description are required in the frontmatter, but three optional fields do most of the heavy lifting in a real subagent workflow.

• The description field controls delegation - Claude uses each subagent's description to decide when to delegate tasks, so write it like a trigger condition and include phrasing like "use immediately after modifying code." A vague description is the most common reason a customer agent never gets called.
• The tools field is a hard constraint - Listing specific tools physically restricts what the subagent can do. A reviewer defined that with only Read, Grep, and Glob cannot write files, period. That's an enforced boundary rather than a prompt suggestion, and it's worth a lot if you run your main session with broad permissions. If you omit the field, the subagent inherits all available tools from the parent, including MCP tools.
• The model field controls cost - You can route different tasks to different models: haiku, sonnet, opus, fable, or a full model ID. The cost difference between models is substantial on pay-as-you-go pricing, and a "find every file that imports this package" job doesn't need your most expensive model. Route exploratory reads to Haiku and save the heavyweights for reasoning.

Beyond those three, the 2026 frontmatter supports fields most guides haven't caught up with. maxTurns caps how long a subagent can run. Skills preloads full skill content into the subagent's context at startup. Memory enables cross-session learning at the user, project, or local scope. Isolation: worktree runs the subagent in a temporary git worktree with its own copy of the repository, which eliminates file conflicts when parallel agents touch the same codebase. And background: true always runs the agent as a background task. As of v2.1.198, Claude runs subagents in the background by default, so your main session stays responsive while they work.

The Markdown body below the frontmatter becomes the subagent's system prompt. Subagents receive that system prompt plus basic environment details, and nothing else from your session's setup. Write it the way you'd brief a specialist: role, process, output format, and standards. Telling the agent to "be critical" or "be honest" helps too, since default LLM behavior skews agreeable.

Three Subagents Worth Building First

Start with agents that produce small outputs from large inputs. These three cover the gaps most developers feel daily, and each one maps to a task where isolation pays off.

• The code reviewer - Runs after code changes and returns findings with line references. Scope it to read-only tools so it can review code without ever modifying it. Give it explicit standards to check: error handling, security issues, performance, and unresolved comments. This agent works alongside static analysis rather than replacing it. Linters catch mechanical problems, while the reviewer catches design problems and logic gaps that pattern matching misses.
• The test automation specialist - A test runner agent that executes your suite, confirms which tests pass, and reports test failures with the relevant stack traces and nothing else. Test output is some of the noisiest content that can enter a context window, and a full run can dump thousands of lines into your main conversation. This agent runs the suite in its own context, writes results into a structured report, and hands back only the failures worth your attention. Point it at your acceptance criteria for a feature, and it can verify the implementation against them.
• The debugger - A methodical agent for failing tests and runtime errors. It ingests logs, traces the point of failure, and identifies root causes. Have it ask clarifying questions like "When did this last work?" before proposing fixes. Pair it with the worktree isolation option when the investigation requires running code.

Resist the urge to build ten of these. Most developers max out at three or four subagents that actually earn their place. Past that, you're maintaining agent files nobody invokes.

Subagents vs. Agent Teams

Subagents and agent teams both put multiple Claude instances to work, and the difference is communication. Subagents report to the main session and cannot talk to each other. Agent teams are separate Claude Code sessions whose members message each other directly, share findings, and challenge each other's conclusions.

The community shorthand captures it well: subagents are function calls; agent teams are organizations.

Agent teams became a native experimental feature in Claude Code in early 2026, enabled with the CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS environment variable. One session acts as a team lead, assigning work and synthesizing results, while teammates operate in their own context windows and coordinate among themselves. You can even reuse your subagent definitions as teammate types, so a security-reviewer agent file can serve both roles. Some older articles claim Claude Code has no native primitive for teams and that you need external frameworks. That was true in 2025, and it isn't anymore.

So when do you need a team? Less often than the hype suggests. Teams cost roughly 3 to 4 times the tokens of a single session and add real coordination overhead. For a bug fix, a refactor, or a new component, they make you slower and poorer. They earn their cost in a few specific situations: parallel code review where separate agents investigate security, performance, and test coverage without contaminating each other's judgment, competing-theory debugging on a genuinely hard bug, and cross-layer features where frontend, backend, and tests move at once.

Two warnings from people running teams in production. There is no /resume for agent teams, so if the session dies, the team is gone. And enable delegate mode on the lead with Shift+Tab, because a lead left in default mode writes code itself instead of coordinating, which means your most expensive agent is doing junior work.

Here's the comparison at a glance:

If tasks are independent and just need doing, use sub-agents. If workers need to negotiate with each other, consider a team and budget for it.

Read: Agentic AI vs. AI Agents: Differences & What You Need to Know

What Subagents Cost

Subagents multiply token usage because each spawned agent opens its own full context window. Anthropic's documentation puts multi-agent workflows at roughly 4 to 7 times the tokens of single-agent sessions. On API pricing, that multiplier lands directly on your bill. On subscription plans, it lands on your rate limits, and five parallel agents burning through exploratory reads is a reliable way to hit the ceiling on a Pro plan in under twenty minutes.

The softening factor is prompt caching. In a typical heavy session, the large majority of tokens are cache reads billed at a steep discount, which makes the effective cost of subagent expansion smaller than the raw multiplier implies. It's still real money and real limits, though.

The discipline that works: use subagents for read-heavy, bounded tasks with a clear output, and keep the main session for anything that requires sustained cross-cutting context. Route cheap jobs to cheap models with the model field. Don't spawn agents because you can. A practical ceiling for most solo work is two or three focused information gatherers running in parallel, with the main session synthesizing what they return and making the decisions.

What Doesn't Work Well Yet

Three limitations show up consistently in real usage, and you should plan around all of them.

• Automatic delegation to custom agents is unreliable - Claude frequently handles a task in the main session even when a defined agent's description matches it exactly. The dependable trigger is explicit invocation. Say "use the code-reviewer agent on this change," and it happens. Wait for Claude to pick your agent on its own, and it often won't. Sharp descriptions with clear "use when" phrasing improve the odds, but if a delegation must happen, explicitly invoke it. There are open GitHub issues tracking this, so treat it as a known gap rather than something you misconfigured.
• Some models over-delegate - Recent Opus versions have a documented tendency to spawn subagents for work that a direct approach would finish faster and cheaper. If a simple task just consumed 50K tokens, an unnecessary delegation is the likely culprit. The maxTurns field and a quick "handle this directly" instruction both help.
• Observability is thin - There's no built-in trace view or per-agent cost breakdown in the terminal. Hooks partially fill the gap. The SubagentStart and SubagentStop lifecycle events let you instrument agent activity, and PreToolUse hooks let you validate or restrict what a subagent does before its output reaches the parent. If you need deeper visibility, the Claude Agent SDK ecosystem has third-party tools for it.

Practical Ways to Get More From Subagents

A handful of habits separate teams that benefit from code subagents from teams that gave up on them.

Write descriptions as delegation triggers. "Reviews code" is weak. "Reviews code changes for security issues and code quality. Use immediately after modifying code" gives Claude something to match against.

Keep outputs small by instruction. Tell every agent to return a concise, structured report rather than raw findings. The whole point is that the parent receives a signal, so an agent that dumps its full exploration back into your main conversation defeats the architecture.

Match the tool list to the job. A research agent needs Read, Grep, and Glob. A test runner needs Bash. Granting everything to everyone throws away the enforcement benefit that makes agent files worth writing.

Use worktree isolation for anything that writes. When parallel agents modify code, same-file edits guarantee conflicts. The isolation: worktree field gives each writer their own copy of the repository and sidesteps the problem entirely.

Treat agent definitions as code. They're version-controlled Markdown files, so review them in PRs, iterate on the prompts when outputs disappoint, and delete the ones nobody invokes.

Read: AI Upskilling: Top Firms, Programs, & Tools for Training Your Workforce

The Bottom Line

Claude Code subagents reward discipline over enthusiasm. The developers getting real value from them in 2026 follow the same pattern: two or three narrowly scoped agents, read-heavy work, tight tool lists, small structured outputs, and explicit invocation when a delegation matters. The ones who gave up usually built a roster of ten personas, let auto-routing decide when to use them, and watched their token budget disappear on work that a single session would have handled faster.

Start with one agent that solves a problem you feel every day, like a code reviewer that returns findings with line references or a test runner that reports only the failures. Check it into version control, iterate on the system prompt when the output disappoints, and add a second agent only after the first one earns its keep. Context isolation is the payoff, and it compounds as your sessions get longer and your projects get bigger.

The skill behind all of this, deciding what to delegate, how to scope it, and how to verify the result, is the same skill that separates people who use AI tools from people who build careers on them. If you want to develop it faster than trial and error allows, Leland's AI program teaches agentic workflows hands-on, and you can work directly with AI automation and agents coaches, or join a live session through upcoming AI events.

See also: Top 10 AI Consultants and Experts

• The 5 Best AI Coding Agents: Pros & Cons, Reviews, & Which is Best for You
• The 5 Best AI Tools & Agents for Business: Reviewed & Ranked
• The 5 Best AI Tools & Agents for Developers: Reviewed & Ranked
• The 5 Best AI Voice Agents (By Type & Function)
• The 5 Best AI Newsletters to Subscribe
• The 5 Best AI Tools & Agents for Finance: Reviewed & Ranked
• The 5 Best AI Tools & Agents for Video Editing: Reviewed & Ranked
• The 5 Best AI Personal Assistants: Reviewed & Ranked

FAQs

What is a subagent in Claude Code?

• A subagent is a specialized Claude instance that the main session spawns through the Agent tool, formerly called the Task tool, to handle specialized tasks. Each subagent operates in its own context window with a custom system prompt and scoped tool access, then returns a single result to the main agent. Subagents cannot spawn further subagents and cannot communicate with each other.

How do subagents differ from skills?

• Skills are instruction files Claude loads into its current context when a task calls for them, and they add knowledge without creating a new agent. Subagents are separate instances with separate contexts. Use a skill for a reusable procedure, like converting a document format. Use a subagent for a multi-step workflow with decision points, like reviewing a pull request. They compose well, since a subagent can invoke skills while doing its work.

Can Claude Code run subagents in parallel?

• Yes. The main session can spawn multiple subagents that run concurrently, and as of v2.1.198, they run as background tasks by default, so your session stays responsive. Parallel agents work best on truly independent jobs, like researching separate subsystems at the same time. For parallel work that modifies files, use worktree isolation to prevent conflicts.

Do subagents make Claude Code more expensive?

• They increase token usage, since every subagent opens its own context window and multi-agent workflows run roughly 4 to 7 times the tokens of a single session. Prompt caching absorbs much of the cost of paid API usage, and routing subagents to cheaper models with the model field cuts it further. On subscription plans, heavy parallel spawning is the fastest route to rate limits, so scope agents narrowly.

Why isn't Claude using my custom subagent?

• Automatic routing to custom agents is a known weak point in 2026. The fix is a sharper description with explicit "use when" conditions, plus explicit invocation by name when the delegation matters. Also, check that the agent file loaded at all. If you created the first file in a brand-new agents directory mid-session, restart Claude Code.

Should I use subagents or agent teams?

• Default to subagents. They're native, stable, cheaper, and cover research, review, and verification well. Reach for agent teams, which are experimental and enabled by an environment variable, when independent workstreams genuinely need to coordinate with each other, like a cross-layer feature or a multi-perspective review. If your tasks are sequential or touch the same files, a single session or subagents will beat a team on both speed and cost.