Run Parallel Sessions with Worktrees

1. What Is a Worktree?

A Git worktree is a separate working directory connected to the same repository history. Each worktree has its own files and branch, while the repository history and remote remain shared.

2. Why Do We Need Worktrees?

Imagine Claude Session A is building authentication while Session B is fixing a login bug. If both use the same checkout, their edits can interfere. With worktrees, each session gets an isolated checkout.

3. Start Claude in a Worktree

Use the --worktree or -w option:

claude --worktree feature-auth

By default, Claude Code creates the worktree under .claude/worktrees/<name>/ and uses a branch named worktree-<name>.

Another parallel session

claude --worktree bugfix-123

Let Claude choose the name

claude --worktree

4. Add Worktrees to .gitignore

Add the default worktree directory to your project's .gitignore:

.claude/worktrees/

This prevents worktree contents from appearing as untracked files in the main checkout.

5. Set Up the Environment

A worktree is a fresh checkout, so initialize the development environment there.

• Install project dependencies.
• Create virtual environments if needed.
• Run normal project setup.
• Copy selected local configuration files when required.

6. Copy Git-Ignored Files with .worktreeinclude

Git-ignored files such as .env are not normally present in a fresh worktree. Create .worktreeinclude in the project root:

.env
.env.local
config/secrets.json

Only files that are both matched and Git-ignored are copied; tracked files are not duplicated.

7. Ask Claude to Create a Worktree

During a session you can ask Claude to “work in a worktree”. Claude Code can create one with the EnterWorktree tool. It can also switch to another worktree under .claude/worktrees/.

8. Cleaning Up Worktrees

When an interactive worktree session ends, Claude checks whether removing it would delete work.

Manual cleanup

git worktree remove ../project-feature-a

If it is locked:

git worktree unlock ../project-feature-a

9. Resume a Worktree Session

When a session is resumed, Claude Code can return it to its worktree after verifying that the worktree is still a separate checkout. This also applies to --continue, --resume, and supported Agent SDK resumes.

10. How Claude Code Enforces Isolation

Claude Code actively protects the main checkout while a session is isolated in a worktree.

• File edits: edits targeting the main checkout are blocked.
• Command directory: commands resolving to the main checkout can be blocked.
• Git redirects: attempts to redirect Git operations into the main checkout are blocked.
• Unclear command shapes: commands that cannot be safely verified may be blocked.

11. Worktrees + Subagents

Subagents can receive their own temporary worktrees so parallel edits do not conflict.

Use worktrees for your agents.

A custom subagent can request isolation with isolation: worktree:

---
name: refactorer
description: Applies mechanical refactors across many files
isolation: worktree
---

Apply the requested refactor across every affected file,
then run the tests and report the results.

12. Subagent Worktree Cleanup

Temporary subagent worktrees can be removed automatically when a subagent finishes without changes. A worktree containing changes is retained so work is not lost. Claude Code also periodically cleans eligible old subagent and background-session worktrees.

13. Choose the Base Branch

{
  "worktree": {
    "baseRef": "head"
  }
}

14. Start from a Pull Request

You can create a worktree from a specific pull request:

claude --worktree "#1234"

Claude Code fetches the PR's change from origin and creates a dedicated worktree.

15. Reuse a Worktree Name

If the named worktree directory already exists, Claude Code can open it instead of creating another one. With the default fresh base, an eligible clean worktree can be reset to the repository's default branch. If it contains meaningful work or does not meet the reset conditions, its old tip is preserved.

16. Replace Worktree Creation with a Hook

A WorktreeCreate hook can replace Claude Code's default Git worktree creation logic. This is useful for custom locations or other version-control systems.

17. What Worktrees Share with the Main Checkout

A worktree has its own files and branch, but some resources remain shared:

• The repository's shared .git directory.
• Project-scope plugins installed for the repository.
• Applicable saved permission approvals.

18. Manage Worktrees Manually with Git

Create a new branch + worktree

git worktree add ../project-feature-a -b feature-a

Use an existing branch

git worktree add ../project-bugfix fix-issue-456

Start Claude

cd ../project-feature-a
claude

List worktrees

git worktree list

Remove one

git worktree remove ../project-feature-a

19. Non-Git Version Control

Worktree isolation uses Git by default. For SVN, Perforce, Mercurial, or another VCS, configure WorktreeCreate and WorktreeRemove hooks to implement creation and cleanup. When a custom hook replaces Git creation, .worktreeinclude is not processed automatically.

20. Troubleshooting

Claude cannot enter the worktree

This can happen if the directory was deleted or a custom creation hook returned an unexpected path.

Symlinked path

Claude Code refuses relevant symlinked .claude, .claude/worktrees, or worktree paths. Remove the problematic symlink and retry.

Git LFS pointer files

In the documented repository-local filter-driver case, a worktree can contain LFS pointer files. Run git lfs pull inside the worktree to retrieve actual files.

Claude refuses to use a worktree

Claude checks the worktree's Git identity. If it resolves to the main checkout or its Git metadata cannot be verified safely, Claude refuses to use it.

21. Worktrees vs. Other Parallel Approaches

22. Practical Example

Suppose your application needs authentication and also has an urgent production bug:

# Terminal 1
claude --worktree feature-auth

# Terminal 2
claude --worktree bugfix-login

23. Common Beginner Mistakes

1. Thinking a worktree is just an unrelated folder.
2. Forgetting to install dependencies in a fresh worktree.
3. Forgetting .claude/worktrees/ in .gitignore.
4. Assuming .env automatically appears.
5. Removing a worktree without checking for changes.
6. Using worktree.baseRef as an arbitrary branch selector.
7. Ignoring Claude's safety/refusal message.
8. Confusing file isolation with complete repository isolation.

24. Best-Practice Checklist

25. Interview / Revision Questions

1. What problem does a Git worktree solve?
2. What does claude --worktree feature-auth do?
3. Where are Claude-created worktrees stored by default?
4. Why add .claude/worktrees/ to .gitignore?
5. What is .worktreeinclude?
6. What is the difference between fresh and head?
7. How can a subagent use a worktree?
8. What does Claude Code protect during isolation?
9. How do you list and remove worktrees manually?
10. How are worktrees different from subagents and agent teams?

26. Practice — Try It Yourself

1. Open an existing Git project.
2. Run claude --worktree feature-test.
3. Ask Claude to add a small feature.
4. Open another terminal and run claude --worktree bugfix-test.
5. Make a different change there.
6. Run git worktree list.
7. Compare the two worktrees.
8. Commit useful changes and clean up temporary worktrees.

27. Quick Memory Map

28. Final Takeaway

claude --worktree feature-name

Once you understand worktrees, parallel Claude Code development becomes much safer: each session gets its own working area, while Git keeps the history connected.