What a git worktree actually is
A git worktree is a second checkout of the same repository sitting in a different directory on your machine. Each worktree has its own branch, its own working directory, and its own index. When you open Claude Code in each one, the two sessions are completely independent - they cannot see each other, cannot step on each other's files, and cannot cause conflicts mid-build.
The problem worktrees solve is that two Claude Code sessions in the same directory will eventually collide on the same file. Even if you try to keep them apart, one agent might update a shared utility, a type file, or a config while the other is mid-way through a change to the same thing. The resulting merge conflict arrives at the worst possible moment - mid-build, when context is deep.
Setting up a worktree in two minutes
From your main project directory, run: git worktree add ../project-auth auth. This does two things: it creates a new directory called project-auth one level up from your current project, and it checks out a branch called auth into that directory. The branch is created automatically if it does not exist.
- Navigate to your main project directory in the terminal.
- Run: git worktree add ../project-feature-name feature-branch-name (replace the names with something meaningful for your specific build).
- Open the Claude Code desktop app and open the new directory (../project-feature-name) as your project.
- That is your second session. The first session stays in the original directory on the original branch.
Running two sessions on the same project safely
With worktrees set up, the two Claude Code sessions are physically isolated. Each one reads and writes only to its own directory. The moment you are ready to start, give each session a clear, bounded scope so neither agent tries to extend into the other's territory.
- Session 1 scope: 'Build the authentication flow. Do not touch anything in the dashboard directory or the reporting utilities.'
- Session 2 scope: 'Build the data dashboard. The auth layer does not exist yet - build against a placeholder that returns a hardcoded user for now.'
- If a session needs something the other session is building, that is a dependency. Stop and sequence - the shared dependency must be finished and merged before the dependent work can continue.
Merging when both sessions are done
When both sessions have completed their work, merge both branches back to main as you normally would. Git does not know or care that the branches were built in parallel via worktrees - it just sees two branches with changes that need to be integrated.
Any conflict you encounter at merge time is a genuine conflict: the auth work made a decision that is incompatible with a decision the dashboard work made. That is a real conflict that needs a human decision - not the accidental collision from two sessions simultaneously editing the same line, which worktrees prevent entirely.
Once you have merged, clean up: git worktree remove ../project-auth. This removes the directory and de-registers the worktree from git. The branch still exists on its own - the remove command only removes the physical checkout.
When to use worktrees vs sequential sessions
Worktrees earn their setup cost when you have two independent builds that would otherwise make you wait. If a session takes 20 minutes and you have two of them, sequential means 40 minutes; parallel means 20 minutes plus a few minutes to merge.
- Use worktrees when: tasks are fully independent, each touches different files and directories, both have clear specs that will not need mid-stream reconciliation, and you have enough focus to manage two active sessions.
- Keep it sequential when: one task depends on the other's output, both modify a shared schema or config that is still being defined, or the build is exploratory enough that a decision in one session might change what the other needs to do.
- The fastest heuristic: could you hand these two tasks to different developers and they would not need to talk to each other to finish them? If yes, fork. If no, keep it sequential.
Common mistakes and how to avoid them
- Forking too early: starting two sessions before the shared contracts (API shape, schema, types) are settled. Agree on the shared contract before forking.
- Not naming worktrees clearly: two sessions called project-1 and project-2 create constant orientation confusion. Name them after the feature: project-auth-work, project-payments-work.
- Forgetting to clean up: old worktrees accumulate on disk. Run 'git worktree list' periodically and remove the ones that are done.
- Running three or more sessions at once before you have done it with two: coordination overhead grows fast. Start with two parallel sessions on a small build, then scale up.
Short, practical drops on skills, MCP, agents, prompts, and more. No spam, unsubscribe anytime.
Frequently asked questions
Does a git worktree copy my entire codebase onto disk?
No. A worktree is a lightweight checkout, not a copy. The git object database is shared between the main checkout and all worktrees - only the working files are checked out into the new directory. The overhead is just the size of the checked-out files, not the full repository history.
Can I have more than two worktrees running at once?
Yes, git supports any number of worktrees. The practical limit is your ability to manage multiple active Claude Code sessions simultaneously. Most people find two parallel sessions manageable. Three starts requiring real attention switching. Four or more is usually less efficient than a well-sequenced two-at-a-time approach.
Do I need to push the worktree branch before merging?
No. The worktree branch exists locally and can be merged to main locally without ever being pushed. Push when you want the branch on the remote for backup, code review, or collaboration. For a solo build that you merge straight to main, a local worktree branch is sufficient.
What if Claude Code in one worktree modifies a file that is also in the other worktree?
Git will not stop this from happening in real-time - it only surfaces the conflict when you try to merge. The prevention is clear session scope: each Claude Code session should have an explicit list of files and directories it is allowed to touch. If a shared utility file needs to change, stop both sessions, make the change on main, and restart both sessions from the updated state.
Last reviewed by David Iya on August 2, 2026
