Claude Code Sub-Agents

Your main session is not a dumping ground

I run 8 agents daily. That sounds like a lot until you realize the alternative: asking Claude Code to review auth changes, watching it read 15 files and write a 200-line audit, and noticing your context window is now half gone.

You needed the 5-line summary. Not the journey.

Sub-agents fix this. They're separate Claude Code instances that handle focused tasks in their own context windows. The security review happens over there. The test generation happens over there. Your main session stays clean and can keep steering.

Why this actually matters

Your context stays focused. The main session makes decisions. Agents do the deep dives. You get the result, not the noise.

Parallel execution. Code review, security scan, and test generation running at the same time, not queued up. Three expert reviews in the time of one.

Specialization that holds. Each agent carries instructions tuned for exactly one job. A code-reviewer knows your team's standards. A tdd-guide enforces test-first. Better instructions, better output, every time.

Built-in agents

Claude Code ships with a few built-in subagents and uses them on its own when a task fits:

The code-reviewer, security-reviewer and tdd-guide agents in the demo above are custom agents. You write those yourself, as shown below. Once they exist, you can be explicit: "Run the code-reviewer on the files I just changed."

The tool that launches an agent is called Agent. It was called Task before version 2.1.63, and old Task(...) references still work.

Building your own agents

Custom agents are markdown files with YAML frontmatter. Put them in .claude/agents/ for one project, or in ~/.claude/agents/ to use them in every project. Only name and description are required, and the description matters most: Claude reads it to decide when to hand a task to the agent. Without a name, Claude Code treats the file as plain documentation and never loads it as an agent.

Here's one I use constantly:

---
name: pr-writer
description: Writes pull request descriptions from the current branch's git diff. Use when asked to describe a branch or draft a PR.
tools: Read, Bash
---

# PR Description Writer

## Role
You generate pull request descriptions from git diffs.

## Behavior
1. Read the full diff with `git diff main...HEAD`
2. Analyze each commit for its purpose
3. Group changes by category (feature, fix, refactor, test)
4. Write a structured PR description:
   - Summary (2-3 sentences)
   - Changes (bulleted by category)
   - Testing notes
   - Breaking changes (if any)

## Constraints
- Never include file paths with absolute user directories
- Keep the summary under 100 words
- Use conventional commit categories

Save it, then invoke it: "Use the PR description writer for this branch." Claude Code reads the file, follows the instructions, delivers the output. Simple as that.

When to delegate vs just do it

Not everything needs an agent. Here's the honest breakdown.

Delegate when:

• The task requires reading a ton of files (research, audits, anything that looks like exploration)
• You need the result but don't care about the intermediate steps
• Multiple tasks can run in parallel
• It's a review, scan, or verification task

Just do it directly when:

• It's a quick edit (a few lines, maybe two files)
• You need to steer every step in real time
• It's a one-off question about the codebase

The rough rule: if it takes more than a minute and you don't need to babysit it, delegate.

Parallel execution is the real unlock

For complex tasks, launch multiple agents at once:

Launch 3 agents in parallel:
1. Agent 1: Security review of the auth module
2. Agent 2: Performance audit of the database queries
3. Agent 3: Test coverage analysis for the API routes

Each works independently, uses its own context, returns a focused report. This is where sub-agents go from "nice to have" to "I can't work without this."

Since v2.1.302 the desktop app and VS Code always run the main conversation's subagents in the background, as the terminal already did, so you can keep talking while they work. An Agent call that a subagent makes itself runs in the foreground by default in claude -p, the Agent SDK, the desktop app and VS Code.

When you need a subagent's result before anything else happens, ask for it: "run the reviewer subagent and wait for its report". claude -p and the Agent SDK honor that out of the box. In the terminal, VS Code and the desktop app, Claude can only wait once fork mode is off (see below). Background subagents also get a smaller built-in tool set than foreground ones, and their permission prompts show up in your main session. A grant you give there for the rest of the session covers your main conversation too, so read the prompt before you click.

Forks: agents that keep your conversation

A normal subagent starts with an empty context and only the brief Claude writes for it. A fork (subagent_type: "fork") inherits the conversation so far instead, which suits a side task that needs everything you've already discussed. Claude could spawn forks on its own in the terminal before; since v2.1.302 it can in claude -p, the Agent SDK, the desktop app and VS Code too. Fork mode is on by default, and while it's on, Claude can't wait for a subagent in interactive sessions. Set CLAUDE_CODE_FORK_SUBAGENT=0 (in your shell, or under env in settings.json) to turn forks off and let Claude wait again, then restart claude or open a new VS Code conversation.

Things I learned the hard way

One task per agent. An agent that does code review AND writes tests is two agents crammed into one file. Split them. You'll thank yourself later.

Be specific. "Review this file for security issues" works way better than "look at the code and tell me if anything's wrong." Bounded tasks, better results.

Trust but verify. Agents are good, not perfect. Skim the output before acting on it. False positives happen. Edge cases get missed.

Start with the built-ins. Let Explore and General-purpose handle delegation for a week before writing custom agents. You'll learn what you actually need, not what you think you need.

Keep agent files short. 20-40 lines is the sweet spot. If your agent file hits 200 lines, you've encoded multiple agents into one. Break it up.