In partnership with
One year ago, I didn't know anything about Git worktrees except the name.
Today, they're my best friends.
What changed? AI tools.
Here's my current setup:
A
cwalias in myzshrc,alias cw='claude --worktree', spins up Claude Code inside a fresh worktreeI pass a branch name every time I remember:
cw nfdiop/feature-x. When I forget, I end up with folders calledlucky-bouncing-sedgewick, and hate myselfAny time I'm juggling more than one task in the same repo, I reach for
cw
If you've ever opened a PR and found changes that didn't belong, worktrees are the fix.
What are Git worktrees
Imagine you're deep in a branch. Uncommitted changes on disk. A dev server running in one terminal. A test watcher in another.
Now a teammate pings you. Can you pull down my PR and sanity-check it locally?
You have three painful options:
Stash everything, kill the processes, then
git checkouttheir branchCommit your half-done work, kill the processes, then
git checkout, except your changes aren't ready for any human to seeClone the whole repo into a different folder. Slow and cumbersome if the codebase is big
Git worktrees give you a fourth option.
A worktree is a second working directory tied to the same repo. Same .git under the hood, different files on disk. You can have main checked out in one folder and a feature branch checked out in another. Both live, both editable, no stashing.
git worktree add ../review-pr their-feature-branch
That's it.
Dissecting the command
Every worktree command reuses the same three parts:
git worktree add ../review-pr their-feature-branch
│ │ │
│ │ └── BRANCH: which branch to check out.
│ │ Must already exist.
│ │
│ └── where the new folder lives on disk.
│
└── COMMAND: adds a new linked working tree.
Git worktree operations
Four commands cover 95% of what you'll use.
# Create a worktree on an existing branch
git worktree add <worktree-path> <branch>
# Create a worktree with a brand-new branch
git worktree add -b <new-branch> <worktree-path>
# List all worktrees
git worktree list
# Remove a worktree (deletes the folder, cleans up refs)
git worktree remove <worktree-path>
# Clean up stale references for worktrees you deleted manually
git worktree prune
Memorize the first three. The rest you'll pick up as you go.
Why Git worktrees are all the rage now
One year ago, I worked on one feature at a time. Switching branches was rare.
Now I run 3+ Claude Code sessions at once, bouncing between branches every day.
The bottleneck moved. The question used to be how fast I could write code. Now it's how many branches my brain can track.
The first time it bit me, I opened a PR that was ready for review and saw changes that didn't belong to it. They were from a different feature I'd been jumping to. I had to send Claude the PR link and say this PR has unrelated changes. Clean it up.
Then I noticed the other branch, the one that was supposed to have those changes, didn't have them either. Two fixes, not one.
The worst part? Five minutes earlier I'd been clicking through a UI thinking I was testing the new behavior. The branch I was on didn't have the new behavior. I was testing nothing. I figured it out by glancing at the branch name in my terminal 🙈.
Worktrees fix this because each branch lives in its own physical folder. The folder name is the branch. You can't be on the wrong one.
Agents don't collide with each other. You collide with yourself. They let you parallelize your attention beyond what your brain can hold.
If you're running agents without worktrees, you've probably already shipped a wrong-branch PR. You just haven't noticed yet.
Gotchas
A few things burned me early. They'll burn you too.
1. Same branch, two worktrees → Git refuses.
You can't check out the same branch in two places. Git blocks you. Makes sense once you think about it. The branch's HEAD can only point at one checkout. Fix: use a new branch per worktree.
This one happens to me often.
2. Worktrees don't show up on GitHub.
A worktree is a local thing. It's not a remote branch. If you want collaborators to see the code, you still git push the branch like normal. The worktree itself is just a convenience on your laptop.
So get in the habit of committing code when you’re done with a feature so you don’t accidentally lose all your code by deleting the worktree.
3. npm run dev may not work out of the box.
Each worktree has its own node_modules, or needs one. Your dev server reads from the local install, so you'll run npm install inside the new worktree before anything boots. Annoying the first time. Worth it.
4. Sibling directory is the convention.
../review-pr next to the main repo is what most people do. git status stays clean, and your editor doesn't index the same files twice in search.
If you use claude --worktree, the default lives inside the repo and that's fine too. Just know your editor will see both copies.
How to make worktrees actually pleasant
A few tiny things made worktrees easier for me.
Alias to delete all worktrees and start from a clean state:
dw() {
git worktree list | tail -n +2 | awk '{print $1}' | xargs -I {} git worktree remove {} --force
git worktree prune
}
Claude Code worktree alias:
alias cw='claude --worktree'
Every Claude session starts in its own folder. No configuration, no thinking.
If you're on Codex: worktree support is still an open issue: https://github.com/openai/codex/issues/12862. Subscribe to it.
Scope editor search to one worktree.
When you open a parent folder containing multiple worktrees in VS Code, Cursor, Windsurf, etc., global search spans all of them. Confusing when the same file shows up six times.
Two fixes:
Specify
files to includeorfiles to excludein the search panelOr open the single worktree folder as the workspace root. Simpler.
Try this today
Worktrees aren't new. They've been in Git for years.
What's new is you. Running agents in parallel means juggling more branches than your brain was ever asked to track.
Go look at your last few PRs right now. Search for changes that don't belong. I bet you'll find one.
Then add the cw alias to your zshrc so it doesn't happen again:
alias cw='claude --worktree'Restart your shell. Spin up your next Claude session with cw your-handle/feature-x.
