Running Claude in Parallel

On this page

Chapter draft. The full treatment of the technique the Version Control chapter introduces in one paragraph. Thesis: once AI stops being one-task-at-a-time, a single working directory is the bottleneck — worktrees are how you give each task its own isolated, parallel workspace, and they’re a large part of what separates “using Claude” from “using Claude effectively.” Deliberately tool-agnostic: it teaches the technique, and treats the automation layer (including the author’s own Endless) as a category, never a prescription. Placement TBD — Part III candidate. Working title.

The bottleneck nobody warns you about

The first time you use Claude, you do one thing at a time. Ask, watch, accept, ask again. It feels productive because it is — but it’s also the slowest possible way to use a programmer who never gets tired and can work on ten things at once.

The instinct to go parallel shows up fast: while Claude refactors the database layer, why can’t another session build the export feature? The answer, if you try it naively, is painful. Both sessions are editing the same folder — the one project directory on your disk. They overwrite each other’s files, they trip over each other’s half-finished changes, and you end up with a tangle neither you nor Claude can make sense of. So most people retreat to one-at-a-time and quietly conclude that parallel AI work “doesn’t really work.”

It works. You just need to stop making every session share one room. That’s what this chapter is about.

What a worktree is

Recall from the Version Control chapter that a branch is a parallel line of work, and that normally you can only occupy one branch at a time because your project folder holds a single checked-out copy of the files. To switch branches, you put your current work down and pick up another — one desk, one project on it at a time.

A worktree breaks that one-desk limit. It lets a single repository have several working folders open at once, each checked out to its own branch, all sharing the same underlying history. Picture one library (the repository, with its complete record of every change) and several reading rooms attached to it (the worktrees), each with a different book open on the table. The history is shared and central; the workspaces are separate and simultaneous.

Concretely: your main project might live in ~/projects/app, and you add worktrees alongside it — ~/projects/app-export, ~/projects/app-refactor — each a real folder you (or a Claude session) can work in independently, each on its own branch, none of them disturbing the others or the original.

Why this is the unlock for AI

Worktrees existed long before AI; developers used them to juggle a hotfix without disrupting a feature. But they matter far more in the AI era, because AI removes the human bottleneck that used to make parallelism pointless. One person can only think about one thing at a time, so multiple workspaces were a mild convenience. A fleet of Claude sessions can genuinely work on five things at once — and now the workspace, not the human, is the thing you need to multiply.

Four properties make worktrees the right substrate:

Parallel. Each session gets its own folder, so several can run at the same moment without colliding. This is the difference between one Claude and a fleet.
Isolated. What happens in one worktree cannot corrupt another, and cannot touch your main working copy. A session that goes badly wrong is contained to its own room. The blast radius of a mistake shrinks to a single folder.
Non-blocking. You don’t have to wait for a long task to finish before starting the next. Kick off a big refactor in one worktree and keep moving in another.
Cheap to abandon. If an experiment doesn’t pan out, you delete the worktree and it’s gone — no untangling, no careful reverting, no residue left in your main folder. This makes it psychologically easy to let Claude try things, which is where a lot of its value hides.

There’s a bonus property worth naming: comparison. Because worktrees are cheap and isolated, you can hand the same task to two sessions in two worktrees, each taking a different approach, and compare the results side by side — then keep the better one and delete the other. Running two attempts and picking the winner is a genuinely powerful pattern, and worktrees are what make it practical.

The mental shift

The hard part of worktrees isn’t the mechanics; it’s a shift in how you picture your work. Newcomers hold onto the idea of “my working copy” — the one folder, the one current state, the place where the project is. Worktrees ask you to trade that for “a pool of workspaces”: the project’s real identity lives in its history, and working folders are disposable, spin-up-and-tear-down things you create per task and throw away when done.

Once that click happens, the way you deploy Claude changes. You stop thinking “what should Claude work on next” and start thinking “what are the three independent pieces of work I can put in flight right now, each in its own room.” That’s the operating posture of someone using AI at full leverage, and it’s invisible to anyone still sharing one folder.

You won’t run these — but you must understand them

Here’s the correction to make right away, because it changes how you read everything else: you, the reader, will almost never type a git worktree command yourself. Two things run them for you:

Claude, at your direction. The everyday case. You say “set that up in its own worktree” and Claude runs the commands. Managing branches and worktrees is programmer’s work, and Claude is your programmer — but the instruction to do it has to come from someone who knows the move exists.
A tool that automates the whole lifecycle. You ask for a piece of work and the tool silently creates the worktree, sets it up, runs the session there, and cleans up. You never see the plumbing.

So your job with worktrees isn’t mechanical — it’s understanding the concept and the directory structure well enough to do two things you can’t delegate:

Guide Claude. To say “put that on a separate worktree,” or to ask “is this change on main or on a worktree?”, you have to understand what you’re asking for. Claude executes; the direction comes from you.
Find your files. Worktrees put your project in more than one place on your disk at once. When you need to open a file — or tell Claude which copy you mean — you have to know the layout.

That second point is the one newcomers miss until it bites. With worktrees, “where is my project?” stops having a single answer. It looks like this:

~/projects/app            ← the main folder, on the main branch
~/projects/app-export     ← a worktree, on the export-feature branch
~/projects/app-refactor   ← a worktree, on the refactor branch

One project, one shared history, three folders on disk. If you go looking for a file and it’s “not there,” you may simply be standing in the wrong room.

The commands themselves — the ones Claude runs on your behalf — are few, and worth recognizing so you know what Claude is doing when it does it:

git worktree add ../app-export -b export-feature — create the ../app-export folder on a new export-feature branch.
git worktree list — show every folder attached to the repo and which branch each is on. (Have Claude run this when you lose track of what’s where.)
git worktree remove ../app-export — tear one down once the work is merged or abandoned.

