Where do you define a custom subagent?

Subagents are markdown files with YAML frontmatter. Project ones live in .claude/agents/ inside the repo; personal ones live in ~/.claude/agents/. The frontmatter sets name, description, allowed tools and model; the body is the system prompt. The /agents command manages them interactively.

Can subagents run in parallel?

Yes. The main session can fan out several subagents at once when the sub-tasks do not depend on each other, so independent work finishes faster. Exact concurrency limits and orchestration commands change between releases, so check the Claude Code docs.

Explainer

Claude Code subagents explained: isolated context, fan-out, worktrees

Priya Nair June 29, 2026 · 8 min read

A Claude Code subagent is a focused helper that the main session spawns to handle one task in its own fresh, isolated context window, then reports back a single result. Instead of doing everything inline - and slowly filling the main conversation with the noise of a long search or a multi-file refactor - the main agent delegates. It hands a sub-task to a worker that starts clean, does the job, and returns just the answer. The main thread stays focused; the messy middle happens somewhere else. Once that clicks, "why did my context fill up so fast" and "how do I run three things at once" stop being mysteries.

The main session fans out to several subagents, each with its own fresh context window; each does one job and returns a single result the main thread can use.

What a subagent is

The core idea behind Claude Code subagents is delegation with a clean slate. When the main agent hits a chunk of work that is self-contained - find every call site of a function, write a test file, audit a diff for security issues - it can spin up a subagent to do it. That subagent does not inherit your whole conversation. It starts with a fresh context window, gets a narrow brief, runs to completion, and hands back a single summarized result. The thousands of tokens it burned grepping through files never land in your main thread - only the conclusion does.

That is the part worth internalizing: a subagent runs in its own isolated context, so its work does not pollute the main conversation. Context is the scarcest resource in a long coding session. Every file you read, every command output, every dead end stays in the window and slowly crowds out the room the agent has to reason. Subagents are how you keep the main thread focused on the plan while the grunt work happens off to the side. The main agent gets the answer; it does not have to carry the search that produced it.

Defining and managing subagents

A custom subagent is just a markdown file with YAML frontmatter. Project subagents live in .claude/agents/ inside the repo, so they travel with the project and everyone on the team gets them. Personal ones live in ~/.claude/agents/ and follow you across every project on your machine. On a name collision, the project version wins. The frontmatter declares who the agent is and what it can touch; the body below it is the system prompt that steers its behavior:

---
name: code-reviewer
description: Reviews diffs for bugs and style issues. Use after edits.
tools: Read, Grep, Glob, Bash
model: sonnet
---

You are a focused code reviewer. Read the diff, flag real
correctness bugs first, then style. Be concise.

The description field does more than label the file - it is the routing signal. The main agent reads descriptions to decide which subagent fits a task, so write it as a "use this when" cue, not a title. tools is a comma-separated allowlist that scopes what the subagent can do (a read-only researcher gets Read, Grep, Glob and nothing that writes), and model picks which model it runs on, defaulting to the session model if you omit it.

You do not have to hand-edit these. The /agents command opens an interactive manager: recent versions show a library of every available subagent - built-in, personal, project, and plugin - plus a view of subagents currently running that you can inspect or stop. It walks you through creating, editing, and deleting them. Exact tab names and capabilities shift between releases, so treat Anthropic's subagents documentation as the source of truth rather than memorizing a layout.

The built-in subagents

You do not have to define anything to start using subagents. Claude Code ships with built-in ones the main agent reaches for automatically, and they map cleanly to three jobs:

A general-purpose worker for complex, multi-step tasks that need both exploration and edits - the catch-all the main agent delegates to when a sub-task involves real reasoning and several dependent steps.
A read-only explorer optimized for fast code search. It sweeps the codebase, reads excerpts, and returns where things live without burning your main context on the file dumps - ideal for "find every place that does X."
A planning worker that researches the codebase first and comes back with an implementation strategy instead of immediately changing files.

The exact names and roster of built-in subagents evolve, so don't hard-code them into your mental model - check the docs for the current set. The pattern, though, is stable: read-only search and planning agents exist precisely so the heavy lifting happens in a throwaway context and only the distilled answer comes back to you.

Fan-out: parallel subagents

Isolated context is the quiet win; parallel fan-out is the loud one. Because each subagent runs on its own, the main session can launch several at once. When you have sub-tasks that don't depend on each other - fix the same lint error across six files, update a pattern in four unrelated components, research three libraries side by side - the main agent can dispatch a subagent per task and let them run simultaneously. Three workers going at once generally finish well before one worker doing them in sequence.

