Skip to main content

Documentation Index

Fetch the complete documentation index at: https://agentic.proxify.io/llms.txt

Use this file to discover all available pages before exploring further.

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:
SituationWorktree needed?
Agents edit different filesNo — same directory is fine
Agents edit overlapping filesYes — isolation prevents write conflicts
One agent codes, the other researchesNo — the researcher isn’t writing files
Multiple features with shared configYes — config changes will collide
# Launch a session in its own worktree (auto-cleans if no changes)
claude --worktree

# Or create worktrees manually for longer-lived branches
git worktree add ../my-app-auth feat/auth
git worktree add ../my-app-perf feat/perf
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:
InstanceRoleDoesDoesn’t
Agent 1: ScaffolderStructureCreates directories, configs, boilerplate, CLAUDE.mdResearch external APIs
Agent 2: ResearcherContextReads existing code, external docs, writes a design briefTouch project files
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: 
Agent branch
    │
    ├─ Rebase onto main
    │   └─ Conflict? → Fix or re-scope
    │
    ├─ Run build + tests
    │   └─ Fail? → Fix before merging
    │
    └─ Pass → Fast-forward main
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: 
Read HANDOFF.md and continue. Your previous changes conflicted with
another branch that landed first. The conflicting files are: [list].
Restructure your changes to work with the updated main branch.
This isn’t a failure state — it’s the expected cost of parallelism on shared code. Budget for it.

​
How Many Is Too Many?

SessionsVerdict
1Baseline — you’re serializing work
2-3Sweet spot for most engineers
4-5Effective if tasks are truly independent
6+Diminishing returns — you can’t review fast enough
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: 
# In an agent definition
isolation: worktree    # Each invocation gets its own worktree
background: true
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:
NeedGo toExample
Independent tasks, no coordinationOrchestration PatternsFan-out migrations, convention sweeps
Tasks that share findings or coordinateAgent TeamsAuth refactor across frontend + backend + tests
Controlling what all of this costsCost & Model RoutingOpus plans, Sonnet implements