skip to content

Subagents & Parallel Work

Subagents run side tasks in their own context window and return a summary, while worktrees and agent teams run whole sessions in parallel. Asked because context is the scarce resource in agentic work.

part ofClaude Coderead it →
on this pageshow

explore

questions

17

What is a Claude Code subagent definition file, and how do its frontmatter and its Markdown body each shape the subagent?

level: juniorimportance: must knowfreq 30%

answer

  1. Markdown plus YAML frontmatter
  2. two required fields
  3. what the body becomes
  4. unknown fields fail silently
  5. /agents stopped being a wizard

basics

~20 s

A subagent is a Markdown file in .claude/agents/ or ~/.claude/agents/: YAML frontmatter configures it (name and description required; tools, model, permissionMode and others optional) and the body becomes its system prompt in place of Claude Code's own.

solid answer

~40 s

A subagent definition is a Markdown file with YAML frontmatter, kept in `.claude/agents/` for one project or `~/.claude/agents/` for all of yours. Only `name` and `description` are required: `name` is the identity (the filename does not matter) and `description` is what Claude reads to decide when to delegate. Optional fields narrow it: `tools` and `disallowedTools`, `model`, `permissionMode`, `skills`, `mcpServers`, `memory`, `isolation`, `hooks`, `maxTurns`. The body is the subagent's system prompt: it gets that plus environment details, not Claude Code's own system prompt, though custom subagents still load your `CLAUDE.md` files. A misspelled field is ignored without an error, and a file missing `name` or `description` is skipped silently. Since v2.1.198 `/agents` only prints where these files live; you ask Claude to write one or edit it yourself.

code

markdown · 15 lines
markdown
---
name: security-reviewer
description: Reviews changed code for injection, authorization and secret-handling flaws. Use after edits to auth or input handling.
tools: Read, Grep, Glob
model: inherit
---

You are a security reviewer. You never modify files.

When invoked:
1. Read the files named in your task.
2. Look for injection, missing authorization checks and leaked secrets.
3. Report each finding as: file:line, severity, why it is exploitable, a suggested fix.

If you find nothing, say so in one line.

go deeper

for a junior

Recall the two directories, the two required fields, and that the body becomes the subagent's system prompt. Know Explore exists without any file.

for a middle

Explain why the body must stand alone (no Claude Code system prompt behind it), which optional fields exist, and the silent-skip cases that make a file never load.

for a senior

Show how you debug a subagent that never runs: debug log, validate command, restart cases, then the description. Separate what frontmatter enforces from what the prompt merely asks.

for a principal

Argue where a team's constraints belong: tool limits in frontmatter that Claude Code enforces, conventions in the prompt, and shared definitions committed under .claude/agents/ with review like any code.

