Subagents and Parallel Workstreams

Claude Code's subagent capability lets you split work across multiple AI instances running simultaneously, each with its own context window. When it works well, it's one of the highest-leverage techniques in this toolkit.

The Context Window Problem This Solves

A single Claude Code session accumulates context over time. Every file read, every exchange, every output — it all piles up. Large tasks exhaust context before they're done.

Subagents solve this by splitting work at the start, before context accumulates. Instead of one instance that knows everything but runs out of room:

Plain text

Parent agent
├── Subagent 1 — focused on authentication module
├── Subagent 2 — focused on payment processing
└── Subagent 3 — focused on notification service

Each subagent gets a lean context window with only what it needs. Three smaller, focused tasks instead of one large, unfocused one. Each finishes faster, makes fewer mistakes, and doesn't interfere with the others.

How Claude Code Spawns Subagents

In Claude Code, you can spawn a subagent using the Task tool:

Plain text

Parent: "I need you to work on three separate modules.
Use the Task tool to spawn subagents for each one..."

Or you can describe the parallel work in your prompt and let the orchestrator decide how to split it:

Plain text

> Refactor the authentication, payment, and notification modules to use
  the new shared error handling pattern from src/lib/result.ts.
  These modules are independent — work on them in parallel.

When Claude Code has the Task tool available, it can launch subagents automatically for independent work.

The Sharded Context Window Pattern

The key word is independent. Subagents work best when the work streams don't need to communicate mid-task.

Good candidates for parallelization:

Tests for independent modules
Documentation for multiple separate functions
Refactoring independent files to a new pattern
Generating boilerplate in multiple directories
Running a consistent change across different parts of the codebase

Bad candidates:

Features where one module depends on another's output
Refactors where shared types need to be agreed on first
Anything where Agent 1's decisions need to inform Agent 2's behavior

If the subagents would need to talk to each other to do it right, don't parallelize it.

Which Personas Produce Quality Output

When spawning subagents for specialized work, the instruction set you give each agent matters more than the model. Some patterns reliably produce good output:

The Implementer + Critic Pattern

Don't ask one agent to implement and evaluate. Split them:

Plain text

Subagent 1 (Implementer):
"Implement the Google OAuth integration in src/auth/oauth.ts.
Follow the patterns in CLAUDE.md. Write the code only."

Subagent 2 (Critic):
"Review the implementation at src/auth/oauth.ts.
Check for: security issues, missing error handling,
convention violations. Report issues only — do not fix."

The implementer doesn't second-guess itself. The critic doesn't get defensive about its own implementation. Separation produces better results than asking one agent to do both.

The Specifier + Implementer Pattern

For complex features:

Plain text

Subagent 1 (Specifier):
"Given the requirements in @docs/auth-spec.md, write a detailed
technical spec for the implementation: data model, API contract,
edge cases, error states. Output to docs/auth-technical-spec.md."

[After Subagent 1 finishes]

Subagent 2 (Implementer):
"Implement the authentication feature exactly as specified in
@docs/auth-technical-spec.md. Do not deviate from the spec.
If something in the spec seems wrong, note it in a comment
but implement as specified."

The spec is written without the pressure of implementation. The implementation is focused without the distraction of design.

The Researcher + Builder Pattern

Plain text

Subagent 1 (Researcher):
"Research how Auth.js v5 handles database session storage.
@fetch the current Auth.js docs.
Summarize: the configuration options, the required Prisma schema,
the known gotchas. Output to docs/authjs-research.md."

[After Subagent 1 finishes]

Subagent 2 (Builder):
"Implement Auth.js v5 with database sessions.
Use the research at @docs/authjs-research.md.
Our database schema is at @prisma/schema.prisma."

The researcher doesn't write code; it gathers information. The builder doesn't research; it builds from the gathered information. Each is focused.

Git Worktrees: Isolated Working Directories

The risk with parallel subagents: if two agents write to the same file simultaneously, they conflict. Git worktrees solve this by giving each agent its own isolated copy of the repository.

How Git Worktrees Work

A git worktree is a second working directory linked to the same git repository. Different branch, different files on disk, same git history.

Bash

# Create a worktree on a new branch
git worktree add ../project-auth-feature auth-feature

# Now you have:
# ../project/           ← main branch (main working directory)
# ../project-auth-feature/  ← auth-feature branch (isolated copy)

Both directories are the same repo. You can commit from either, merge branches, etc. But changes in one don't appear in the other until merged.

Worktrees + Subagents

Plain text

Parent agent:
Creates worktree-1 on branch feature/auth
Creates worktree-2 on branch feature/payments
Spawns Subagent 1 → works in worktree-1
Spawns Subagent 2 → works in worktree-2
Both complete
Parent merges the branches
Removes worktrees

No file conflicts. No agents stepping on each other. Each works in total isolation and the results are merged afterward.

Creating a worktree:

Bash

git worktree add ../project-feature-auth feature/auth
git worktree add ../project-feature-payments feature/payments

Listing worktrees:

Bash

git worktree list

Removing a worktree:

Bash

git worktree remove ../project-feature-auth

Crystal: A Subagent Orchestration UI

Crystal is a macOS app built specifically for git-worktree-based subagent orchestration. It handles the worktree creation, subagent spawning, and results review in a GUI.

If you're on macOS and want to try the subagent pattern without managing worktrees manually, it's worth exploring.

The underlying pattern is the same regardless of whether you use Crystal or do it manually: isolated worktrees, parallel agents, merge at the end.

When Parallelization Hurts

The overhead of splitting work matters. Don't parallelize small tasks:

Plain text

Wrong:  Spawn 3 subagents to rename 3 variables
Right:  Do it in one pass — the overhead isn't worth it

Wrong:  Parallelize tightly coupled changes that need to agree on types
Right:  Define the shared types first, then parallelize implementation

Wrong:  Parallelize when you're not sure how the pieces fit together
Right:  Understand the whole first, then split confidently

The threshold: if a task takes under 5 minutes in a single session, parallelization isn't worth the overhead. If it would strain a single context window, or if it's clearly separable, parallel is better.

The Practical Pattern

A realistic subagent workflow for a medium-sized feature:

Plain text

1. Single session: explore the codebase, understand the current state
   > @src/ how does data flow through the checkout process?

2. Single session: write the implementation plan
   > create a detailed plan for adding subscription tiers to the checkout

3. Review the plan — are the parts truly independent?

4. If yes: spawn subagents for each part with worktrees
   - Subagent 1: subscription database schema + migration
   - Subagent 2: subscription UI components
   - Subagent 3: subscription API endpoints

5. Review each subagent's output
6. Merge the branches
7. Integration test: single session to wire everything together

The integration step is important. Subagents working in isolation might produce pieces that almost fit together. A final single-agent integration pass catches the gaps.

The Signal to Use Subagents

You want subagents when:

A task is clearly divisible into independent streams
Context pressure is already a problem mid-task
The work is repetitive across many files (lends itself to identical agent configs)

You want a single session when:

The pieces are tightly coupled
You're not sure how it fits together yet
The task is small enough that one context window is plenty

Subagents are a power tool. Like any power tool, using them on the wrong job creates more mess than working without them.