The signal for when fan-out helps is dependency, not size: if sub-task B doesn't need sub-task A's output, they can run in parallel. You can even give each one different permissions - a research subagent stays read-only while an implementation subagent gets full edit access. Recent versions add a higher-level way to kick off a batch of parallel agents from one natural-language instruction, with concurrency capped under the hood. The exact orchestration command and limits change between releases, so confirm them in the subagents docs. This is the in-the-box cousin of the worktree pattern we cover in running parallel agents with git worktrees, and the broader case for it lives in run multiple AI agents at once.

Isolated context (and worktree isolation)

Context isolation keeps the conversation clean. The natural next question is filesystem isolation: if three subagents are editing files in parallel, what stops them from clobbering each other? Inside one shared checkout, nothing does - and that's the same collision problem you hit running multiple agents in one folder by hand.

Recent versions answer it the same way the manual workflow does. You can set a subagent to run in its own git worktree, so its file edits land in a separate checkout - its own branch, its own working tree - instead of your main one. The frontmatter switch looks like isolation: worktree, and a worktree that finishes without changes is typically cleaned up for you. Each isolated subagent then has its own context window and its own files, which is what makes "three subagents editing in parallel" safe rather than a recipe for silent corruption. Flag names and cleanup rules move between releases, so the worktrees docs are the place to confirm the current behavior. We walk through what a worktree actually is, end to end, in git worktrees + Claude Code.

Worth noting alongside the definition format: shared, cross-tool agent instructions increasingly live in an AGENTS.md file - an open standard a growing list of coding tools read - while Claude Code keeps its richer CLAUDE.md for Claude-specific config and reads AGENTS.md as a fallback. If you're sorting out which project rules go where, we compare them in CLAUDE.md vs AGENTS.md. Subagent definitions themselves still live in .claude/agents/; AGENTS.md is for the shared behavioral rules every agent in the repo should follow.

One thing to plan for: many notifications

Here is the consequence nobody mentions in the tutorials. Subagents are a force multiplier - one prompt can blossom into a main agent plus five workers, each running in its own context, some in their own worktrees. That is wonderful for throughput. It is also a lot of things finishing at slightly different times. Five subagents wrapping up is five "done" moments. Add the main agent pausing for a permission prompt, a subagent asking a clarifying question, another hitting an edit it wants approved, and you have a steady drip of events - each one a moment where a few seconds of your attention has real value, and each one easy to miss if you've looked away.

Under the hood, Claude Code surfaces these moments through its lifecycle hooks - roughly a stop event when an agent finishes, a notification event when one wants your attention, and a pre-tool event before it runs something. We break those down in Claude Code hooks explained. The problem isn't the events; it's the volume. A single terminal can only show you one thing at a time, and a subagent that quietly finished two minutes ago looks exactly like one still grinding. The more you fan out, the worse the mismatch between how much is happening and how much you can actually see. That's the same wall we describe in stop babysitting your AI coding agent, just multiplied by the number of subagents in flight.

Frequently asked questions

What is a Claude Code subagent in one sentence?: A Claude Code subagent is a focused helper that the main session spawns to handle one task in its own fresh, isolated context window, then reports a single result back without cluttering the main conversation.
Where do you define a custom subagent?: Subagents are markdown files with YAML frontmatter. Project ones live in .claude/agents/ inside the repo; personal ones live in ~/.claude/agents/. The frontmatter sets name, description, allowed tools and model; the body is the system prompt. The /agents command manages them interactively.
Can subagents run in parallel?: Yes. The main session can fan out several subagents at once when the sub-tasks do not depend on each other, so independent work finishes faster. Exact concurrency limits and orchestration commands change between releases, so check the Claude Code docs.
Do subagents keep their file edits isolated?: They can. Recent versions support running a subagent in its own git worktree, so its file edits land in a separate checkout instead of your working tree. See the Claude Code docs for the current flag.

Where Backgrind fits

Backgrind doesn't run your subagents - Claude Code does that natively. Backgrind is the surface that makes a fan-out survivable: an always-on-top overlay running your real CLI, with a tab per session, kept alive by a background daemon so closing the window never kills the work. When a subagent finishes, the main agent pauses for a decision, or one of them asks a question, that session's tab pings with an accent ring and a chime while the rest keep running silently. You don't scan a wall of terminals hunting for the one that needs you; the one that needs you raises its hand. It's a GUI for your agents, not another agent. See the loop in the live demo.