61  61. Subagents (and Running Agents in Parallel)

When Claude works on a big task, its context window fills up with everything it reads. A subagent lets Claude hand a side task to a helper that has its own, fresh context, and get back only a short summary. This page explains subagents, how to create your own, and the other ways Claude Code can run several agents at once.

61.1 What a subagent is

As of Oct 6, 2026 · Official docs: Create custom subagents

A subagent is a separate AI assistant that Claude starts to handle one task. Each subagent runs in its own context window, with its own instructions (its system prompt), its own set of allowed tools, and its own permissions. When it finishes, it sends a summary back to the main conversation.

An analogy: a manager asks an intern to read 40 reports and come back with a one-page memo. The intern’s desk gets messy; the manager’s desk only receives the memo.

Main conversation:  "Where do we call the payments API?"
   │
   ├──► Explore subagent  (its own context window: reads 60 files)
   │         │
   │         └── returns: "3 places: checkout.js, refund.js, ..."
   ▼
Main conversation continues, holding only the short answer

Why use subagents?

• Keep the main conversation clean. Search results, logs, and file contents stay in the subagent’s context; only the summary comes back.
• Specialize. A subagent with focused instructions (say, a code reviewer) does one job well.
• Restrict what it can do. You can give a subagent fewer tools, for example no file editing.
• Work in parallel. Several subagents can research different areas at the same time.
• Control cost. A simple job can run on a faster, cheaper model such as Haiku.

Subagents are not free: each one sends its own requests to the model, which count toward the same usage limits as your main conversation, and their results add to your main context.

Claude starts a subagent with its Agent tool. In the transcript, a delegation appears as a row with the subagent’s name and a short task description, such as code-reviewer(Review recent changes).

61.2 Built-in subagents

As of Oct 6, 2026 · Official docs: Create custom subagents: Built-in subagents

Claude Code includes several subagents that Claude uses automatically when they fit the task:

Subagent	What it’s for	Tools
Explore	Fast searching and analysis of a codebase. Claude picks how thorough to be: quick, medium, or very thorough	Read-only (no Write or Edit)
Plan	Gathers context in plan mode before Claude presents a plan	Read-only
general-purpose	Complex, multi-step tasks that need both exploring and changing things	All tools available to subagents
Others	claude (a catch-all), statusline-setup (used by /statusline), and claude-code-guide (answers questions about Claude Code’s features)	Varies

61.3 Using subagents

As of Oct 6, 2026 · Official docs: Create custom subagents: Work with subagents

• Automatically. Claude compares your request with each subagent’s description and delegates when one fits.

• By asking. Plain English works:

  Use a subagent to run the test suite and report only the failing tests with their error messages

  Research the authentication, database, and API modules in parallel using separate subagents

• By @-mention, which guarantees that a particular subagent runs. Type @ and pick it from the list, for example @"code-reviewer (agent)" look at the auth changes (or type @agent-code-reviewer).

• For a whole session. claude --agent code-reviewer starts a session in which the main conversation itself takes on that subagent’s instructions, tools, and model.

In an interactive session, subagents run in the background by default, so you can keep working. A panel below the prompt shows the running ones, /tasks lists background work (including subagents that just finished), and if a background subagent needs permission for a tool call, the prompt appears in your main session with the subagent’s name.

61.4 Creating your own subagent

As of Oct 6, 2026 · Official docs: Create custom subagents: Configure subagents

A custom subagent is a Markdown file. It starts with frontmatter (settings written in YAML between two --- lines), followed by the subagent’s instructions, which become its system prompt. Where you save the file decides who can use it (see The .claude Folders and Settings Files):

Folder	Available in	Tip
.claude/agents/ (in a project)	That project	Commit it so your team gets it too
~/.claude/agents/	All your projects	Personal helpers

Plugins can also provide subagents. This is the docs’ read-only code reviewer, saved as .claude/agents/code-reviewer.md:

---
name: code-reviewer
description: Expert code review specialist. Proactively reviews code for quality, security, and maintainability. Use immediately after writing or modifying code.
tools: Read, Grep, Glob, Bash
model: inherit
---

You are a senior code reviewer ensuring high standards of code quality and security.

