\Previously in the seriesThe Bare Minimum SetupCLAUDE.md Done RightModels, Tiers, and EffortThe Context Window TaxHooks That Guard Your CodeMCP Servers Worth AddingSkills That Actually FireIntroductionEvery tool call, file read, and exploratory detour in Claude Code's main conversation eats into the same context window. Do a codebase research pass that comes back with 4,000 tokens of findings, and that's 4,000 fewer tokens available for everything that follows — do it three or four times, and you're already compacting history before you've touched a single file.\Subagents are the mechanism for keeping that cost out of your main conversation. Each subagent runs in its own isolated context window, does its work, and returns only the result. The main session sees the summary, not the journey.\In the previous article, I covered skills — reusable slash commands that run inside your main conversation context. Subagents are a different tool for a different problem: not reusing a workflow, but isolating the cost of running one.\This is article 8 in the Navigating Claude Code series. I'll start with what a subagent actually is, then walk through the built-in ones Claude already uses on your behalf, how to write custom ones, and where the configuration choices actually move the needle.What a subagent isA subagent is a separate Claude instance that the main agent can spawn using the Agent tool. It has its own fresh context window — the parent conversation history is not included. The only way to pass information to a subagent is through the prompt string in the Agent tool call. The only way to get information back is through the subagent's final response.\That isolation is the entire point. It keeps verbose intermediate work — file traversal, codebase search, large analysis passes — from accumulating in your main session.\A few constraints worth knowing upfront:Subagents cannot spawn other subagents. Nesting isn't supported — if a subagent hits something that would normally trigger delegation, it works through it in its own context rather than spawning further.Subagents exist only for the duration of their task. Once they return a result, that instance is gone. There's no shared state between subagents running in the same session, and no memory of what a sibling agent found.Whatever the subagent returns lands in your main context verbatim. A subagent that does 8,000 tokens of internal work but writes a 3,000-token report still costs you 3,000 tokens when that report arrives. The isolation keeps you from watching the work accumulate — it doesn't protect you from a verbose result.\The practical distinction from skills: a skill loads its instructions into your main conversation and runs there. A subagent leaves that conversation entirely, does work in its own window, and returns a result. If you want to reuse a workflow, that's a skill. If you want to keep the cost of running it out of your main context, that's a subagent.Built-in SubagentsClaude Code ships with three main built-in subagents. You don't define or configure them — they activate automatically when Claude decides to use them.\Explore is a fast, read-only agent built on Haiku. Claude delegates to it when it needs to search or understand a codebase without making changes. File discovery, grep traversal, code reading — all of that happens in Explore's context, not yours. It's invoked with a thoroughness level: quick, medium, or very thorough, depending on what Claude judges the task requires.\Plan is similar to Explore but used specifically during plan mode. When you run claude --plan and Claude needs to research your codebase before presenting a plan, it sends that research to Plan. This prevents the research from consuming your main context before you've even seen the plan.\General-purpose is a full-capability agent — it inherits the main conversation's model and has access to all tools. Claude delegates to it when a task requires both exploration and modification, or involves multiple dependent steps that would be expensive to track in the main context.\You've likely already seen these agents in action. The [subagent: explore] or [agent] labels that appear during complex tasks indicate Claude has decided to offload work.Creating a Custom SubagentCustom subagents live as Markdown files with YAML frontmatter. The location determines scope:| Location | Scope ||----|----|| .claude/agents/ | Current project only || ~/.claude/agents/ | All your projects || Managed settings | Organisation-wide (admin-deployed) |\Project-level subagents belong in version control. If your team is working in the same codebase, they benefit from the same agents.\The minimal file structure:---name: code-reviewerdescription: Reviews code changes for security issues, logic bugs, and performance problems. Use after writing or modifying code.model: sonnettools: - Read - Grep - Glob---You are a code reviewer focused on security, correctness, and performance. Do not suggest style changes or formatting — only substantive issues.For each issue found, provide:- File and line reference- What the problem is- Why it matters- A concrete fix\The description field is how Claude decides whether to invoke this subagent. Write it as a statement of when to use the agent, not what the agent is. "Reviews code changes for security issues" is a routing cue. "A code review assistant" is not.\You can also create subagents interactively with /agents and let Claude generate the configuration from a description — useful when you're not sure what the system prompt should look like.Configuration options that matter.ModelThe model field is one of the highest-leverage settings. The main conversation might run on Opus for complex reasoning, but a subagent doing read-only research doesn't need that. Routing exploratory tasks to Sonnet or Haiku cuts cost without losing much quality on well-scoped work.model: haiku # or sonnet, opus\You can also set CLAUDE_CODE_SUBAGENT_MODEL as an environment variable to control which model all subagents use by default.ToolsBy default, a custom subagent inherits all tools available to the main conversation. If your subagent is a reviewer or researcher, it has no business writing files. Restrict it:tools: - Read - Grep - Glob - Bash\Or deny specific tools explicitly with disallowedTools. A subagent that can't write is a subagent that can't accidentally overwrite something mid-analysis.Permission ModeCustom subagents can run in a stricter permission mode than the parent conversation. Setting permissionMode: bypassPermissions on a trusted deploy agent is different from leaving the default, where each tool call still follows the normal permission rules.\For most custom subagents, leave this at the default. The value of locking down tools is that you don't need to think about permissions per-invocation.MemoryBy default, a subagent starts with a blank context every time. If you want a subagent to accumulate knowledge across sessions — recurring project patterns, codebase conventions it has observed — you can enable persistent memory:memory: user # persists to ~/.claude/agent-memory/\This is most useful for subagents you run frequently against the same codebase. A subagent that remembers "this project uses a custom error wrapper instead of throwing directly" saves you re-explaining that every session.Common PatternsParallel ResearchIf you need to analyse several independent areas of a codebase — say, checking API contracts, database schema, and test coverage for a feature — you can ask Claude to run these as parallel subagents:Analyse the payment module. Use three parallel subagents:one for the API layer, one for the database queries, one for test coverage.Each should return a findings summary.\Parallel dispatch only works when the tasks are genuinely independent — no shared state, no file overlap, no output from one feeding into another. When there are dependencies, subagents must run sequentially, and the ordering matters.Isolating High-Volume OperationsSome tasks produce a lot of intermediate output that you don't need in your main context. Log analysis, large file diffs, and dependency tree traversal — these are good candidates for subagent isolation. The subagent does the work and returns a condensed summary.Chaining SubagentsFor multi-step workflows, you can ask Claude to chain subagents so that the result of one feeds into the next. Research hands off to planning, planning hands off to implementation — each phase works with a summary of what came before, not the full accumulated context of everything that happened.Use the researcher agent to analyse the auth module.Then use the planner agent to turn those findings into a refactor plan.Pass the plan to the implementer agent to make the changes.\This is sequential by definition — each agent needs the prior result. The value is that only the summaries cross between phases, not the full intermediate context.The Pitfall: Verbose subagent output still costs you.The most common mistake is treating subagent isolation as free context savings. It isn't, if your subagents return walls of text.\A subagent that does 10,000 tokens of internal work but returns a 500-token structured summary saves you 9,500 tokens. A subagent that does 10,000 tokens of work and returns an 8,000-token detailed report saves you 2,000 tokens — and that 8,000-token response lands directly in your main context, where it counts against your window.\The fix is to be explicit in your subagent's system prompt about the output format:Return a maximum of 10 bullet points. Each point needs a severity level, a file reference, and one sentence describing the issue. Leave out code snippets unless there's genuinely no other way to describe the problem.\If the main session needs to dig into a specific finding, it can ask a follow-up. I'd rather get a 300-token report and ask one clarifying question than receive 3,000 tokens of preemptive detail that still doesn't cover the edge case I care about.The Pitfall: Description-driven delegation is unpredictable.Claude uses your subagent's description field to decide when to route tasks. If the description is vague or overlaps with another subagent, delegation becomes inconsistent. You'll ask Claude to "check the code," and sometimes it invokes your reviewer, sometimes it does it in-line, sometimes it uses a general-purpose.\You can bypass this entirely by naming the subagent explicitly:Use the code-reviewer agent to check the authentication module\Explicit invocation ignores the description-matching logic and calls the agent directly. For critical workflows, this is more reliable than hoping Claude's routing matches your intent.\Run /agents and you'll see every configured subagent grouped by where it came from — managed, project, user, plugin. More usefully, it flags anything being silently overridden by a same-named definition at a higher priority level. That's the first thing to check when a custom agent stops getting invoked, and you have no idea why.Best PracticesWrite descriptions as invocation cues, not capability descriptions.Match the model to the task — Haiku for read-only research, Sonnet for analysis, Opus only when the subagent needs to reason through something complex.Restrict tools to what the subagent actually needs. Read-only agents shouldn't have write access.Be explicit about the output format in the system prompt. Verbose output cancels out the context savings.Invoke by name when the workflow is important enough that you can't afford inconsistent routing.Put project subagents in .claude/agents/ and check them into version control.ConclusionSubagents are not a feature for complex agentic pipelines only. Even in a normal session, the built-in Explore and Plan subagents are already working to keep exploratory work out of your main context. Custom subagents extend that pattern to your own workflows — code review, research passes, dependency analysis, anything that produces output you'd rather receive as a summary than watch accumulate.\The next article covers agent teams, which take a different approach: instead of one orchestrator spawning isolated workers that report back independently, agent teams let multiple Claude instances communicate directly with each other mid-task. Subagents can parallelize work, but they can't share findings or challenge each other's results without the main agent acting as intermediary. That's the bottleneck agent teams remove — and the reason the two systems exist alongside each other rather than one replacing the other.\