## What a subagent definition is A **subagent** in Claude Code is a separate assistant with its own context window, its own system prompt and its own tool access, which Claude can hand a task to. A **definition file** is how you describe one you want to reuse. It is an ordinary Markdown file with **YAML frontmatter** between two `---` lines at the very top, followed by Markdown prose. Where the file lives decides who can use it: - `.claude/agents/` inside a repository: a **project** subagent, meant to be committed so the team shares it. - `~/.claude/agents/`: a **user** subagent, available in every project on your machine. - Both directories are scanned recursively, so `agents/review/security.md` is fine; the subfolder does not change the subagent's identity. Other sources exist (an organisation's managed settings, the `--agents` launch flag, plugins), and they matter when two definitions share a name, but the file format is the same everywhere. ## The frontmatter: configuration Only two fields are **required**; everything else narrows or extends the defaults. | Field | Required | What it controls | |---|---|---| | `name` | yes | The identifier Claude and hooks see. No `:`, which is reserved for plugin-scoped names. The filename does not have to match. | | `description` | yes | When Claude should delegate. It is always in Claude's context, so keep it short and specific. | | `tools` / `disallowedTools` | no | Allowlist and denylist of tools. Omit both and the subagent inherits every tool available to subagents. | | `model` | no | An alias, a full model ID, or `inherit`. | | `permissionMode` | no | The permission mode it runs in, within limits set by the main session's mode. | | `skills`, `mcpServers`, `memory`, `hooks`, `isolation`, `maxTurns`, `effort` | no | Preloaded skills, scoped MCP servers, persistent memory, lifecycle hooks, a worktree, a turn cap, an effort level. | Multi-word fields are **camelCase** (`disallowedTools`, `permissionMode`, `maxTurns`) and must match exactly. Claude Code **ignores a field it does not recognise without reporting anything**, so `disallowed-tools:` or `tool:` silently does nothing and the subagent keeps its inherited tools. ## The body: the whole system prompt Everything after the closing `---` becomes the subagent's **system prompt**. This is the part people underestimate: the subagent receives that prompt plus basic environment details such as the working directory, **not** Claude Code's own system prompt. So the body has to say what the subagent is for, how to work, and what shape its final report should take. A custom subagent does still load your `CLAUDE.md` hierarchy and a git status snapshot as part of its starting context, unless its frontmatter sets `omitClaudeMd: true`. It does not see the main conversation's history; it starts from the task message Claude writes when delegating. ## Files Claude Code skips without telling you A definition that never gets used is usually one that never loaded. Claude Code skips a file, reporting nothing in the session, when: 1. it has no `name` (treated as documentation kept beside your agents); 2. the opening `---` is not on the first line; 3. the `name` starts with `-` or contains `:`; 4. it has a `name` but no `description`; 5. the YAML does not parse. Run with `--debug` to see the reasons in the debug log, or run `claude plugin validate .claude/agents` to find frontmatter that does not parse. Two files in one directory tree with the same `name` load only one of them, chosen by filesystem order; `/doctor` reports such duplicates. ## Creating and editing since v2.1.198 Before v2.1.198, `/agents` opened an interactive wizard for creating, editing and deleting subagents. Since v2.1.198 it only **prints a reminder** of the two directories and suggests asking Claude. The working routes now are: 1. ask Claude to write the file ("create a read-only security reviewer in .claude/agents/"), then review the frontmatter it wrote; 2. write or edit the file yourself. Claude Code **watches** both directories, so an edit is picked up within seconds and the next delegation uses it. A restart is still needed when the `agents` directory did not exist when the session started. ## What you get without writing a file Claude Code ships **built-in subagents**: **Explore**, a fast read-only agent for searching a codebase; **Plan**, a read-only research agent used during plan mode; and **general-purpose**, which has every tool available to subagents. Explore and Plan skip your `CLAUDE.md` files and the git status snapshot to stay fast. A project or user file named `Explore` overrides the built-in one, which is how you change its model. ## Why the anatomy matters The two halves do different jobs. The **frontmatter is enforced by Claude Code**: a tool missing from `tools` is not available, unless another field such as `memory` adds it. The **body is guidance to the model**: "never edit files" in the prompt shapes behaviour, but only the tool list makes it impossible. Safe delegation comes from putting each constraint in the half that can actually hold it.

  • You saved a new subagent file but Claude never delegates to it. What do you check first?
    Whether it loaded at all: `name` and `description` both present, the opening `---` on line one, YAML that parses, and no `:` in the name; `--debug` shows skip reasons. If the `agents` directory was created after the session started, restart. If it loaded, the `description` is probably too vague to match the task.
  • Does a custom subagent see the project's CLAUDE.md?
    Yes. A custom subagent loads every level of the `CLAUDE.md` hierarchy the main conversation loads, unless its frontmatter sets `omitClaudeMd: true`, which keeps only managed policy files. The built-in Explore and Plan agents skip `CLAUDE.md` and the git status snapshot regardless.

  • The filename is the subagent's name, so renaming the file renames the agent.
  • The body is appended to Claude Code's default system prompt.
  • A misspelled frontmatter field makes Claude Code reject the file with an error.
  • Run /agents to open the wizard and create a new subagent.
  • Only name is required; description is optional and defaults to the body.

Assumes Claude Code 2.1.286; since 2.1.198 /agents only prints the definition-file locations instead of opening a wizard.

open as a page

How do you run two Claude Code sessions on one repository at once without colliding edits, and what does `claude --worktree` set up?

level: juniorimportance: must knowfreq 26%

basics

~20 s

Start each session with claude --worktree <name> (or -w). Claude Code creates a git worktree at .claude/worktrees/<name> on a new branch worktree-<name> and starts there, so each session edits its own files while sharing the repository history.

open as a page

In a Claude Code subagent definition, how do the `tools` and `disallowedTools` fields differ, and how would you scope a read-only security reviewer?

level: middleimportance: must knowfreq 22%

basics

~20 s

tools is an allowlist and disallowedTools a denylist applied first; omit both and the subagent inherits every subagent tool. A read-only reviewer lists Read, Grep and Glob, because keeping Bash still lets it change files.

open as a page

In Claude Code, what does a non-fork subagent start with, and what reaches your main conversation when it finishes?

level: middleimportance: must knowfreq 30%

basics

~20 s

A non-fork subagent starts with its own system prompt, the task message Claude writes for it, your CLAUDE.md files and a git status snapshot, not your conversation history. Only its final message comes back to the main conversation.

open as a page

In Claude Code, how do automatic delegation, an @-mention and `claude --agent` differ in deciding which subagent does the work?

level: juniorimportance: should knowfreq 22%

basics

~20 s

Automatic delegation lets Claude pick a subagent by matching your request to its description; an @-mention guarantees that subagent runs for one task; claude --agent <name> makes the whole session run as that agent, with its prompt, tools and model.

