Worktrees and parallel development

Work on multiple features at once without conflicts

⏱ Est. ~5 min

01 · Read

What if you could work on two features at the same time without stepping on each other's files? Normally your project has one set of files per branch. You're halfway through implementing auth when a critical bug comes in — you have to stash your work, switch branches, and lose your flow.

Git worktrees solve this. A worktree is a separate working directory that shares the same git history as your main project. Each worktree has its own branch and files. Claude Code has built-in worktree support — you can spin up an isolated workspace with a single flag.

💡 Picture thisPicture an office with two desks instead of one. Each desk has its own copy of the documents you're working on, but both connect to the same filing cabinet (the git history). You can work on a feature at desk 1 and fix a bug at desk 2, never shuffling papers between them.

Key points

A worktree is a separate working directory sharing the same git repo
Each worktree has its own branch and files
No stashing, switching branches, or losing flow
Claude Code creates worktrees automatically with --worktree

02 · Code example

Create a worktree with the --worktree flag. Each one gets its own branch and directory.

Create a worktree

# Start a Claude session in an isolated worktree
claude --worktree feature-auth

# Start another session for a bug fix
claude --worktree bugfix-login

# Auto-generate a random worktree name
claude --worktree

What happens behind the scenes

Worktree location: .claude/worktrees/feature-auth/
Branch created:   worktree-feature-auth
Files:            Full copy of your project
Git history:      Shared with main repo

Each worktree lives in its own directory under .claude/worktrees/ with its own git branch. Two Claude sessions can edit files at the same time without conflicts. When you're done, worktrees with no changes get cleaned up automatically.

03 · Read

Worktrees are especially powerful with parallel Claude sessions. Here's a typical flow:

1. You're implementing a feature in your main directory 2. A bug report comes in — claude --worktree bugfix-123 3. The bugfix session works independently in its own copy 4. Once fixed, merge the bugfix branch back into main 5. Continue your feature work without missing a beat

You can also use worktrees inside subagents. Add isolation: worktree to your subagent's SKILL.md frontmatter and it'll automatically work in its own worktree — great for tasks that need to edit files without touching your main working directory.

Key points

Run multiple Claude sessions in parallel, each in its own worktree
Merge the worktree branch back when you're done
Subagents can use worktrees with isolation: worktree
Add .claude/worktrees/ to your .gitignore

04 · Read

For truly large-scale changes — renaming a function across 100 files, or migrating an API — Claude Code provides the /batch command. It breaks your task into independent units, spawns a subagent for each, and each one works in its own worktree.

Each subagent creates a draft pull request for its piece. You review, merge the good ones, and iterate on the rest. This is how professionals handle large refactors — break them into independent, reviewable chunks.

Key points

/batch breaks a large task into independent units
Each unit runs in its own worktree with its own subagent
Each creates a draft PR for review
Perfect for large-scale refactors and migrations

05 · Quiz

What happens when a Claude worktree session ends with no uncommitted changes?

The worktree is cleaned up automatically
The worktree stays forever until you delete it manually
Claude asks you to commit before closing
The worktree moves to a backup directory

06 · Drag to sort

Put these parallel worktree workflow steps in the right order.

(This section is interactive — please enable JavaScript.)

Other lessons in this chapter

⚠ The full interactive experience needs JavaScript. Please enable it and reload.

※ This is an independent Traditional Chinese teaching project — not an official Anthropic product. Claude™ is a trademark of Anthropic, PBC.