Subagents

Status: 🟩 COMPLETE (🟦 LIVING) Last updated: 2026-06-19 Plain-English tagline: A fresh Claude session launched mid-task with its own context, prompt, and tools. Use them for parallel work, context isolation, or specialized prompts.

---

In plain English

When Claude Code is working on something for you, the main session has a context window — a finite amount of “memory” for the current conversation. As the session progresses, files get read, tool results accumulate, your messages pile up. Past a certain size, the context fills up and the model starts losing track of earlier details.

A subagent is a fresh Claude session launched in the middle of your work. It has:

• Its own context window (starting empty)
• Its own system prompt (often specialized)
• Its own tool allowlist
• A single mission

The main session spawns the subagent with a focused task (e.g. “find every file that references the old API endpoint”), the subagent does the work, and returns a single summary back to the main session. The main session never sees the noise — all the file reads, tool calls, intermediate analysis stay in the subagent’s context.

For long-running tasks or research-heavy questions, subagents are how Claude Code keeps the main session lean.

---

Why it matters

Three concrete benefits:

1. Context isolation. A search across 50 files doesn’t dump 50 files into your main session — the subagent does the reading, returns the result.
2. Parallelism. Multiple subagents can run simultaneously. Three independent searches finish in the time of one.
3. Specialized prompts. A code-review subagent has a different prompt than the main session. A planning subagent has a different one. Different mindsets for different jobs, without polluting the main one.

For complex work, well-used subagents are the difference between “running out of context halfway through” and “keeping the main session focused throughout.”

---

The built-in subagent types

Your current setup has these:

Subagent type	Best for	Tools
claude	General catch-all when no specific agent fits	All tools
Explore	Fast read-only search; locating code, files, references	Read, Glob, Grep, Web tools — no Edit/Write
general-purpose	Multi-step research or open-ended tasks	All tools
Plan	Designing implementation plans; architectural thinking	All tools except Edit/Write
claude-code-guide	Questions about Claude Code itself / SDK / Claude API	Glob, Grep, Read, WebFetch, WebSearch
statusline-setup	Specifically for configuring the status line	Read, Edit

You spawn one via the Agent tool, specifying the type.

---

When to use which type

Explore — for “where does X live?” questions

You: "Find every file that imports from `lib/supabase-server`."

The Explore subagent does the search with Glob and Grep, reads relevant snippets, and returns a list. Your main session gets the answer without the search noise.

Specify search breadth: quick (one targeted lookup), medium (moderate exploration), very thorough (search across multiple locations and naming conventions).

Plan — for “how should I approach this?” questions

You: "Plan the migration from the old auth system to Supabase Auth."

The Plan subagent thinks architecturally — produces a step-by-step plan, identifies critical files, considers trade-offs. Returns a plan without executing it.

This is one of the most valuable subagents. Use it before any non-trivial change. The plan it returns gives you a chance to redirect before any code is written.

general-purpose — for everything else

When the task has multiple steps and might involve writes, but doesn’t fit a more specific type. The catch-all when you want the benefits of isolation but need full tool access.

claude-code-guide — for “how does Claude Code do X?” questions

When you’re asking about Claude Code itself (a feature, a setting, an option, a behavior), this subagent has the right context to answer authoritatively.

claude — default for FleetView and untyped tasks

The general default. Same capabilities as the main session. Use it when you want context isolation without a specialized prompt.

statusline-setup — niche

Specifically for configuring the Claude Code status line. Most users never need to spawn this directly.

---

Custom subagents

You can define your own subagent types in .claude/agents/<name>.md:

---
name: code-reviewer
description: Independent code review of pending changes, focused on correctness and security
tools: [Read, Glob, Grep, Bash]
permissions: ask
---
 
You are an independent code reviewer.
 
For the code provided:
 
1. Identify any correctness bugs.
2. Flag any security issues (especially OWASP Top 10).
3. Suggest small improvements only if they fix a real issue.
4. Do NOT suggest stylistic changes or refactors.
 
Return your findings as:
- Bugs (must fix)
- Security (must fix)
- Suggestions (consider)

After saving this file, the code-reviewer subagent is available. Spawn it like any built-in.

The frontmatter controls:

• name — slug used to spawn
• description — when this subagent fits
• tools — restricted tool list (omit for full access)
• permissions — override default permission mode

---

A concrete example: parallel exploration

Suppose you want to understand a codebase fast. You spawn three subagents in parallel:

Main session:
- Spawn Explore subagent: "Map the routing structure of the app — what URLs exist, what files handle them?"
- Spawn Explore subagent: "Map the database schema — what tables, what relationships?"
- Spawn Explore subagent: "Find every use of the Supabase service_role key — should be ONLY server-side."

