Skip to main content
Official reference — The official parallel execution docs cover claude --worktree, the /batch command, and worktree isolation mechanics. This page is the opinionated playbook for making parallelism work in practice.

​
The Core Idea

One agent handles one task at a time. While it’s writing tests, it’s not implementing the next feature. The fix: run multiple agents on the same project, each in its own isolated workspace. The goal isn’t “run as many instances as possible.” It’s maximum output from minimum viable parallelization. Every additional session is a review burden. Add one when you have a clear, scoped task — not because you have a free terminal.

​
When You Need Worktrees

Not every parallel session needs a worktree. The trigger condition is specific:
Use /rename auth-refactor to name each session — when you’re switching between 3-4 terminals, unnamed sessions become unmanageable.

​
Scoping Parallel Work

The hardest part of parallelism isn’t the tooling — it’s deciding what each agent should own. Two rules: 1. Main session writes code, forks answer questions. Keep code changes in your primary session. Use /fork for research: “What does the auth middleware do?” or “How does the billing API handle retries?” Forks read the codebase without changing it, so there’s zero conflict risk. 2. Scope by file ownership, not by step. Don’t split “implement feature X” into “write the code” and “write the tests” — that creates dependencies. Instead, split by module boundaries: one agent owns auth/, another owns billing/, each writes its own implementation and tests.
Never split implementation from its tests. Keep them in the same agent, same worktree. An agent that writes code without running tests produces untested code. An agent that writes tests without seeing the implementation produces wrong tests.

​
Starter Patterns

​
Dual-Instance Kickoff

When starting a new feature or project, run two agents simultaneously: The scaffolder gives the researcher a structure to reference. The researcher gives the scaffolder context for the next round. Merge their outputs and start the real implementation with a fully prepared workspace.

​
The Cascade

For ongoing parallel work across multiple sessions:
  1. Open a new terminal tab for each task
  2. Arrange tabs left-to-right in priority order
  3. Kick off each agent with a clear, scoped prompt
  4. Sweep left to right — review output from oldest to newest
Each worktree should be self-contained: its own session, its own branch with regular commits, and its own HANDOFF.md if you need to pause and resume.

​
Conflict Resolution

When parallel branches merge, conflicts happen. The mental model:
Non-overlapping work (agents owned different files): land branches in any order. No conflicts possible. Overlapping work (agents touched shared files): land sequentially. Merge the highest-priority branch first, then rebase the next branch onto the updated main. If a rebase produces conflicts, feed the conflict context back to the agent:
This isn’t a failure state — it’s the expected cost of parallelism on shared code. Budget for it.

​
How Many Is Too Many?

The constraint isn’t compute. It’s your ability to review and integrate the output. Each parallel session also loads context independently — 3 sessions ≈ 3× the token cost. See Cost & Model Routing for optimization strategies.

​
Subagent Isolation

For programmatic parallelism (not just terminal tabs), agents can spawn subagents with built-in worktree isolation:
This is the bridge between manual parallel sessions and the orchestration patterns below. See Subagent Patterns for the full guide.

​
Going Deeper

Once parallel sessions are second nature, the next question is how much coordination your tasks actually need: