# How to use Claude Code subagents for parallel work

**Author:** Ivan Misic  
**Published:** 2026-01-11  
**URL:** https://ivanmisic.net/blog/ai-tools/doing-multiple-things-at-once

**In plain English**

Claude Code subagents are useful when one focused task can run in its own context and return a summary. Use them for separate research, checks, or review work. Keep dependent steps and overlapping edits under one owner.

- Use a normal subagent when the task needs its own instructions and limited tools
- Use `/subtask` when the worker needs the full conversation so far
- Name independent areas explicitly and ask the main conversation for one combined result
- Keep work sequential when one step needs the previous answer
- Treat agent teams as a different tool for workers that need to coordinate with each other

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](https://code.claude.com/docs/en/sub-agents) 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](https://code.claude.com/docs/en/sub-agents).

## Create one focused subagent

One project-level worker is enough to show the pattern. Save it as `.claude/agents/accessibility-reviewer.md`:

```markdown
---
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](https://code.claude.com/docs/en/sub-agents) 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](https://code.claude.com/docs/en/sub-agents) says an `@` mention guarantees that the named subagent runs for that task.

```text
@"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](https://code.claude.com/docs/en/sub-agents) and [Run agents in parallel](https://code.claude.com/docs/en/agents).

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](https://code.claude.com/docs/en/sub-agents). Use it when a normal subagent would need the same long explanation you already gave the main conversation.

```text
/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:

```text
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.

<figure>

![Comparison showing independent CSS, JavaScript, and HTML checks running in parallel before one combined report, while dependent analysis, decision, and implementation steps remain sequential](/images/blog/ai-tools/parallel-versus-sequential-work.png)

<figcaption>Separate checks can run in parallel and feed one report. Keep work sequential when each step needs the previous result.</figcaption>

</figure>

## Always ask for synthesis

Several correct reports can still leave you with a mess. Ask the main conversation to combine them into one result.

```text
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:

1. inspect the current data model
2. decide the migration
3. create the migration
4. 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](https://code.claude.com/docs/en/worktrees) 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:

```text
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](https://code.claude.com/docs/en/sub-agents) 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](https://code.claude.com/docs/en/agents) warns that several sessions or subagents multiply token use. The [cost guide](https://code.claude.com/docs/en/costs) 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](https://code.claude.com/docs/en/agent-teams) 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](https://code.claude.com/docs/en/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](https://code.claude.com/docs/en/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](https://code.claude.com/docs/en/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:

1. name two genuinely independent checks;
2. make the first pass read-only;
3. provide the paths, constraints, and expected output;
4. ask for one combined result;
5. review the findings before any edits;
6. add parallel editing only when file ownership and recovery are clear.

## Sources

- [Create custom subagents](https://code.claude.com/docs/en/sub-agents), Anthropic. Supports built-in and custom subagents, file scopes, frontmatter, invocation, permissions, monitoring, concurrency, and `/subtask` fork behavior.
- [Run agents in parallel](https://code.claude.com/docs/en/agents), Anthropic. Compares subagents, full-context forks, agent view, agent teams, worktrees, and the cost of running several workers.
- [Manage costs effectively](https://code.claude.com/docs/en/costs), Anthropic. Supports using subagents to keep verbose output outside the main context and explains the cost tradeoff.
- [Orchestrate teams of Claude Code sessions](https://code.claude.com/docs/en/agent-teams), Anthropic. Supports the short subagents-versus-agent-teams boundary and coordination overhead.
- [Run parallel sessions with worktrees](https://code.claude.com/docs/en/worktrees), Anthropic. Supports using separate checkouts to isolate file changes.
- [Manage agents with agent view](https://code.claude.com/docs/en/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](https://code.claude.com/docs/en/workflows), Anthropic. Supports script-held orchestration, the `/workflows` list, and the bundled `/deep-research` workflow.