Git Worktrees for Parallel Work

Understand what git worktrees are and why they matter

Know how Claude Code uses worktrees for parallel work

Manually enter and exit worktrees

Merge changes from worktrees back to your branch

Know when worktrees help versus add complexity

Git worktrees let you have multiple working copies of a repository simultaneously. Each worktree is a separate checkout, with its own branch and working directory. Changes in one worktree do not affect others.

Claude Code uses worktrees to isolate work. When subagents need to make changes in parallel, each gets its own worktree. This prevents conflicts and allows true parallel development. You can also enter worktrees manually for experimental work.

This lesson explains how worktrees work in Claude Code.

A git worktree is a linked working tree. It shares the same repository (the .git directory) but has its own files and branch.

Without worktrees:

You have one working directory. To work on a different branch, you stash or commit changes, switch branches, and continue. You can only work on one branch at a time.

With worktrees:

You have multiple working directories, each on its own branch. You can edit files in one worktree while another is building, testing, or being reviewed.

Example:

Each directory is fully functional. Changes are isolated until you merge.

Claude Code creates worktrees automatically in several situations:

Batch operations:

When you run /batch, each subagent works in its own worktree. This allows parallel changes to different files without conflicts.

Isolated subagent work:

When Claude spawns a subagent with isolation: worktree, the subagent works in a separate checkout. If the subagent's work fails or is rejected, your main directory is untouched.

Experimental changes:

You can ask Claude to make experimental changes in a worktree:

Worktree cleanup:

If a subagent makes no changes, Claude cleans up the worktree automatically. If changes were made, you get the branch name for review or merge.

You can enter a worktree for your own experimental work:

Command:

Or:

Claude creates a new worktree on a fresh branch and changes the working directory. Your main session now operates in the worktree.

What happens:

Claude creates a new branch from your current commit

Claude creates a new working directory

Your session moves to that directory

All edits happen in the worktree

You can verify by checking:

When you are done with worktree work:

Discard changes:

The worktree is deleted. Changes are lost.

Keep changes:

The worktree is deleted but the branch remains. You can merge it later.

Merge changes:

Claude merges the worktree branch into your target branch.

List worktrees:

Shows all active worktrees and their branches.

Check which worktree you are in:

Worktrees typically live in a .worktrees or worktrees directory adjacent to your main repository.

After subagent work or your own experimentation, you need to integrate changes.

Simple merge:

Claude performs a standard git merge.

With review:

Claude shows what changed so you can review.

Cherry-pick:

If you want some changes but not all.

Resolving conflicts:

If the merge has conflicts, Claude helps resolve them:

Parallel development:

Multiple features or fixes happening simultaneously without branch switching.

Safe experimentation:

Try a risky refactor without affecting your working directory.

Review isolation:

Keep review changes separate from new development.

Batch operations:

The /batch skill depends on worktrees for parallel subagent work.

Long-running changes:

Start a big change in a worktree while keeping your main directory available for quick fixes.

Simple, linear work:

If you are working on one thing at a time, worktrees add overhead.

Small repositories:

The parallelization benefit is minimal in small codebases.

Disk space:

Each worktree is a full checkout. Large repositories multiply disk usage.

Mental overhead:

Tracking which worktree has which changes requires attention.

Merge complexity:

More parallel work means more potential merge conflicts.

Experimental refactor:

You can evaluate the result and decide whether to keep or discard.

Batch migration:

Each file is updated in a separate worktree. PRs are created for each.

Parallel fixes:

Bug fix is isolated from feature work.

Safe testing:

Your main directory stays stable.

Name branches clearly:

When creating worktrees manually, give branches descriptive names:

Clean up promptly:

Delete worktrees when done:

Stale worktrees consume disk space.

Merge regularly:

Do not let worktree branches diverge too far from main. Merge conflicts grow with divergence.

Document in progress work:

If you leave a worktree mid-task, note what you were doing:

Session naming helps you remember state.

Git worktrees are separate checkouts sharing the same repository

Claude Code uses worktrees to isolate parallel subagent work

Enter worktrees manually for experimental changes

Exit with discard, keep branch, or merge

Worktrees enable parallel development without branch switching

The /batch skill depends on worktrees for parallel operations

Clean up worktrees when done to save disk space

Merge regularly to avoid large conflicts

Experiment with worktrees:

Start Claude Code in a git repository.

Ask: enter a worktree for testing

Check your location: pwd and git branch

Ask Claude to make a small edit to any file.

Ask: show me the diff

Ask: exit the worktree and discard the changes

Check your location again: pwd

Verify the edit is gone from your main directory.

Repeat, but this time exit with keep the branch.

Run git branch to see the preserved branch.

Delete the branch when done: git branch -d <branch-name>

This exercise shows the worktree workflow.

https://code.claude.com/docs/en/worktrees - Worktree documentation in Claude Code

https://code.claude.com/docs/en/agents#isolation - Worktree isolation for subagents

https://code.claude.com/docs/en/common-workflows - Worktrees in common workflows