Parallel Agents
One Claude session is one pair of hands. With subagents Subagent A specialized AI agent Claude Code can delegate a task to. It works in its own separate context window with its own tools and instructions, then reports back a summary. Define one as a Markdown file in `.claude/agents/` (project) or `~/.claude/agents/` (personal) with `name` and `description` frontmatter; Explore, Plan, and general-purpose are built in. "Like hiring a specialist contractor for a specific part of a project. They work independently and report back when done." Git Worktree A second (or third) working folder attached to the same Git repository, each checked out on its own branch. It lets several AI agents edit code in parallel without trampling each other's files. Claude Code can create one for you with `claude --worktree feature-auth`, and subagents can use `isolation: worktree`. "Like giving each contractor their own copy of the blueprints and their own room to work in, then merging the finished rooms."
1Two kinds of parallel
Subagents: parallel inside one session
Your main Claude delegates side tasks to helpers. Each helper gets a fresh, isolated context window Context Window The amount of text an AI can 'see' at once, measured in tokens: your instructions, the conversation, files it read, and tool results. Current Claude models (Opus 5.5, Sonnet 5, Fable 5.1) offer 1M-token windows and Haiku 4.5 has 200K, but even huge windows work best when kept focused. "Like short-term memory. The bigger the window, the more the AI can remember from your conversation."
Worktrees: parallel sessions
Several full Claude Code sessions, each in its own checkout on its own branch. Edits in one never touch the others. Great for separate features or a bug fix while a feature is in progress.
The analogy: subagents are you sending an assistant to the library. Worktrees are giving two contractors their own copies of the blueprints and their own rooms to work in.
2Subagents: built-in and custom
Claude Code Claude Code Anthropic's agentic coding tool. It lives in your terminal (and in VS Code, JetBrains, and on the web), reads your codebase, edits files, runs commands, and ships code. Install with the native installer (`curl -fsSL https://claude.ai/install.sh | bash` on macOS/Linux, `irm https://claude.ai/install.ps1 | iex` on Windows); it needs a Pro, Max, Team, Enterprise, or Console account. "Like having a senior developer living in your terminal, ready to help 24/7."
Explore
Fast, read-only codebase search. Skips CLAUDE.md to stay cheap.
Plan
Read-only research agent used in plan mode.
general-purpose
Full tool set for complex, multi-step side tasks.
You can also ask for one directly:
Prompt
use a subagent to investigate how our auth system handles token refreshWrite a custom subagent
A custom subagent is a markdown file with frontmatter. Put it in .claude/agents/ (this project, commit it) or ~/.claude/agents/ (all your projects). name and description are required; the description is how Claude decides when to delegate, so make it specific.
.claude/agents/test-writer.md
---
name: test-writer
description: Writes and runs Vitest tests for a given module. Use after a feature is implemented.
tools: Read, Glob, Grep, Edit, Write, Bash
model: sonnet
---
You write focused Vitest tests.
1. Read the module and any existing tests next to it.
2. Cover the happy path, one edge case, and one failure case per exported function.
3. Only create or edit files under tests/ or *.test.ts.
4. Run npm test and report: files written, pass/fail counts, anything you couldn't test.Other useful fields: disallowedTools, permissionMode, maxTurns, skills, mcpServers, background: true, and isolation: worktree. model takes sonnet, opus, haiku, or inherit.
To guarantee a specific subagent runs, @-mention it: @agent-test-writer cover lib/billing/invoices.ts. Note that /agents is no longer a wizard; just ask Claude to create or edit a subagent, or write the file yourself.
3Fan out in parallel
Claude can run several subagents at the same time, in the background, while you keep talking to the main session. The trick is asking for independent pieces with clear boundaries:
Prompt
Run three subagents in parallel:
1. Explore: list every place we call stripe.* and which API version each uses.
2. Explore: find every route under app/api that doesn't check auth().
3. general-purpose: read lib/db/schema.ts and list tables with no index on foreign keys.
Each one reports back in under 20 bullets. Don't edit anything.Research fans out beautifully because nobody writes files. For parallel edits, give each subagent its own worktree so they can't trample each other:
Prompt
use worktrees for your agentsOr make it permanent with isolation: worktree in the subagent's frontmatter. Each gets a temporary worktree that's cleaned up automatically if it made no changes. For big mechanical changes, the bundled /batch skill does the whole dance: it splits the job into independent units, shows you a plan, then runs one background subagent per unit in its own worktree.
Claude Code
/batch migrate src/ from JavaScript to TypeScript4Git worktrees for multiple sessions
A worktree is a second (or fifth) working directory of the same Git Git A version control system that tracks changes to your code. It lets you save snapshots, undo mistakes, and collaborate with others. "Like Google Docs history on steroids. You can see every change ever made and go back in time."
Terminal 1
claude --worktree feature-authTerminal 2
claude --worktree fix-billing-bug- Each lands in
.claude/worktrees/<name>/on a new branchworktree-<name>. Add.claude/worktrees/to your.gitignore. -wis the short form.claude --worktree "#1234"branches from a pull request.- On exit, a clean worktree is removed; one with changes prompts you to keep or delete it.
- It's a fresh checkout: no
node_modules, no.env.local. Install dependencies in each one, and list gitignored files to copy in a.worktreeincludefile.
.worktreeinclude
.env
.env.localOr manage worktrees with plain git
Useful when you want an existing branch or a folder outside the repo:
Terminal
git worktree add ../myapp-feature-a -b feature-a # new branch
git worktree add ../myapp-bugfix fix-issue-456 # existing branch
cd ../myapp-feature-a && npm install && claude
git worktree list
git worktree remove ../myapp-feature-aTwo dev servers can't both use port 3000. Run the second with npm run dev -- -p 3001. And remember every worktree that talks to a database is talking to the same database unless you point it elsewhere (a Neon branch per worktree is a nice trick).
5Coordination patterns
Step 1
Plan
In one session, break the work into chunks that don't touch the same files. Write the plan down (a markdown file is fine).
Step 2
Fan out
Hand each chunk to a subagent or a separate worktree session, with the file list it owns and a clear definition of done.
Step 3
Integrate
Merge the branches or collect the results one at a time. Resolve conflicts yourself (or with Claude) in the main session.
Step 4
Verify
Run type-check, tests, and a build on the combined result. Parallel pieces that each pass can still fail together.
Disjoint file ownership
The number one rule: two agents never own the same file. Say it explicitly in the plan.
docs/plan-billing.md
# Billing feature: parallel plan
Shared contract (written first, by me, before fan-out):
- lib/billing/types.ts -> Invoice, Plan types. NOBODY else edits this.
Agent A (worktree billing-api) owns:
- app/api/billing/**
- lib/billing/queries.ts
Agent B (worktree billing-ui) owns:
- app/(dashboard)/billing/**
- components/billing/**
Agent C (subagent test-writer) owns:
- tests/billing/**
Done = npx tsc --noEmit passes, npm test passes, no edits outside owned paths.Contract first
Write shared types, API shapes, or DB schema before fanning out. Parallel agents guessing at each other's interfaces is how you get three incompatible versions of Invoice.
Verify the whole, not the parts
After merging, run the full check in one place. Each branch passing its own tests proves little about the combination.
6Costs and traps
Parallel saves wall-clock time, not tokens Tokens The units AI uses to process text. Roughly 1 token = 4 characters. You pay per token, and context windows are measured in tokens. "Like words on a meter. The more you write (or the AI writes), the more tokens tick by."/usage.
- Route cheap work to cheap models. A search-and-summarize subagent rarely needs Opus. Set
model: haikuorsonnetin its frontmatter. - Keep subagent descriptions short. Every custom subagent's description sits in your main context on every turn.
- Cap the fan-out. Three well-scoped agents beat ten vague ones. You still have to review everything they produce.
Overlapping files
Two agents editing the same file in the same checkout is a race. Worktrees or strict ownership, always.
Splitting sequential work
If step 2 needs step 1's output, parallelizing it just produces two guesses. Parallelize independent work only.
Forgetting the integrate step
Five branches is not a feature. Budget real time for merging and fixing the seams.
Review debt
Agents generate code faster than you can read it. If you can't review it, you can't ship it.
7When to go parallel
Good fits
- Research across a big codebase (subagents, read-only).
- A bug fix while a feature is mid-flight (two worktrees).
- Frontend + backend + tests against an agreed contract.
- Mechanical changes across many files (
/batch). - Independent reviews: security, performance, accessibility.
Stay single-threaded
- You're still figuring out what to build.
- The pieces share files or a changing schema.
- Small tasks: coordination overhead beats the speedup.
- You're near your usage limit.
Next steps
Ready to let agents work while you sleep? Take the next step to background and cloud agents.