When invoked:
1. Run git diff to see recent changes
2. Focus on modified files
3. Begin review immediately

Review checklist:
- Code is clear and readable
- Functions and variables are well-named
- No duplicated code
- Proper error handling
- No exposed secrets or API keys
- Input validation implemented
- Good test coverage
- Performance considerations addressed

Provide feedback organized by priority:
- Critical issues (must fix)
- Warnings (should fix)
- Suggestions (consider improving)

Include specific examples of how to fix issues.

The most useful frontmatter fields (only name and description are required):

Field	Meaning
name	Unique name, such as code-reviewer
description	When Claude should use it. Claude reads this to decide; phrases like “use proactively” encourage automatic use
tools	Allowed tools, e.g. Read, Grep, Glob. If omitted, it gets all tools available to subagents
disallowedTools	Tools to take away, e.g. Write, Edit
model	sonnet, opus, haiku, fable, a full model ID, or inherit (same as the main conversation)
permissionMode	The permission mode it runs in, e.g. plan (ignored while your main session is in auto, acceptEdits, or bypassPermissions mode: the subagent then uses that mode)
isolation	worktree gives it its own copy of the repository (see Git Worktrees and Parallel AI Agents)

Field names must match exactly (disallowedTools, not disallowed-tools): Claude Code silently ignores fields it doesn’t recognize.

The easy way: ask Claude. Describe what you want and where to save it, then review the file it writes:

Create a personal code-improver subagent in ~/.claude/agents/ that scans files and suggests improvements for readability, performance, and best practices. It should explain each issue, show the current code, and provide an improved version. Make it read-only and have it use Sonnet.

Claude Code notices new and changed subagent files within a few seconds. The exception: if the agents folder didn’t exist when the session started, restart Claude Code. (Older tutorials show an interactive /agents wizard; in current versions /agents only prints a reminder to ask Claude or edit the files.)

Deeper dive: what a subagent can (and can’t) see

A subagent starts fresh. It does not see your conversation history, the files Claude already read, or the skills already used. It starts with:

• its own system prompt (the Markdown body of its file) plus basic details such as the working directory;
• the task message Claude writes when it delegates;
• your CLAUDE.md files and a git status snapshot (the built-in Explore and Plan subagents skip both to stay fast and cheap);
• any skills listed in its skills field.

So if you told Claude something only in the chat (“ignore the vendor/ folder”), a subagent won’t know it. Put lasting rules in CLAUDE.md, or ask Claude to include them when it delegates.

61.5 Subagent, skill, or main conversation?

As of Oct 6, 2026 · Official docs: Choose between subagents and main conversation · Extend Claude Code: Compare similar features

• Main conversation: back-and-forth work, quick targeted changes, or steps that share a lot of context (plan, build, test). A fresh subagent needs time to gather context.
• Subagent: the task produces lots of output you don’t need to keep, it is self-contained and can return a summary, or you want to restrict its tools.
• Skill: reusable instructions or a workflow that should run in your main conversation. (The two combine: a subagent can preload skills, and a skill can run in a subagent.)

61.6 The bigger picture: running agents in parallel

As of Oct 6, 2026 · Official docs: Run agents in parallel · Agent view · Agent teams · Dynamic workflows

Subagents are one of five ways Claude Code can work on several tasks at once:

Approach	What it is	Status
Subagents	Helpers inside one session that return a summary	Standard
Agent view	claude agents opens one screen to start, watch, and reply to full Claude Code sessions running in the background on your computer	Research preview
Agent teams	A “lead” session splits the work among teammate sessions that message each other and share a task list	Experimental, off by default
Dynamic workflows	A script Claude writes that runs dozens or hundreds of subagents and cross-checks their findings. Try the built-in /deep-research; watch runs with /workflows	Paid plans (on Pro, turn on in /config)
Projects	One ongoing conversation at claude.ai/code or in the desktop app that starts parallel sessions, usually in the cloud (a thread can also run on your computer through Remote Control)	Public beta on Pro and Max

A few related tools: /subtask <task> starts a fork, a subagent that inherits your whole conversation instead of starting fresh; /fork copies the whole session into a new background session; and /background (or /bg) moves the current session to the background. When parallel agents edit files, git worktrees keep them from overwriting each other.

