Claude Code Sub-Agents & Parallel Work

Sub-agent architecture

A sub-agent gets its own fresh context window, completely separate from the main conversation. When it finishes, it returns only a summary. That isolation is the whole point: sub-agent work never bloats your main context, and because they're independent, several can run at once. Once you're comfortable with single sub-agents, the next step is coordinating several specialists together — see the chapter on building Agent Teams.

Automatic delegation

Claude delegates on its own for large file operations, parallel research, and tasks that would otherwise exhaust the main context.

Explicit invocation

You can also spawn a sub-agent by name or instruction whenever you want a clean, dedicated context for a slice of work.

Custom sub-agent configuration

Define a reusable agent as a markdown file at ~/.claude/agents/code-reviewer.md (personal) or .claude/agents/code-reviewer.md (shared with the team). YAML frontmatter sets its capabilities; the body is its system prompt.

markdown

---
name: code-reviewer
description: "Specialized code review agent. Use for reviewing PRs, checking security, and evaluating code quality."
model: claude-opus-4-5
tools:
  - read_file
  - bash
  - web_search
mcp-servers:
  - github
  - sentry
permission-mode: plan
preload-skills:
  - review-pr
  - security-audit
persistent-memory: true
---

You are a specialized code review agent. You focus exclusively on code quality,
security vulnerabilities, performance issues, and adherence to team conventions.

When reviewing code:
1. Check for security vulnerabilities first (injection, auth issues, data exposure)
2. Evaluate correctness and edge case handling
3. Assess performance implications
4. Check adherence to our coding standards from CLAUDE.md
5. Provide specific, actionable feedback with line references

Never suggest stylistic changes without a functional justification.

Invoking sub-agents

There are three ways work reaches a sub-agent: Claude decides, you name one, or you push it to the background.

Automatic delegation (Claude decides):

text

> Research the best approaches for implementing distributed locking in Redis,
  then implement the best option in our caching module.

Claude may spawn a research sub-agent for the first part, then implement in the main session.

Explicit invocation:

text

> @code-reviewer: Review the changes in the auth module on the current branch
> Spawn a sub-agent to investigate the memory leak while I continue working on the feature

Background vs foreground:

text

> [Run in background] Analyze all TypeScript files for potential type safety issues and report back

Background sub-agents run without blocking your session.

Agent View — the parallel work dashboard

Launch the dashboard to dispatch and monitor multiple sessions at once.

bash

claude agents

From Agent View you can:

See all running and recent sessions
Monitor session state and progress
Dispatch new sessions to specific directories
Read session summaries and attach to running sessions
Filter by status, model, or directory

Dispatch three agents to three directories — zero context collision:

text

# In agent view interface
[New Agent] → directory: ./packages/api    → "Fix all ESLint errors"
[New Agent] → directory: ./packages/worker → "Write unit tests for the job handlers"
[New Agent] → directory: ./packages/shared → "Update TypeScript to strict mode"

Common parallel patterns

Pattern 1 — Parallel research

Spawn several agents to investigate different angles of one question, then synthesize their findings.

Pattern 2 — Fan out across files

One agent per file applying the same transformation, each reporting files that need special attention.

Pattern 3 — Chain specialized agents

Sequential hand-off: research → architect → implement → review, each a specialist.

text

# Pattern 1 — Parallel research
> Spawn 3 sub-agents to research: (1) best practices for database connection pooling,
  (2) how our competitors handle this in open-source code,
  (3) what our current code does. Synthesize their findings when done.

# Pattern 2 — Fan out across files
> For each file in src/api/routes/, spawn a sub-agent that adds comprehensive error handling.
  Each agent works on one file. Report any files that need special attention.

# Pattern 3 — Chain specialized agents
> First, use the research agent to understand the legacy system.
  Then use the architect agent to design the migration plan.
  Then use the implementation agent to execute it.
  Then use the code-reviewer agent to review the result.

Worktrees for true branch isolation

When parallel agents must work on different branches, git worktrees give each one its own checkout on disk. No stashing, no branch thrashing — just independent working directories you can point a Claude session at.

bash

# Create an isolated worktree per task
git worktree add .worktrees/auth-refactor feature/auth-refactor
git worktree add .worktrees/perf-fixes feature/performance

# Copy needed gitignored files (e.g., .env)
cp .env .worktrees/auth-refactor/
cp .env .worktrees/perf-fixes/

# Launch Claude in each
(cd .worktrees/auth-refactor && claude -p "Complete the auth refactor")
(cd .worktrees/perf-fixes && claude -p "Fix the N+1 queries in the API")

# Clean up when done
git worktree remove .worktrees/auth-refactor
git worktree remove .worktrees/perf-fixes

Practice project

Design and execute a parallel development sprint. Pick three features that can be built independently, create a git worktree for each, launch three Claude agents simultaneously, and merge all three when done. Measure the total wall-clock time against your estimate for doing the same work sequentially. For more hands-on chapters like this, browse the full Claude Code tutorial series.

Quick summary

Sub-agents get isolated context windows and return only a summary — no context bloat
Define reusable agents as markdown files with YAML frontmatter for tools, model, and skills
Invoke automatically, by name, or in the background; manage them all from claude agents
Use git worktrees so parallel agents on different branches never collide

Sub-Agents FAQ

What is a sub-agent in Claude Code?

A sub-agent gets its own fresh context window, completely separate from the main conversation. When it finishes, it returns only a summary, so its work never bloats your main context.

How is a sub-agent's context isolated from the main session?

Each sub-agent runs in a fresh, isolated context window that is separate from the main conversation. Because they are independent, sub-agent work never bloats your main context and several can run at once.

How do I run Claude Code agents in parallel?

Launch Agent View with the command claude agents to dispatch and monitor multiple sessions at once. You can point each agent at a different directory so three agents can work on three directories with zero context collision.

How do I define a custom sub-agent?

Define a reusable agent as a markdown file at ~/.claude/agents/code-reviewer.md for personal use or .claude/agents/code-reviewer.md to share with the team. YAML frontmatter sets its capabilities, and the body is its system prompt.

When does Claude delegate to a sub-agent automatically?

Claude delegates on its own for large file operations, parallel research, and tasks that would otherwise exhaust the main context. You can also spawn a sub-agent explicitly by name or instruction whenever you want a clean, dedicated context.