Claude Code subagents help when a focused task can leave the main conversation, run with clear boundaries, and return a summary. I use them for separate research and review work. I keep dependent steps and overlapping edits under one owner.
That boundary matters more than the number of workers.
What a Claude Code subagent is
A normal subagent is a delegated worker inside one Claude Code session. It starts with its own context, instructions, tools, and permissions, then returns its result to the conversation that called it. The noisy file reads, logs, and search output stay outside the main context. The current Anthropic documentation describes this as the main reason to use one.
Choose based on how much context and coordination the work needs:
| Choice | Context and coordination | Use it when |
|---|---|---|
| Main conversation | Keeps the current discussion and decisions | The next step depends on what you are discussing now |
| Normal subagent | Starts fresh with a focused task and returns a result | A side task can be explained on its own |
| Full-context fork | Inherits the conversation so far and returns a result | A fresh worker would need too much background |
| Agent team | Uses separate sessions that can coordinate with each other | Workers need to share findings or manage a joint task list |
Use the smallest option that fits. More coordination has a cost, even when the agents are doing the typing.
Built-in and custom subagents
Claude Code includes built-in subagents for exploration, planning, and general work. Claude can select one when your request matches its purpose.
A custom subagent earns its place when the same focused role, tool boundary, or output format comes up again. Put a project-specific definition in .claude/agents/ so it can live with the repository. Put a personal definition in ~/.claude/agents/ when you want it available across your projects. Claude Code loads both locations, and only name and description are required in the file frontmatter.
On Claude Code v2.1.198 and later, /agents no longer opens the old creation wizard. Ask Claude to create the file or edit the Markdown directly, then review what it wrote. The command now prints a reminder rather than opening the old management panel. Anthropic records that change in its subagents documentation.
Create one focused subagent
One project-level worker is enough to show the pattern. Save it as .claude/agents/accessibility-reviewer.md:
---
name: accessibility-reviewer
description: Reviews HTML templates for accessibility issues. Use before a page release.
tools: Read, Grep, Glob
model: inherit
---
Review HTML templates without editing them.
Report the file, line, issue, user impact, and a suggested fix.
Group repeated issues and state when you are unsure.The tool list gives this worker only file-reading and search tools. Its job is narrow, and its output is easy to review. That is enough. A catalogue of twenty agent personas mostly gives you twenty definitions to maintain.
Anthropic's agent-loading guidance says Claude Code watches existing agent directories for file changes. If this is the first file in a newly created agents directory, restart the session so Claude can discover it.
Invoke and monitor the right worker
Claude can delegate automatically when your request matches a subagent description. Naming a subagent in plain language encourages the choice, but Claude still decides. Anthropic's invocation guidance says an @ mention guarantees that the named subagent runs for that task.
@"accessibility-reviewer (agent)" check the templates in app/views/blog.
Return one report and do not edit files.Type @ and pick the worker from the list rather than typing that quoted form by hand. You can also write it manually as @agent-accessibility-reviewer, in which case the list shows file matches while you type and the mention still resolves when you submit. Either way, Claude writes the task prompt from your full message, so the goal, paths, limits, and expected result need to be clear.
Background subagents appear in the current session. /tasks lets you inspect, attach to, or stop background work, including recently completed subagents. If a background worker reaches a tool call that needs permission, Claude Code surfaces that prompt in the main session and names the worker asking for it. These controls are documented in Create custom subagents and Run agents in parallel.
Do not assume that a batch request creates one worker per item. Claude may keep the work in the main conversation, combine items, or run them in rounds. If the split matters, name it.
Use /subtask when the worker needs your context
/subtask has a specific meaning on Claude Code v2.1.212 and later. It starts a forked subagent that inherits the full conversation so far, as described in Anthropic's current subagents documentation. Use it when a normal subagent would need the same long explanation you already gave the main conversation.
/subtask review the parser changes we agreed on and draft the missing tests. Do not edit files.A fork gives up the input isolation of a normal subagent. It sees the parent system prompt, tools, model, and message history, but its tool output stays outside the main context and only the final result returns. Use it for context-heavy side work, not as the default handoff. The command requires v2.1.212 or later and is unavailable when agent view is disabled.
Split independent work
CSS, JavaScript, and HTML checks can run separately because one result does not depend on another. Ask for the split and the final format:
Review this project in three independent areas:
1. CSS structure and likely responsive problems
2. JavaScript errors and fragile behavior
3. HTML semantics, links, and accessibility basics
Use separate read-only subagents for the three reviews.
When they finish, return one report grouped by severity.
Do not edit files.Keep the first pass read-only, so you can compare the findings before anything changes. Decide which findings deserve edits after seeing the whole report.
Always ask for synthesis
Several correct reports can still leave you with a mess. Ask the main conversation to combine them into one result.
Check each CSS file for deprecated properties.
Return one table with the file, line, property, browser risk, and recommended replacement.
Group repeated findings instead of listing the same issue many times.I ask for one combined result, ranked by what changes the decision. Otherwise the review becomes a pile of agent summaries, and somebody still has to turn that pile into a decision.
Keep dependent work sequential
Do not parallelize steps that build on each other:
- inspect the current data model
- decide the migration
- create the migration
- run and verify it
The decision in step two needs the evidence from step one. The migration and verification need the agreed decision.
The same applies when two workers would edit the same files. Give each worker a separate area or use worktree isolation so each one gets a separate checkout. Separate checkouts reduce direct file collisions, but their branches can still conflict when you combine the work. A worktree does not make a weak plan correct or remove the need for review.
For a file-organization task, start with a plan:
Review the downloads folder and propose where each file should move.
Do not move, rename, or delete anything until I approve the plan.Parallel deletion is still deletion. More workers do not make the decision safer.
Account for context, permissions, and cost
A normal subagent starts with fresh context. It receives a task message instead of your full conversation history, so include the goal, constraints, relevant paths, and expected output. A fork is the exception because it inherits the conversation.
Foreground work blocks the main conversation while it runs. Background work lets you continue, but permission questions still come back to the main session. Several running workers also multiply token use and can consume concurrency or rate limits. The current subagents documentation gives Agent-tool subagents a default concurrent limit of 20, but that is a guardrail, not a target. Subagents can also spawn their own subagents, three layers below the main conversation by default.
Anthropic's parallel-work guidance warns that several sessions or subagents multiply token use. The cost guide recommends subagents for verbose operations because only the summary returns to the main conversation. Delegation keeps verbose output out of the main context, but total token use still grows.
Choose a cheaper model for a simple worker only after checking whether its output is good enough for the task. Do not count savings before measuring the result.
Subagents or agent teams
Subagents report results to the conversation that spawned them. Agent teams use separate sessions that can communicate directly and may share a task list. Teams suit work that needs discussion and coordination between workers, but they add coordination overhead and use more tokens. They are also experimental and off by default, so you have to turn them on before you can try one.
That is the useful boundary. Use subagents when workers report back to one conversation. Reach for an agent team only when the workers need to coordinate with each other. Anthropic's agent teams documentation covers the current product behavior.
Other ways to run work in parallel
All of that happens inside one conversation. Claude Code can also run work outside it.
Agent view opens with claude agents and gives you one screen for sessions running in the background: what each one is doing, and which ones are waiting on you. Before a background session edits files it moves into its own git worktree, so two of them cannot write over each other. It is a research preview, so expect the interface to change.
Dynamic workflows move the plan into a script instead of Claude's turn-by-turn judgment. You describe the job, Claude writes the script, and a runtime spawns the agents and keeps the intermediate results out of the conversation. That fits a codebase-wide audit, a large migration, or research that needs its sources cross-checked against each other. /workflows lists the runs, and /deep-research is the bundled one worth trying first.
/batch is the packaged version for one large change: it splits the work across 5 to 30 worktree-isolated subagents that each open a pull request. Convenient, and still no substitute for reading the diffs.
Sessions you start yourself can also pass findings between each other with cross-session messaging.
How I use subagents
My website has rules for areas such as CSS, security, PHP, and the database. When I audit those rules against the codebase, separate read-only workers can inspect different areas and return one report.
This saves me time because each worker checks one area and the main conversation combines the findings. I still review the report before changing a rule.
Start small:
- name two genuinely independent checks;
- make the first pass read-only;
- provide the paths, constraints, and expected output;
- ask for one combined result;
- review the findings before any edits;
- add parallel editing only when file ownership and recovery are clear.
Sources
- Create custom subagents, Anthropic. Supports built-in and custom subagents, file scopes, frontmatter, invocation, permissions, monitoring, concurrency, and
/subtaskfork behavior. - Run agents in parallel, Anthropic. Compares subagents, full-context forks, agent view, agent teams, worktrees, and the cost of running several workers.
- Manage costs effectively, Anthropic. Supports using subagents to keep verbose output outside the main context and explains the cost tradeoff.
- Orchestrate teams of Claude Code sessions, Anthropic. Supports the short subagents-versus-agent-teams boundary and coordination overhead.
- Run parallel sessions with worktrees, Anthropic. Supports using separate checkouts to isolate file changes.
- Manage agents with agent view, Anthropic. Supports the background-session screen, the automatic worktree move before edits, and the research-preview status.
- Orchestrate subagents at scale with dynamic workflows, Anthropic. Supports script-held orchestration, the
/workflowslist, and the bundled/deep-researchworkflow.
Get Personalized Help
Copy this prompt to ChatGPT, Claude, or your favorite AI assistant. Fill in your details and get guidance tailored to your specific situation.
I read https://ivanmisic.net/blog/ai-tools/doing-multiple-things-at-once about using Claude Code subagents for independent, bounded work. Help me decide whether and how to delegate my task. My situation: - Goal and deliverable: [WHAT MUST BE DONE AND WHAT THE FINAL RESULT SHOULD LOOK LIKE] - Candidate work areas: [PARTS I THINK COULD RUN SEPARATELY] - Dependencies and shared context: [WHAT EACH PART NEEDS FROM OTHER PARTS OR THIS CONVERSATION] - Files and ownership: [PATHS EACH PART WOULD READ OR EDIT, INCLUDING ANY OVERLAP] - Risk and limits: [READ-ONLY OR EDITING, PERMISSIONS, COST, DEADLINE, AND RECOVERY POINT] First decide whether this belongs in the main conversation, normal subagents, a full-context fork, or a more coordinated setup. Use the smallest option that fits. Show which steps are genuinely independent and which must remain sequential because they depend on earlier evidence or touch the same files. If delegation is justified, produce: 1. a task split with one owner per path or decision; 2. a focused prompt for each worker, including goal, relevant paths, constraints, and return format; 3. the order and concurrency limits; 4. a synthesis prompt that combines findings, removes duplicates, and ranks what changes the decision; 5. review, permission, cost, and rollback checkpoints before any edits. Prefer a read-only first pass when findings need comparison. Do not claim that worktrees remove merge risk, that more workers improve a weak plan, or that a background task can bypass permission questions. If safe parallelization is not possible, say why and give a sequential plan instead.