More agents, more usage

“Running several sessions or subagents at once multiplies token usage.” The agent view docs give an example: ten background agents use your quota roughly ten times as fast as one. Start small, and try a big workflow on a small slice first.

Deeper dive: nesting, limits, and resuming

• A subagent can start subagents of its own, by default up to three layers below the main conversation.
• By default, at most 20 subagents can run at the same time in a session.
• Claude can resume a finished subagent (for example, “continue that code review and now check the authorization logic”), and it picks up with its full history. The built-in Explore and Plan subagents can’t be resumed.
• You can block a subagent with a permission deny rule such as "Agent(Explore)".

61.7 Key takeaways

• A subagent does a side task in its own context window and returns a summary, keeping your main conversation clean.
• Built-ins (Explore, Plan, general-purpose) work automatically; custom subagents are Markdown files in .claude/agents/ or ~/.claude/agents/.
• The description tells Claude when to delegate; tools limits what the subagent can do.
• Every extra agent uses more of your usage; parallel options range from subagents to agent view, agent teams, and workflows.

Practice Questions

Easy

Question 1 · Short answer

What is a subagent, and what does it send back to the main conversation?

Suggested answer

A subagent is a separate AI assistant that Claude starts to handle one task. It works in its own context window, with its own instructions, tools, and permissions, and when it finishes it sends a summary of its results back to the main conversation (not everything it read).

Question 2 · Multiple choice

What is the main benefit of having a subagent search 60 files instead of doing it in the main conversation?

1. The subagent is never charged against your usage limits
2. The search results stay in the subagent’s context, so your main context stays clean
3. The subagent can see more of your conversation history
4. The subagent always uses a more powerful model

Suggested answer

b. Only the summary comes back, so the main context window doesn’t fill up with search results. (a) is false: subagents’ requests count toward the same usage limits. (c) is false: a normal subagent starts fresh, without your conversation history. (d) is false: unless its settings say otherwise, a subagent normally uses the main conversation’s model, and you can set a cheaper one such as Haiku.

Question 3 · Matching

Match each built-in subagent with its job.

Subagent		Job
1. Explore		A. Answers questions about Claude Code’s own features
2. Plan		B. Complex multi-step tasks that explore and change things
3. general-purpose		C. Fast, read-only search and analysis of a codebase
4. claude-code-guide		D. Gathers context in plan mode before Claude presents a plan

Suggested answer

1 → C, 2 → D, 3 → B, 4 → A.

Question 4 · True or false

A normal (non-fork) subagent can see the whole conversation you’ve had with Claude so far.

Suggested answer

False. A normal subagent starts with a fresh context: its own system prompt, the task message Claude writes for it, your CLAUDE.md files (except Explore and Plan), and a git status snapshot. Only a fork (for example one started with /subtask) inherits the full conversation.

Question 5 · Fill in the blank

Project subagents are saved in the folder ________, and personal subagents that work in all your projects are saved in ________.

Suggested answer

.claude/agents/ (inside the project) and ~/.claude/agents/ (in your home folder).

Question 6 · Multiple choice

Which two frontmatter fields are required in a subagent file?

1. name and model
2. tools and description
3. name and description
4. model and tools

Suggested answer

c. Only name and description are required. Without tools, the subagent gets all tools available to subagents; without model, Claude Code picks the model by its default rules (normally the main conversation’s model).

Medium

Question 7 · Read the file

Read this subagent file and answer: (a) What is it called? (b) When will Claude use it? (c) Can it edit files with the Edit tool? (d) Which model does it use?

---
name: safe-researcher
description: Research agent with restricted capabilities. Use for questions about how the code works.
tools: Read, Grep, Glob
model: haiku
---

Answer questions about the codebase. Quote file names and line numbers.

Suggested answer

1. safe-researcher. (b) When a request matches its description: questions about how the code works (or when you ask for it by name or @-mention it).
2. No. Its tools list only allows Read, Grep, and Glob, so Edit, Write, and Bash are not available. (d) Haiku, a fast, lower-cost model.