And one orientation command earns a place right next to git status: git log --oneline -20 — the last twenty commits, one line each. People run it so constantly they alias it (a common one is glo). It’s how you see what’s actually committed in the folder you’re standing in, which is exactly how you tell what a worktree contains that main doesn’t, or confirm a change landed where you meant it to. When you’re disoriented about which room holds what: status tells you what’s changed, glo tells you what’s committed.

About the automation tools (and not prescribing one)

A category of tooling exists specifically to manage the worktree lifecycle for you, so even the “tell Claude to do it” step disappears — you request work, and isolation happens automatically. The author’s own tool, Endless, is one such system: it builds worktree isolation in so each unit of work lands in its own workspace and you never manage folders yourself.

It is deliberately not this chapter’s job to sell you Endless or any single tool. The point is the technique — parallel, isolated workspaces — and there are really only two modes you’ll operate in:

Direct Claude to manage worktrees as part of the work: understand the concept, delegate the commands.
Let a tool automate the lifecycle so isolation is invisible (Endless is one example; the category is growing, and Claude Code’s own parallel agents use the same underlying isolation).

A developer can also run git worktree by hand, and some will — but that’s not the mode most readers of this book operate in, and you don’t need to adopt it to get the benefit. Choose based on how much parallelism you actually run: occasional single tasks may never need more than the main folder; orchestrating many sessions is where automation pays off. The mistake to avoid isn’t which tool — it’s not knowing the technique exists, and serializing work that could have run five-wide.

The sharp edges (so they don’t surprise you)

Worktrees share history but not your uncommitted working state, and that trips people up. A few honest gotchas:

A fresh worktree starts empty of the uncommitted stuff. Downloaded dependencies (node_modules, a Python virtual environment), local configuration, and secret files (see the Environment variables Briefing) do not automatically appear in a new worktree — they aren’t tracked by Git. You often have to install dependencies or copy an env file into each new worktree before it runs. (This setup step is a big part of what the automation tools do for you.)
The same branch can’t be checked out in two worktrees at once. Git blocks it, on purpose — two folders editing the same branch would defeat the isolation. Each worktree gets its own branch.
They cost disk. Each worktree is a full copy of the project’s working files (the history is shared, so it’s cheaper than cloning the whole repo, but not free). A dozen worktrees is a dozen copies of the source tree on your disk.
They need cleanup. Abandoned worktrees linger as folders until removed. Left unmanaged, they accumulate — another reason automation helps once you run many.

None of these are reasons to avoid worktrees; they’re reasons to either use a tool that handles them, or to have Claude set up and tidy them as you go — while you keep enough of the three commands above in mind to recognize what it’s doing.

When not to bother

Worktrees earn their keep when you have genuinely independent work to run in parallel. They don’t help — and add overhead — when:

Your tasks depend on each other and must happen in order anyway.
You’re doing one focused thing and parallelism would just be juggling.
The work is small enough that setup cost exceeds the time saved.

Like everything in this book, the technique is a tool, not a mandate. The skill is recognizing when independent work is sitting in front of you that you’re needlessly serializing — and reaching for isolation then.

Where this connects

The control stack (Chapter 7, The Control Stack) — your CLAUDE.md and hooks travel with each worktree, so every parallel session inherits the same steering.
Team adoption (Chapter 13, Team Adoption & Code-Review Culture) — worktrees are a personal-scale version of what branches-and-review do for a team; the isolation instincts transfer directly.
When Claude Code fails (Chapter 14, When Claude Code Fails) — isolation is a containment strategy: a session that fails badly in its own worktree can’t take your working copy down with it.
Version Control (Chapter TK, Version Control) — this chapter is the deep end of the worktree paragraph there; branches and undo are its prerequisites.

The one-line takeaway: the project lives in its history; working folders are cheap, disposable rooms you spin up per task. Internalize that, and running Claude five-wide stops feeling reckless and starts feeling normal.

Draft notes (not for the reader)

Tool-agnostic is a hard constraint. Endless appears once, as one example among three ways to get the technique, explicitly not as the prescription — per the author’s instruction. If a later pass makes Endless feel like the recommended path, that’s a regression; keep the technique primary and the tool incidental.
Confirm Endless specifics before adding any. The chapter currently claims only that Endless “builds worktree isolation in” (stated by the author). Do not describe Endless’s mechanics, UI, or workflow beyond that without confirming details — avoid putting words in the tool’s mouth.
Placement is genuinely open — Part III (“Managing Your AI Programmer”) is the lead candidate, since this is an operating/scaling technique, not foundational vocabulary. It forward-refs cleanly from the Part I Version Control chapter regardless. Number left at TK.
The reader does NOT run git worktree themselves — corrected per author. The two operating modes are “direct Claude to manage worktrees” and “let a tool automate the lifecycle”; hand-running is a developer’s option, explicitly not the reader’s mode. The commands appear only so the reader recognizes what Claude does and understands the resulting directory structure — which they need in order to guide Claude and to find files. If a pass reframes the reader as the one typing the commands, that’s a regression.
Non-dev accessibility check: the “reading rooms / one library” and “pool of workspaces” metaphors, plus the directory-tree diagram, are doing the load-bearing work for non-devs; the git worktree commands are recognition aids, not instructions, and can be skimmed. If a beta non-dev reader stalls, cut the command lines further, not the metaphors or the folder diagram.
The “comparison / two attempts, pick the winner” bonus could grow into its own worked example once case studies exist (Appendix C, Annotated Case Studies) — it’s the most persuasive single argument for the technique.
Cross-refs use xref tokens so the final renumber resolves them.

Found something wrong, unclear, or plainly disagreeable? Open an issue