Skip to main content

Git Worktrees & Parallel Workstreams

Advanced
What you'll learn
  • What a git worktree is — one repo, multiple working directories, each on its own branch
  • The exact problem it solves: stopping parallel Claude sessions from colliding on the same files
  • The four commands to add, list, and remove worktrees
  • When the technique earns its keep — and the three pitfalls that bite at merge-time
  • How worktrees compose with subagents: parallelism across sessions vs within one

A git worktree lets one repository have multiple working directories, each checked out to a different branch. Pair that with Claude Code and you can run several sessions in parallel on the same project — each editing its own files, with no collisions.

The problem it solves​

If two Claude sessions edit the same working directory at once, they trip over each other's changes. Worktrees give each session its own directory and branch, so parallel work stays isolated until you merge.

The basics​

Four commands carry the whole workflow: add a worktree (new dir + new branch), list what exists, and remove one when you're done.

Guided walkthrough1 of 4
  1. From your repo, git worktree add ../app-feature-a -b feat-a creates a new directory AND a new branch in one shot.

The four-command workflow

# from your repo
git worktree add ../app-feature-a -b feat-a   # new dir + new branch
git worktree add ../app-fix-123 -b fix-123
git worktree list
# when done with one:
git worktree remove ../app-feature-a

Open a Claude Code session in each worktree directory and let them work independently.

When it's worth it​

  • Parallel features/fixes you want to progress at once.
  • A long task running in one worktree while you keep working in another.
  • Risky experiments isolated from your main checkout.

Pitfalls​

Watch out
  • Watch the merge-back: branches will eventually merge — conflicts surface then, not during. Keep worktrees focused and short-lived.
  • Don't run stateful, shared resources (one dev DB, one port) from two worktrees without separating them.
  • Clean up with git worktree remove so stale dirs don't accumulate.

Worktrees vs subagents​

Two different axes of parallelism — they don't compete, they stack.

What it parallelizesIsolation
SubagentsWork within one session (delegation)Isolated context
WorktreesWork across sessions on diskIsolated branches/files

They compose well: a session in a worktree can itself spawn subagents.

Pro tip
  • Use a worktree when you need two Claude sessions touching the same repo at once; use a subagent when one session needs to offload a chunk of work into isolated context.

Check yourself

0/4
  1. What does a git worktree give you?
  2. Which command creates a new directory AND a new branch in one step?
  3. When do merge conflicts from parallel worktrees actually surface?
  4. How do worktrees and subagents relate?
Key takeaways
  • A git worktree = one repo, multiple working directories, each on its own branch — the basis for collision-free parallel Claude sessions.
  • Two sessions on one working directory trip over each other; a worktree per session keeps files and branches isolated until you merge.
  • git worktree add ../dir -b branch creates dir + branch; list shows them; remove cleans up.
  • Worth it for parallel features/fixes, long-running tasks alongside other work, and isolated risky experiments.
  • Beware the merge-back, don't share stateful resources (DB, port) across worktrees, and always clean up — and remember worktrees compose with subagents.

Next​