Question 8 · Write the prompt

Your test suite prints hundreds of lines. Write a prompt that keeps that output out of your main conversation.

Suggested answer

For example:

Use a subagent to run the test suite and report only the failing tests with their error messages

The subagent runs the tests in its own context and returns only the failures.

Question 9 · Write the file

Write a project subagent named test-runner that may only use Read, Grep, Glob, and Bash, runs on Haiku, and should be used after code changes to run the tests and summarize failures. Give the file’s path too.

Suggested answer

Path: .claude/agents/test-runner.md

---
name: test-runner
description: Runs the test suite and summarizes failures. Use proactively after code changes.
tools: Read, Grep, Glob, Bash
model: haiku
---

Run the project's tests. Report only the failing tests, each with its error
message and the file it is in. Do not change any files.

Any clear system prompt is fine; the key parts are the path, the required name and description, the tools list, and model: haiku.

Question 10 · Scenario

For each situation, choose main conversation, subagent, or skill:

1. You and Claude are going back and forth to fine-tune the wording of a web page.
2. You want Claude to search a large codebase for every use of an old function and report the list.
3. You type the same 12-step release checklist into chat every week.

Suggested answer

1. Main conversation: lots of back-and-forth that shares context.
2. Subagent: a self-contained search with a lot of output; only the list needs to come back.
3. Skill: reusable instructions you can run again and again in your main conversation.

Question 11 · Predict

During a session, Maria asks Claude to create her first personal subagent in ~/.claude/agents/ (the folder didn’t exist before). When she then asks Claude to use it, Claude can’t find it. Why, and what should she do?

Suggested answer

Claude Code watches the agents folders for changes, but only folders that existed when the session started. Because ~/.claude/agents/ was created during the session, the new file wasn’t picked up. She should restart Claude Code; after that, edits are detected automatically.

Question 12 · Multiple choice

A tutorial says to “run /agents and use the wizard to create a subagent”. What actually happens in current versions of Claude Code?

1. /agents opens agent view
2. /agents prints a reminder to ask Claude or edit the agent files directly
3. /agents deletes all custom subagents
4. /agents lists the plugins you have installed

Suggested answer

b. The interactive wizard existed in older versions (v2.1.197 and earlier). Now /agents just reminds you to ask Claude or edit .claude/agents/ or ~/.claude/agents/. Agent view (a) is opened with claude agents from your shell, a different command despite the similar name.

Question 13 · Short answer

How can you make sure that your code-reviewer subagent (and not some other one) handles a request? Give two ways.

Suggested answer

• @-mention it: type @ and pick it, e.g. @"code-reviewer (agent)" look at the auth changes (or @agent-code-reviewer). This guarantees that subagent runs for that task.
• Run the whole session as that agent: claude --agent code-reviewer.

Naming it in plain English (“Use the code-reviewer subagent to …”) usually works too, but then Claude still decides.

Hard

Question 14 · Find the bug

Sam wants a reviewer that can’t change files, but it edits files anyway. Find the bug.

---
name: careful-reviewer
description: Reviews code without changing it. Use after code changes.
disallowed-tools: Write, Edit
---

Review the recent changes and list problems by priority.

Suggested answer

The field name is wrong. It must be disallowedTools (camelCase), exactly as in the docs. Claude Code silently ignores fields it doesn’t recognize, so disallowed-tools does nothing; with no tools field either, the subagent inherits all tools, including Write and Edit. Fix: disallowedTools: Write, Edit (or an allowlist such as tools: Read, Grep, Glob).

Question 15 · Long answer

The docs’ code-reviewer subagent has tools: Read, Grep, Glob, Bash and is described as read-only. Is it truly unable to change files? Explain.

Suggested answer

Not completely. It has no Edit or Write tool, but it does have Bash, and shell commands can change files (for example echo "x" >> file.txt or rm file.txt). It needs Bash to run git diff. What protects you is the permission system: such commands still go through permission checks and your deny rules. For a reviewer that truly can’t run commands, remove Bash from tools (and, if needed, give it the diff in the task instead).

Question 16 · Scenario

