You are refactoring your project's API router while fixing a critical login bug. You start Claude Code in your repo, ask it to restructure the route handlers, and while it works you open a second terminal to start another Claude session for the bug fix. Both sessions edit src/routes/auth.ts. The bug fix session adds a null check on line 47. The refactoring session rewrites lines 30-60 entirely. When you come back, one session's changes have silently overwritten the other's. The bug fix is gone.
This is the parallel editing problem. Subagents (Lesson 11) avoid it because they run read-only or touch separate files by convention. Agent Teams (Lesson 20) coordinate through shared task lists and messaging. But when you need two Claude sessions making independent, full-scope changes to the same codebase, you need something stronger: complete filesystem isolation where each session works on its own copy of the repository.
That is what worktrees provide. One flag -- --worktree -- creates a full copy of your repository in a separate directory with its own branch, its own files, and its own git index. Each session edits its own copy. When you are done, you merge changes back through standard git workflows -- branches, pull requests, code review. No overwrites, no conflicts during work, no lost changes.
When you run claude --worktree feature-auth, Claude Code does three things:
Your original repository is untouched. The worktree is a complete, independent working copy -- you can edit any file, run tests, install packages, all without affecting your main directory.
You can name your worktree explicitly or let Claude generate a name:
Named worktrees are easier to find later. Use descriptive names that match what you are working on -- feature-auth, bugfix-payment-null, refactor-db-layer.
All worktrees are created inside your repository:
Add .claude/worktrees/ to your .gitignore to prevent worktree contents from appearing as untracked files in your main repository.
Claude starts in .claude/worktrees/feature-auth/ on branch worktree-feature-auth. You can verify this inside the session:
Output:
Work normally inside the worktree session. Edit files, run tests, ask Claude to implement features. All changes happen in the worktree directory. Your main repository directory remains untouched.
Commit your work as you go:
These commits exist only on the worktree-feature-auth branch, which only exists locally. Nobody else can see them yet.
When your work is ready, push the branch and create a pull request:
Claude pushes worktree-feature-auth to the remote and opens a PR. Your team reviews the changes through the normal PR process -- code review, CI checks, approval. This is the same workflow you use for any feature branch.
When you exit the Claude session (type /exit or press Ctrl+C), Claude checks the state of the worktree:
If you choose keep, the directory and branch remain. You can return later with cd .claude/worktrees/feature-auth && claude or start a new worktree session.
If you choose remove, Claude deletes the worktree directory and the local branch. This is destructive -- any commits that were not pushed to the remote are permanently lost (recoverable only via git reflog within 30 days, and only if you know the commit hash).
This catches most people the first time. When you run claude --worktree feature-auth, the new branch is created from the default remote branch (typically origin/main), not from whatever branch you are currently on.
If you are on branch experiment-v2 with 50 commits of work and you create a worktree, the worktree starts from origin/main -- your 50 commits are not there.
Why this design? It prevents cascading dependencies. If worktrees branched from your current branch, and that branch had bugs, every worktree would inherit those bugs. Starting from the latest remote main gives each worktree a clean, stable foundation.
If you need to branch from a specific commit or branch, use manual git worktree creation instead:
Use --worktree when you want fast, disposable isolation for a focused task. Use manual worktrees when you need to control the base branch, place the worktree outside the repo, or work with an existing branch.
In Lesson 11, subagents ran inside the same directory as the parent session. This works when subagents touch different files, but fails when two subagents need to edit overlapping files. Adding isolation: worktree to a subagent definition gives each subagent its own complete copy of the repository.
Create a custom subagent at .claude/agents/isolated-reviewer.md:
When Claude spawns this subagent, it creates a temporary worktree, runs the subagent inside it, and automatically removes the worktree when the subagent finishes -- if no changes remain.
You can also ask Claude directly without a custom agent definition:
Agent Teams coordinate multiple Claude instances through shared task lists and messaging. Worktrees solve a different problem: filesystem isolation. You can combine them:
The decision follows the same pattern from Lesson 20: do agents need to talk to each other (teams), do agents need filesystem isolation (worktrees), or both?
While tmux is primarily used for Agent Teams (--teammate-mode tmux), you can also use it to manage multiple worktree sessions side by side. This is a manual workflow, not a built-in feature:
Now you can watch both sessions work simultaneously, switching between panes with Ctrl+B then arrow keys. Each session has its own isolated copy of the repository. Neither can interfere with the other.
If Claude crashes or your terminal closes unexpectedly, the worktree directory remains but no session is using it. To find and clean up orphaned worktrees:
If the worktree has uncommitted changes, git refuses to remove it. Use --force only if you are certain you do not need those changes:
When you exit a worktree session and choose "remove," Claude deletes the worktree directory and the local branch. If you committed work but never pushed it, those commits are gone from the branch.
Recovery: Within 30 days, git retains commit objects in the reflog. If you know the commit hash (check git reflog), you can recover:
Prevention: Always push your branch before removing a worktree. The PR workflow (Step 3 above) handles this naturally.
You are on branch feature-v2 and create a worktree expecting it to include your feature-v2 changes. The worktree starts from origin/main instead. See "The Base Branch Gotcha" above for the explanation and manual worktree creation as the workaround.
A worktree is a fresh directory copy. It does not share node_modules/, virtual environments, or build artifacts with your main directory. After creating a worktree, you may need to install dependencies:
For projects with long installation times, consider using tools that support shared caches (like pnpm for Node.js or shared pip caches for Python).
Lesson 23 introduces Remote Control -- controlling your local Claude Code session from any device. Where worktrees isolate your work across directories, Remote Control lets you monitor and interact with that work from your phone, tablet, or any browser while your machine does the processing.
Exercise 1: Create Your First Worktree
In your terminal (not inside Claude), run:
Once the session starts, paste this prompt:
When done, type /exit and observe the cleanup prompt. Choose "remove" since this was practice.
What you're learning: The fundamental isolation model -- a worktree is a complete, independent copy of your repository where changes do not affect the original directory.
Exercise 2: Verify File Isolation Between Two Worktrees
Open two terminal windows side by side. In terminal 1:
Paste this prompt:
In terminal 2:
Paste this prompt:
What you're learning: Each worktree is truly isolated from every other worktree. Files created in one do not appear in another, making parallel work safe.
Exercise 3: Full PR Workflow from a Worktree
In your terminal:
Paste this prompt:
After the PR is created, type /exit and choose "remove." Then verify in your browser that the PR still exists on GitHub even though the local worktree is gone.
What you're learning: The complete worktree lifecycle -- create, work, push, PR, cleanup. Once changes are pushed to the remote, the local worktree is safely disposable.
Exercise 4: Configure a Custom Subagent with Worktree Isolation
Start a normal Claude session (no worktree needed):
Paste this prompt:
What you're learning: How isolation: worktree gives each subagent its own copy of the repository, preventing file conflicts when multiple agents work in parallel.
Exercise 5: Simulate and Recover an Orphaned Worktree
In your terminal:
Paste this prompt:
Now force-quit the session with Ctrl+C (skip the cleanup prompt). Then in a new terminal, run these commands yourself:
What you're learning: How to diagnose and recover from orphaned worktrees -- a common situation when sessions crash or terminals close unexpectedly. The unpushed commit still exists in git reflog for 30 days, but the branch and worktree directory are gone after removal.