open as a page

When Claude Code finds subagent definitions with the same name in managed settings, `--agents`, project, user and plugin scopes, which one runs?

level: middleimportance: should knowfreq 12%

basics

~10 s

The highest-priority source wins: managed settings, then the --agents flag, then the project's .claude/agents/, then ~/.claude/agents/, then plugins. Among nested project directories, the definition closest to the working directory wins.

open as a page

In an interactive Claude Code session, why do spawned subagents run in the background, and what changes for a background subagent?

level: middleimportance: should knowfreq 12%

basics

~20 s

Fork mode, on by default in interactive sessions since v2.1.232, backgrounds every spawned subagent. A background subagent gets a smaller built-in tool set, raises permission prompts in your main session, and reports through a later completion notification.

open as a page

Why does a fresh `claude --worktree` session lack your .env file, your node_modules and your unpushed commits, and what fixes each?

level: middleimportance: should knowfreq 12%

basics

~20 s

A Claude Code worktree is a fresh checkout of tracked files from the remote default branch. List gitignored files in .worktreeinclude, symlink or reinstall dependencies with worktree.symlinkDirectories, and set worktree.baseRef to head to keep unpushed commits.

open as a page

A Claude Code migration-writer subagent sets `permissionMode: acceptEdits`, yet it runs in auto mode in your session — when does Claude Code honour that field?

level: seniorimportance: should knowfreq 7%

basics

~20 s

Only when the main session is in default (Manual), dontAsk or plan mode. In auto, acceptEdits or bypassPermissions the subagent runs in the parent's mode, and since 2.1.267 a declared bypassPermissions is never honoured unless the parent already uses it.

open as a page

In Claude Code, when should you hand a side task to a forked subagent with `/subtask` rather than a fresh subagent?

level: seniorimportance: should knowfreq 11%

basics

~20 s

Use a fork (/subtask, v2.1.212+) when the side task needs what the conversation already knows: it inherits history, prompt, tools and model and reuses the parent's cache. Use a fresh subagent for other tools, another model or an unbiased view.

open as a page

After a team starts delegating every search to Claude Code subagents, plan usage climbs — where does a subagent's token cost come from, and how do you cut it?

level: seniorimportance: should knowfreq 9%

basics

~20 s

Each subagent sends its own requests against the same usage limits, on a cold cache, and its report then stays in the parent's context. Cut cost with cheaper subagent models, terse reports, forks for context-heavy work and fewer delegations.

open as a page

When do you use Claude Code agent teams instead of subagents, how do you turn them on, and how do you stop teammates overwriting each other's files?

level: seniorimportance: should knowfreq 11%

basics

~20 s

Agent teams are experimental and enabled with CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1. Use them when workers must talk to each other and share a task list, not just report back; teammates get no worktrees, so give each one its own files.

open as a page

In a Claude Code subagent definition, what do the `skills`, `mcpServers` and `memory` fields load, and what does each one not restrict?

level: middleimportance: nice to knowfreq 5%

basics

~20 s

skills injects listed skills' full content at startup, mcpServers gives the subagent servers of its own, and memory adds a persistent directory. None limits access: unlisted skills stay invocable, and memory switches on Read, Write and Edit.

open as a page

What does Claude Code's bundled `/batch` skill do with a codebase-wide change, and why might its workers miss your unpushed commits?

level: middleimportance: nice to knowfreq 5%

basics

~20 s

Claude Code's /batch splits a large change into 5 to 30 independent units and, after you approve the plan, runs one background subagent per unit in its own worktree, branched from the remote default branch unless worktree.baseRef is head.

open as a page

In Claude Code, what is the difference between `/background` and `/fork`, and where does each resulting background session edit files?

level: middleimportance: nice to knowfreq 7%

basics

~20 s

In Claude Code 2.1.286, /background (alias /bg) moves this conversation into a background session that keeps editing in place; /fork copies it into a new background session told to use its own worktree, while you keep working.

open as a page

A Claude Code subagent sets `model: haiku` while `CLAUDE_CODE_SUBAGENT_MODEL=sonnet` is exported — which model runs, and how do you force one model everywhere?

level: seniorimportance: nice to knowfreq 6%

basics

~10 s

Haiku runs: since 2.1.251 the order is the per-invocation model, then the frontmatter model, then CLAUDE_CODE_SUBAGENT_MODEL, then the main model. To force one model, also set CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1 (2.1.257+).

open as a page

A Claude Code fan-out fails with `Concurrent subagent limit reached` — what limits subagent concurrency and nesting, and how do you change them?

level: seniorimportance: nice to knowfreq 6%

basics

~10 s

Claude Code refuses a new Agent spawn while 20 subagents are running (CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS) and lets subagents nest three layers below the main conversation (CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH). Both take a positive whole number; neither can be removed.

open as a page