You tell Claude in the chat, “From now on, ignore everything in the vendor/ folder.” Later, an Explore subagent’s report is full of findings from vendor/. Explain why, and give a better way to make the rule stick.

Suggested answer

A subagent starts with a fresh context: it doesn’t see your conversation history, so it never saw the chat instruction. (Explore also skips CLAUDE.md files.) Better options: ask Claude to include the rule in the task it gives the subagent (“search, but ignore vendor/”), and put lasting rules in CLAUDE.md, which normal subagents do load. For Explore specifically, restating the rule in the delegation is the reliable route.

Question 17 · Compare

Compare subagents and agent teams: how do they communicate, who coordinates the work, and which costs more? Which one can you use without changing any settings?

Suggested answer

• Subagents report their results back to the conversation that started them; the main agent manages all the work. They cost less because only summaries come back.
• Agent teams: a lead session coordinates teammates that message each other directly and share a task list. Each teammate is a separate Claude session, so teams use significantly more tokens.
• Subagents work out of the box. Agent teams are experimental and disabled by default (they must be turned on with a setting).

Question 18 · Scenario

A classmate on a Pro plan opens claude agents and dispatches ten tasks at once “to finish faster”. Then they hit their usage limit by lunchtime. Explain what happened and suggest a better approach.

Suggested answer

Each background session in agent view is a full Claude Code session that uses the subscription quota independently, so ten sessions use quota roughly ten times as fast as one. A better approach: dispatch only the tasks that are truly independent and important, start with one or two, use subagents (which return summaries) for side research, and check usage with /usage.

Question 19 · Scenario

Your team must check all 400 files of a codebase for the same security issue, and you want each finding double-checked. Which parallel approach from this page fits best, and what should you do before running it on everything?

Suggested answer

A dynamic workflow: Claude writes a script that runs many subagents (dozens to hundreds) and can have other agents cross-check the findings, which is too much for a handful of subagents in one conversation. Because a workflow can use many more tokens than a normal conversation, first run it on a small slice (for example one folder), watch the cost in /workflows, and then scale up. On a Pro plan, workflows must first be turned on in /config.

Challenge

Question 20 · Hands-on

In a practice Git repository, ask Claude to create a project code-reviewer subagent (read-only, using Sonnet). Review the file it writes, make a small change to a file, and then ask the subagent to review it with an @-mention. While it runs, look at /tasks. Report what you saw.

Suggested answer

A good answer includes:

• the file .claude/agents/code-reviewer.md with name, a clear description, a tools list without Edit and Write, and model: sonnet, plus a short explanation of each field;
• the prompt used, such as @"code-reviewer (agent)" review my last change;
• what appeared in the transcript (a row like code-reviewer(...)) and in /tasks;
• the summary the subagent returned, and a note on whether its feedback was useful and correct.

Question 21 · Hands-on

Ask the same research question twice: once normally (“Explain how this project is organized”) and once with “Use a subagent to …”. Run /context after each (in separate sessions, or after /clear) and compare how full your context window is. What do you notice?

Suggested answer

A good answer reports the /context numbers (or a description of them) for both runs and notices that, with a subagent, less of the main context window is used, because the files the subagent read stay in its own context and only its summary comes back. It may also note that the subagent version took a bit longer to start and that both runs used part of the plan’s usage.

Question 22 · Long answer

Design three custom subagents for a team web-app project (for example a test runner, a code reviewer, and a documentation writer). For each, write the frontmatter (name, description, tools, model), say where you would save it, and explain why you gave it those tools and that model.

Suggested answer

A good answer has three focused subagents, each saved in .claude/agents/ (so the team shares them through git), with descriptions that clearly say when to use each one. For example:

• test-runner: tools: Read, Grep, Glob, Bash, model: haiku. It needs Bash to run tests, but a cheap, fast model is enough to summarize failures.
• code-reviewer: tools: Read, Grep, Glob, Bash (Bash for git diff), model: sonnet or inherit. No Edit/Write, because a reviewer should report, not change code.
• docs-writer: tools: Read, Grep, Glob, Edit, Write, model: sonnet. It must create and edit Markdown files, but it doesn’t need Bash.

The explanation should follow “give each subagent only the tools it needs” and match the model to how hard the job is.