All three run simultaneously. Each one does its file reads, runs greps, looks at imports. After ~30 seconds, all three return summaries to your main session. You now have the lay of the land — without 50 file contents bloating your context.

This pattern is especially useful when joining an existing project.

---

Subagents vs the main session

Aspect	Main session	Subagent
Context window	Yours; persists through the conversation	Fresh; ends with the subagent
You see tool calls	Yes	No (just the final summary)
Can edit files	Usually yes (with permissions)	Depends on subagent type
Cost	Tracked in your session	Each spawn adds cost
Parallel	One conversation at a time	Multiple subagents can run together
Inherits memory	Yes	Yes (CLAUDE.md, MEMORY.md still loaded)
Inherits prior conversation	Yes	NO — they start fresh

Critical caveat: subagents do NOT inherit the main session’s conversation. They start with the system prompt + your spawn message. If you’ve told the main session something it needs to know, the spawn prompt must include it.

---

Foreground vs background subagents

You can choose:

• Foreground (default) — main session waits for the subagent to finish, gets the result, proceeds. Use this when the result blocks your next step.
• Background — main session continues with other work; you’re notified when the subagent finishes. Use this when you have independent work to do in parallel.

In practice, for most uses, foreground is fine. Background is useful for long-running explorations you can fire-and-forget.

---

Subagents and worktrees

Some subagents can run in an isolated git worktree — a temporary clone of the repo where the subagent’s changes don’t touch your working files until you choose to merge them. Useful for:

• Risky experiments where you want to easily discard the result
• Multiple parallel subagents working on related but independent changes
• Letting a subagent take destructive actions safely

If you spawn with isolation: "worktree", the agent gets its own branch and folder. If it doesn’t make changes, the worktree is auto-cleaned up. If it does, you can review the branch and merge selectively.

---

What NOT to use subagents for

• Trivial single-step tasks. Spawning a subagent has overhead. For “read this one file and tell me the entry point,” just do it in the main session.
• Conversational context-dependent work. If the subagent needs to understand the back-and-forth you’ve had, the cold-start cost is high. Pass the relevant context explicitly.
• Iterative refinement with you in the loop. Subagents return a single result. If you need three rounds of “make it more X, less Y,” that’s not the right fit.
• Tasks the main session can do well without bloat. If your context isn’t filling up, the isolation benefit is small.

---

The cost dimension

Each subagent spawn is a separate billed conversation. For a single subagent on a focused task, this is cheap (often a few cents). But:

• Three parallel subagents = 3× the model calls
• A subagent that itself spawns more subagents (transitively) compounds
• Long-running subagents with many tool calls add up

The trade-off is: more cost, more capability, cleaner main session. For occasional use, the cost is negligible. For high-volume agent systems, profile and optimize.

---

Common gotchas

• Subagents don’t see your conversation. Always include relevant context in the spawn prompt. “Continue what you were doing” doesn’t work.

• Returns are summarized, not raw. The subagent’s Agent tool result is the subagent’s final text response — not its tool call history. If you need detail, ask the subagent to return more detail.

• Subagent failures don’t crash the main session. They return an error message that the main session can act on (retry, ask different way, give up).

• Permissions can differ. A subagent restricted to read-only can’t write. If you spawn an Explore to do an edit, it’ll fail. Use the right type.

• Multiple subagents writing files in parallel can conflict. They share the filesystem. If two parallel subagents both want to edit the same file, you’ll get races. Use worktrees or sequential spawning.

• The Agent tool isn’t always called “Agent.” In some Claude Code versions or in MCP-mediated contexts, the spawn mechanism varies. The concept is the same.

• Subagents share your MCP servers. Tools you’ve configured at the user level are available to subagents too. That’s usually fine but can be surprising.

• Recursive subagent spawning is allowed but quickly opaque. A subagent spawning its own subagent works, but you lose visibility into the inner one. Avoid unless necessary.

• Cost surprises. A complex parallel subagent task can produce a meaningful bill. Watch your usage if you spawn many or long-running subagents.

---

See also

• Claude Code deep dive 🟩 🟦 — subagents are one of six primitives
• Agents 🟩 — the underlying concept
• Slash commands 🟩 — /agents lists and manages
• The memory system 🟩 — subagents inherit
• settings.json 🟩 — where custom subagent types are registered
• Plugins 🟩 — plugins can ship subagent definitions

---

Sources

• Anthropic — Subagents docs
• Anthropic — Building effective agents
• Claude Code: Hooks, Subagents & Skills Complete Guide (2026)