Claude Code subagents are isolated AI workers that your main Claude session can spin up, delegate tasks to, and collect results from — letting you run multiple jobs in parallel instead of waiting for each one to finish sequentially. If you’ve ever watched Claude slowly work through a 10-file refactor one file at a time, subagents are the fix.
What Are Claude Code Subagents? (Architecture and How They Work)
Claude Code subagents are purpose-built AI workers that run inside their own isolated context windows, each with a dedicated system prompt, a specific toolset, and optionally a different model than the parent session. When the main agent calls the Agent tool, it spawns a subagent, passes a task description, and the subagent executes fully independently — reading files, running searches, writing code — then returns only its final result. The parent’s context window never sees the subagent’s intermediate steps, tool outputs, or reasoning chains. This context isolation is the key architectural advantage: a subagent researching API documentation might consume 200K tokens of intermediate output, but the parent receives a clean 500-word summary.
Claude Code supports 16+ parallel agents running simultaneously for complex workflows. Each subagent is a first-class Claude instance with the same tool access as the parent — Bash, Read, Write, Grep, Glob — or a restricted subset you define. The separation isn’t just logical: with the isolation: "worktree" flag, each subagent gets its own git worktree, meaning they can write to different files without merge conflicts. Opus 4.7 became the default model for Claude Code starting April 23, 2026, but individual subagents can override this to use cheaper models for routine tasks — a design decision that directly drives cost and speed. The agent lifecycle is: parent delegates → subagent spawns in fresh context → subagent works autonomously → subagent returns result → parent continues. There is no back-and-forth; once spawned, a subagent runs to completion.
How Subagent Context Isolation Works
Subagent context isolation means the subagent’s entire conversation thread — tool calls, search results, file reads — exists in a separate memory space from the parent. When the subagent finishes, only the text in its final message comes back to the parent. A subagent exploring 50,000 lines of legacy code returns “Found 3 relevant functions in auth/middleware.go” — not the full exploration trace. This keeps the parent’s context window clean and focused on high-level coordination rather than drowning in implementation noise.
Subagents vs Agent Teams: Choosing the Right Pattern
Subagents and Agent Teams solve different coordination problems. Subagents are the right choice when workers don’t need to communicate with each other — each one gets a task, runs it, and reports back to the parent. Agent Teams are for situations where workers need to share state, pass intermediate results between themselves, or react to each other’s outputs during execution. If you’re running 9 parallel code reviews (each reviewer looks at a different quality dimension), subagents are ideal: they’re independent, they don’t need to know what the security reviewer found before the performance reviewer starts. If you’re building a multi-step pipeline where Step B needs Step A’s output before it can begin, that’s a sequential workflow, and orchestrating it through the parent is cleaner than subagents.
The practical decision framework comes down to three questions: (1) Can all tasks start at the same time with the same inputs? (2) Does each task produce a standalone result? (3) Are the tasks touching different files or resources? If yes to all three, use parallel subagents. If any task depends on another task’s output, run them sequentially through the parent or consider an Agent Team with shared memory. Cost matters here too: parallel subagents all bill simultaneously, so spawning 10 agents at once costs the same in wall-clock time as one but burns 10× the tokens in the same minute.
When Sequential Beats Parallel
Sequential subagent execution makes sense when the output of one step is the input for the next — a research subagent finds the relevant files, then a coding subagent rewrites them based on those findings. Running these in parallel would mean the coding agent starts without knowing which files to touch. The parent orchestrates sequentially: spawn Researcher → wait for result → spawn Coder with Researcher’s output → wait for result → commit.
How to Create Custom Subagents (agents/ directory and frontmatter)
Custom subagents live as Markdown files in your project’s .claude/agents/ directory. Each file defines a specialized worker: its name (used to invoke it), a description (used by the parent to decide when to delegate to it), optional tool restrictions, and an optional model override. The frontmatter fields are name, description, tools, and model. The body of the file is the system prompt — the instructions the subagent follows when it runs.
---
name: security-reviewer
description: Reviews code changes for security vulnerabilities — SQL injection, XSS, auth bypasses, secrets in code. Use when reviewing PRs or auditing new endpoints.
tools: Read, Grep, Glob
model: claude-sonnet-4-6
---
You are a security-focused code reviewer. When given a file or diff, check for:
- SQL injection via string concatenation in queries
- XSS via unescaped user input in templates
- Hardcoded secrets, API keys, or credentials
- Auth bypass patterns (missing middleware, direct object references)
- Insecure deserialization
Report each finding with: file path, line number, severity (Critical/High/Medium), and a one-sentence fix recommendation.
Save this as .claude/agents/security-reviewer.md. Now the parent session’s Agent tool can invoke it by description match — or you can explicitly reference it. The tools field restricts the subagent to only Read, Grep, and Glob: it can look at code but not execute shell commands or write files. This is a security boundary for untrusted or narrow tasks. The model field routes this subagent to claude-sonnet-4-6 instead of the default Opus — appropriate for a structured review task that doesn’t require deep reasoning.
Global vs Project Subagents
Subagents in ~/.claude/agents/ are global and available in every project. Subagents in .claude/agents/ (project-level) are only available in that project. Global agents are ideal for utility workers you reuse everywhere — a grep-expert that knows advanced search patterns, a commit-message-writer that follows your conventions. Project agents encode domain-specific knowledge: a schema-validator that knows your company’s API schema format, or a migration-reviewer that knows your database conventions.
Running Parallel Subagents for 10x Faster Development
Parallel subagent execution is the most direct path to faster development in Claude Code. Instead of reading 10 files sequentially — each file read blocking the next — you delegate all 10 reads simultaneously and wait for the first to finish while the others run in the background. The explicit pattern is to tell Claude: “Use parallel subagents for each of these tasks” and list independent work items. Claude’s internal Agent tool accepts a run_in_background flag that makes this automatic for independent work.
A real-world benchmark: exploring 5 large files for API usage patterns takes roughly 45 seconds sequentially (9 seconds per file). Running 5 subagents in parallel returns all results in ~12 seconds — the time of the slowest single lookup. The split-and-merge pattern scales this further: 50 functions split into 10 batches of 5, all 10 batches run simultaneously, results merged by the parent. Review time for a 50-function audit drops from 7+ minutes to under 90 seconds. The /resume command on large sessions is up to 67% faster on 40MB+ sessions after recent Claude Code optimizations, meaning even the overhead of managing large parallel sessions has been reduced.
Prompting for Parallel Execution
The most reliable way to trigger parallel subagents is explicit instruction in your prompt:
Claude will spawn 4 agents simultaneously, each reading and analyzing one file, then synthesize the results. Without “in parallel” or “using separate subagents,” Claude may default to sequential execution in a single context.
Git Worktrees + Subagents: True File Isolation for Parallel Work
The critical constraint on parallel subagents is file conflicts: if two subagents try to write to the same file simultaneously, one will overwrite the other’s changes. The isolation: "worktree" flag solves this at the filesystem level. When a subagent runs with worktree isolation, Claude Code creates a new git worktree — a separate working directory linked to the same repository — and the subagent operates entirely within that worktree. The main branch and other worktrees are unaffected until you explicitly merge.
# In your prompt or subagent definition:
# isolation: "worktree" enables per-subagent git worktrees
The workflow for parallel feature development: define 3 subagents, each working on a different feature branch in its own worktree. Subagent A adds the user profile endpoint, Subagent B adds the notification system, Subagent C adds the analytics dashboard. All three run simultaneously. Each commits to its worktree’s branch. The parent then reviews the three branches, runs tests, and merges the passing ones. This is genuine parallel development — not just parallel reading, but parallel writing with zero risk of interference. Worktrees are automatically cleaned up if the subagent makes no changes; if changes were made, the path and branch are returned so the parent can inspect and merge.
Worktree Isolation Tradeoffs
Worktree isolation adds overhead: each worktree is a full working directory copy (though shared via git’s object store, so not as expensive as a full clone). For read-only tasks — code analysis, documentation lookup, search — the overhead isn’t worth it; just run parallel subagents without isolation. Reserve worktree isolation for subagents that will write files, create migrations, or make commits. The rule of thumb: if the subagent’s output is a text result, no isolation needed. If the output is file changes, use isolation: "worktree".
Model Selection Strategy: Opus, Sonnet, and Haiku for Cost Optimization
Claude Code’s model routing capability — assigning different models to different subagents — is one of the most underused cost optimization levers available. Opus output tokens cost nearly 19× more than Haiku output tokens: a 5,000-token task costs $0.375 with Opus vs $0.02 with Haiku. The Advisor Strategy (Opus for planning + Sonnet/Haiku for execution) cuts costs 11% while improving code quality compared to running everything on Opus. The logic: Opus’s reasoning advantage matters most for ambiguous, multi-step decisions. For structured, well-defined tasks — format a JSON file, check syntax, count lines, grep for a pattern — Haiku is just as accurate and costs a fraction of the price.
The routing framework by task type:
| Task Type | Recommended Model | Why |
|---|---|---|
| Architecture decisions, complex debugging | Opus 4.7 | Needs deep reasoning |
| Feature implementation, code generation | Sonnet 4.6 | Best speed/quality balance |
| File lookup, syntax check, grep, count | Haiku 4.5 | Routine, deterministic output |
| Code review (structured checklist) | Sonnet 4.6 | Pattern matching, not reasoning |
| Research synthesis, writing documentation | Sonnet 4.6 | High-quality text, not code logic |
The model field in a subagent’s frontmatter overrides the session default:
---
name: fast-grep
description: Finds function definitions, import patterns, and usage examples quickly.
tools: Read, Grep, Glob
model: claude-haiku-4-5-20251001
---
You are a fast search specialist. Return exact file paths and line numbers. No explanations.
A realistic cost comparison for a 20-file codebase audit: all-Opus runs at ~$1.50 total. Routed (Opus orchestrator, Sonnet reviewers, Haiku for file lookups) runs at ~$0.35. Same quality on the output that matters; 77% cheaper on the routine steps.
5 Real-World Subagent Patterns Every Developer Should Know
Real-world subagent patterns are reusable templates for common development workflows that benefit from delegation, parallelism, or context isolation. Each pattern targets a specific bottleneck: slow sequential file reads, contaminated context windows, bulk processing, comprehensive code review, and complex multi-phase tasks. Knowing these five patterns means you can immediately apply subagents to concrete situations rather than designing workflows from scratch. The patterns below come from production use cases, including the 9-agent code review framework that reduced review time from minutes to seconds, and the split-and-merge pattern used for auditing codebases with 50+ functions simultaneously. Two factors determine which pattern to reach for: whether tasks are independent (parallel patterns) or sequential (pipeline patterns), and whether tasks produce file changes (worktree isolation required) or just text results (no isolation needed). Start with the parallel code review pattern — it’s immediately applicable to any PR workflow and demonstrates the full subagent value proposition with zero custom setup required beyond listing what each reviewer should check.
Pattern 1: 9-Agent Parallel Code Review
Spawn 9 subagents simultaneously, each focused on one quality dimension:
- Security reviewer (injection, auth, secrets)
- Performance reviewer (N+1 queries, large allocations)
- Error handling reviewer (unhandled exceptions, missing rollbacks)
- Type safety reviewer (any casts, missing null checks)
- Test coverage reviewer (untested paths, edge cases)
- Documentation reviewer (missing docstrings, outdated comments)
- Dependency reviewer (new packages, license issues)
- API contract reviewer (breaking changes, versioning)
- Accessibility reviewer (for frontend changes)
Each reviewer reads the same diff but focuses on its own checklist. The parent collects 9 reports and synthesizes a final review. Review time drops from 5+ minutes to under 60 seconds.
Pattern 2: Explore-Plan-Execute Pipeline
Three sequential subagents for complex features: (1) Explorer scans the codebase to find relevant files, patterns, and potential conflicts; (2) Planner takes the Explorer’s report and drafts a step-by-step implementation plan; (3) Executor implements the plan file by file using worktree isolation. The parent’s context never fills up with raw exploration data — it receives clean handoffs at each phase boundary.
Pattern 3: Split-and-Merge for Bulk Processing
For tasks like “add JSDoc comments to 50 functions” or “migrate 40 tests from Jest to Vitest”: split the work into batches of 5-10, spawn one subagent per batch, collect results, merge. Each subagent handles a bounded, well-defined chunk. The parent’s job is coordination and final merge, not execution.
Pattern 4: Context-Clean Research
Delegate all web searches, documentation lookups, and file explorations to subagents before starting implementation. The subagent returns a 200-word briefing. The parent implements against the briefing without ever seeing the raw search results. This keeps the implementation context clean and prevents the 100K-token research dumps that slow down late-session performance.
Pattern 5: Parallel Feature Branches
For independent features on the same sprint: each subagent gets a worktree, a feature spec, and a deadline. They develop in parallel. The parent reviews each branch, runs the test suite, and merges passing branches. The bottleneck shifts from “one feature at a time” to “review and merge throughput.”
Getting Started with Community Subagents (awesome-claude-code-subagents)
The VoltAgent awesome-claude-code-subagents repository on GitHub contains 100+ specialized community subagents covering everything from Rust borrow checker guidance to Next.js performance auditing to SQL query optimization. Rather than writing every subagent from scratch, this library is the fastest way to get production-grade subagents into your workflow. Each entry in the repo is a ready-to-use .md file with tested frontmatter and a proven system prompt. The community has already debugged the edge cases: prompt phrasing that reliably triggers the right behavior, tool restrictions that prevent subagents from taking destructive actions, model assignments tuned for each task type.
To get started: browse the repository’s categories (Security, Performance, Testing, Documentation, Architecture), copy the files for the subagents most relevant to your work, and drop them into .claude/agents/ in your project or ~/.claude/agents/ for global access. Test each subagent on a small task before including it in production workflows. The most-forked entries as of early 2026 are the security-reviewer, the test-generator, and the migration-planner — all representing tasks that benefit from focused context and structured output.
Writing Your First Custom Subagent
Start with a task you currently delegate to Claude via long, repeated prompts. If you find yourself typing the same 200-word instruction block every time you want a certain kind of review or analysis, that’s a subagent. Write the instruction block into a frontmatter .md file, decide which tools the subagent needs, choose the cheapest model that handles the task reliably, and save it to .claude/agents/. Run it on 3-4 representative tasks. Adjust the system prompt based on the outputs. After 5 iterations, you’ll have a reliable, reusable worker that handles that task better than an ad-hoc prompt ever did.
FAQ
What is the difference between a Claude Code subagent and a regular Claude session? A subagent runs in an isolated context window with its own system prompt, tool access restrictions, and optional model override. The parent session delegates a task, the subagent executes it independently, and only the final result comes back to the parent. A regular session shares the full conversation history with the model on every turn.
How many subagents can run in parallel in Claude Code? Claude Code supports 16+ parallel agents simultaneously. The practical limit depends on your API rate limits and the size of each subagent’s workload. For most codebases, 5-10 parallel subagents covers the useful parallelism; beyond that, orchestration overhead starts to offset the gains.
Can subagents write to files without conflicting with each other?
Yes, if you use the isolation: "worktree" flag. Each subagent with worktree isolation gets its own git worktree — a separate working directory — so simultaneous writes go to different locations. Without worktree isolation, parallel subagents that write to the same file will conflict.
How does model routing in subagents affect cost? Significant impact. Opus output tokens cost ~19× more than Haiku. Routing routine tasks (file lookups, pattern matching, syntax checks) to Haiku and reserving Opus for architectural decisions can reduce total session costs by 70-80% with no quality loss on the simple tasks.
Where do I find pre-built community subagents for Claude Code?
The VoltAgent/awesome-claude-code-subagents repository on GitHub is the main community library with 100+ specialized subagents. Copy the relevant .md files to .claude/agents/ in your project or ~/.claude/agents/ for global use.