← Back to the summary

Git Worktrees Are the Isolation Layer AI Coding Agents Need

Recently, many friends like me have been using Codex and Claude Desktop to write code on both macOS and Windows simultaneously, and we've been baffled by something called worktree.

You clearly told the AI to modify the code, but refreshing the page shows no effect at all? Chances are you've unknowingly fallen into the worktree "trap."

This article, based on my real-world troubleshooting experience, will help you thoroughly understand what Git worktree is, why it has suddenly become popular in the AI programming era, and how exactly to use it.

1. Why Traditional Branch Switching Is No Longer Enough

Let's first recall our usual development workflow. In a regular Git repository, you can only be on one branch at a time within a single directory:

Do daily development on the main branch
Suddenly need to fix an urgent bug, so you have to git stash your code, switch to the hotfix branch
After fixing, switch back to main and restore your previous code

This approach works fine for small projects. But in the AI programming era, pain points emerge:

You want the AI to refactor an old module while simultaneously developing a new feature
Or let Codex and Claude work on different branches at the same time
Even have a main Agent run tasks in parallel with multiple sub-Agents

If you keep switching branches in the same directory, not only is it easy to mess up uncommitted code, but the AI's context will also get cross-contaminated, wasting precious token quotas.

Worktree was born to solve this problem.

2. Understanding Worktree in One Sentence

Worktree = Multiple "working directories" from the same Git repository, doing different tasks simultaneously.

Git allows one repository to be associated with multiple working directories. This means you can place different branches of the same repository into different folders.

For example, if you have a main project my-project and now want to develop a login feature and fix a bug simultaneously, your directory structure with worktree would look like this:

my-project (main working tree): stays on the main branch
my-project/login (linked working tree): checks out the feature-login branch
my-project/hotfix (linked working tree): checks out the hotfix branch

They look like three independent project directories, but underneath they share the same Git repository data (commit history, object database, etc.).

3. Core Advantages of Worktree

Compared to cloning multiple repositories or frequently switching branches, worktree has three major benefits:

No more frequent branch switching

No more stash this and stash that. Want to switch branches? Just change folders. Each directory independently has its own HEAD, staging area, and working directory.
Run multiple versions simultaneously

For example, you can run npm run dev in the main directory to debug the main branch, while running a service on another port in a worktree directory to test a new feature, with no interference between the two.
Perfectly suited for AI programming tools

This is the most critical point! Tools like Claude Code can achieve perfect task isolation using worktree:
- Each AI session gets its own exclusive worktree
- If the AI messes up, just delete the worktree; the main directory code remains untouched
- If the changes are good, merge them back in — safe and efficient

4. Hands-On Guide: From Creation to Cleanup

Don't be intimidated by the concept; the actual operation is very simple.

1. View existing worktrees

git worktree list

This lists all working trees and their statuses for the current repository.

2. Create a new worktree

Based on an existing branch:

git worktree add ../my-project-login feature/login

This creates a my-project-login folder in the parent directory and checks out the feature/login branch.

Create a brand new branch:

git worktree add -b feature/payments ../payments main

Creates a feature/payments branch based on main and checks it out in the new ../payments directory.

Create a temporary experiment directory (not associated with a branch):

git worktree add -d ../debug-dir

This creates a "detached HEAD" working tree at the current commit, perfect for temporary testing.

3. Delete a worktree

Remember to clean up after use!

git worktree remove ../my-project-login

If you've already manually deleted the directory, use this command to clean up residual metadata records:

git worktree prune

5. Worktree Pitfall Avoidance Guide for AI Tools

Back to my initial confusion: why didn't code changes take effect in Claude Desktop?

Because the Claude Code desktop version automatically creates a worktree for each new session by default! And it usually places the worktree in the .claude/worktrees/ folder under the current project root directory.

If you don't notice this, start the service in the main directory, but let the AI modify code in the worktree directory, then refreshing the page ten thousand times won't show any changes.

Advanced Tips:

For simplicity: For simple modifications, just turn off the worktree option and work directly in the main directory.
For isolation: Let the AI mess around freely in the worktree, and merge back when the changes are good.
Configuration copying: A worktree is a fresh checkout, so ignored files like .env won't be automatically carried over. You can create a .worktreeinclude file in the project root directory to tell Claude which configuration files to automatically copy over.
Pollution prevention: Remember to add .claude/worktrees/ to your .gitignore to prevent it from appearing in the main repository's untracked file list.

6. Summary

Simple projects: Modify directly in the main directory; don't burden yourself unnecessarily.
Complex projects / AI parallelism: Definitely use worktree for isolation — one task per directory, no interference.
Core taboo: The same branch cannot be used by two worktrees simultaneously; Git will refuse to create it to avoid confusion.

Once you understand worktree, you can not only avoid the basic mistake of "code changes not taking effect," but also more efficiently orchestrate multiple agents working in parallel in the AI programming era. Give it a try in your next project!