AC
Chapter 06Scaling Up

Parallel sessions with git worktrees

Running multiple Claude instances on different tasks. Worktree-based isolation.

25 minLesson 1 of 4

One Claude session equals one task. That is the rule. If you try to give a single session three unrelated tasks, you burn context on all of them and get mediocre results on each. The solution is not to wait for one task to finish before starting the next. The solution is to run three sessions in parallel.

This is the single biggest multiplier I have found in agentic coding. Not better prompts. Not smarter models. Parallelism.

Git worktrees: the enabler

The problem with running multiple sessions in the same repo is obvious: they step on each other. Session A edits utils.ts while session B is reading it. Merge conflicts. Broken state. Chaos.

Git worktrees solve this completely. A worktree is a separate checkout of your repo in a different directory, but sharing the same .git history. Each worktree has its own working tree — its own files, its own branch — but they all share commits, branches, and history.

Each Claude session works in its own worktree. Changes in one worktree do not touch the files in another. No interference. No conflicts during development. Conflicts only surface at merge time, when you are in control.

Isolation

Each worktree is a fully independent directory. Claude can edit, build, and test in one worktree without affecting any other.

Shared history

All worktrees share the same .git directory. Branches, commits, and tags are visible everywhere. You can merge across worktrees instantly.

Lightweight

Creating a worktree is nearly instant — it is a checkout, not a clone. No network calls, no duplicate history.

Clean separation

Each worktree runs on its own branch. No accidental commits to the wrong branch. No mixed-up changes.

How it works in practice

Here is the workflow I use daily. Three tasks, three worktrees, three Claude sessions.

Parallel worktree workflow
# Create worktrees for parallel tasks
git worktree add ../task-auth feature/auth
git worktree add ../task-api feature/api-refactor

# Terminal 1: auth feature
cd ../task-auth && claude

# Terminal 2: API refactor
cd ../task-api && claude

# Terminal 3: your main work continues here
# You stay productive while both agents work

# When tasks complete, merge them back
git merge feature/auth
git merge feature/api-refactor

# Clean up
git worktree remove ../task-auth
git worktree remove ../task-api

Let me break that down step by step.

Step 1: Create the worktree. git worktree add ../task-auth feature/auth creates a new directory ../task-auth and checks out the feature/auth branch there. If the branch does not exist yet, add -b to create it: git worktree add -b feature/auth ../task-auth.

Step 2: Open a new terminal. Navigate into the worktree directory and run claude. That session now operates entirely within that worktree. Every file read, every edit, every bash command — all scoped to that directory.

Step 3: Continue your own work. Back in the main worktree, you keep coding. Or you spin up yet another Claude session for a different task. You are not blocked.

Step 4: Merge when done. Once a worktree task is complete, switch to your main branch and merge: git merge feature/auth. Handle any conflicts the normal way.

Step 5: Clean up. git worktree remove ../task-auth removes the worktree directory. The branch remains — you can delete it when you are done with it.

When parallel sessions shine

Not every situation calls for parallelism. Here is when it works best.

Independent features. Two features that touch different parts of the codebase. Auth system and blog redesign. API refactor and new dashboard component. Zero overlap means zero conflict risk.

Bug fix plus feature. You are building a feature, but a bug report comes in. Spin up a worktree for the hotfix. Fix it, merge it, ship it. Your feature work never stops.

Refactoring while building. One session refactors the data layer while another builds a new feature on top of the existing interface. When the refactor merges, you adapt the feature to the new interface — often a small diff.

When they do not work

Tasks that touch the same files. If both sessions need to edit globals.css or schema.prisma, you will get merge conflicts. Worse — the sessions cannot see each other's changes, so they may make contradictory decisions.

Sequential dependencies. If task B requires the output of task A — say, B builds on an API that A is creating — you cannot run them in parallel. B would be working against an interface that does not exist yet.

Advanced: worktree-based quality pipelines

This is a pattern from the ECC framework (Ralphinho's RFC-Driven DAG) that takes worktrees to the next level. Instead of just isolating features, you isolate pipeline stages.

The idea: each work unit runs through a quality pipeline — implement, review, fix, approve — and each stage runs in its own worktree with a fresh context window. The author and the reviewer never share context. The reviewer sees only the output, not the reasoning that produced it. This eliminates author-bias completely.

Quality pipeline with worktrees
# Stage 1: Author implements in worktree
git worktree add ../impl feature/new-api
cd ../impl && claude  # "Implement the user settings API"

# Stage 2: Reviewer reviews in separate worktree
git worktree add ../review feature/new-api
cd ../review && claude  # "Review the changes on this branch for
                        #  security issues and missing error handling.
                        #  Only report issues you're >80% confident about."

# Stage 3: Author fixes review findings
cd ../impl && claude  # "Fix these review findings: [paste]"

# Merge queue: only merges when all stages pass

The advanced version includes a merge queue with eviction — if a work unit fails review too many times, it gets evicted from the queue and requires human intervention. And conflict recovery — if two work units conflict at merge time, one is automatically rebased and re-verified.

You do not need this level of sophistication on day one. But knowing it exists shows you where the ceiling is. Worktrees are not just a convenience. They are infrastructure for multi-agent pipelines.

Practical limits

Each worktree is a separate directory, which means a separate node_modules install — unless you use a monorepo tool like pnpm that can share dependencies. In a pnpm workspace, each worktree reuses the global store, so install times are fast.

Each Claude session is a separate context window. That means separate cost. Three parallel sessions cost three times as much as one sequential session. The tradeoff is worth it when the tasks are genuinely independent and time-sensitive.

Start with two parallel sessions. Get comfortable with the merge workflow. Then scale to three or four as you build confidence. The goal is not maximum parallelism. The goal is maximum throughput with maintained quality.