Git Worktrees on Peter Fulop

Claude Code now has built-in Git worktree support

Sat, 21 Feb 2026 00:00:00 +0000

Last week I wrote about how I develop multiple features at once with AI agents and git worktrees. The whole thing was about setting up a hub-and-spoke model where each feature gets its own directory and branch, letting you fire up multiple agents in parallel without them stepping on each other’s files. It worked well, but it involved a fair bit of manual ceremony — bare clones, config flags, naming conventions, cleanup.

Then Boris Cherny, the creator of Claude Code at Anthropic, announced that they’re shipping built-in git worktree support directly in the CLI. The Claude Desktop app has had a worktree checkbox for a while, but bringing this to the command line is what makes it really interesting for those of us who live in the terminal.

As of this release, worktree isolation is now a first-class CLI feature.

One flag instead of a whole setup ritual

In my previous article, getting worktrees going meant cloning as a bare repo, configuring core.bare and core.worktree, initializing a main worktree, then creating feature worktrees one by one. Not difficult, but definitely something you had to learn once and then remember every time.

With Claude Code’s built-in support, it’s one flag:

1

claude --worktree feature-auth

Claude creates a worktree (by default under something like .claude/worktrees/feature-auth/), checks out a dedicated branch (e.g. worktree-feature-auth) based on your default remote branch, and drops you into an isolated session. Your main working directory stays exactly as it was.

Under the hood, this appears to map closely to git worktree add combined with session metadata that Claude manages separately. The branch, filesystem isolation, and Git history are still standard Git mechanics — Claude just automates the ceremony around them.

If you don’t care about naming, just let Claude pick one for you:

1

claude --worktree

You’ll get something like bright-running-fox — random, but it keeps the sessions distinct. The short flag works too, so claude -w is all you need when you just want quick isolation.

You can also skip the command line entirely and ask Claude mid-session to “work in a worktree” or “start a worktree,” and it will create one on the fly.

Running multiple sessions in parallel

The real value here is the same as what I described in my previous post — running several agents at once, each on its own task. The difference is how little setup is involved now.

Open a few terminal tabs and spin up separate sessions:

1
2
3
4
5
6
7
8


# Terminal 1 — auth refactor
claude --worktree feature-auth

# Terminal 2 — new API endpoint
claude --worktree new-api-endpoint

# Terminal 3 — test coverage
claude --worktree add-tests

Each session gets its own copy of the codebase on its own branch. They share the same Git history and remote, but the files on disk are separate.

Cleanup that reduces friction

In its current implementation, Claude Code handles much of this automatically. When you exit a worktree session, it checks whether there are changes in that workspace. If the worktree is clean, it may remove the worktree and its associated branch. If there are changes, it prompts you to decide whether to keep or remove it.

One thing worth doing: add .claude/worktrees/ to your .gitignore:

1

echo ".claude/worktrees/" >> .gitignore

Subagents and isolation

From early demos and testing, subagents can also take advantage of worktree isolation. This is still evolving, but it enables stronger parallelism for large refactors.

What this does not solve

Worktrees eliminate file-level collisions. They do not eliminate integration complexity. You still need reviews, rebases, and careful merging.

Pushing to remote. Claude creates the worktree and branch locally, but it does not push to the remote or open a pull request for you. Once work in a worktree session is done, you still need to push the branch yourself and create a PR. This is easy to forget when you have been working across multiple worktrees at once.

1

git push -u origin worktree-feature-auth

Full cleanup after merging. The session-exit prompt handles the simple case, but once you have pushed a branch, merged the PR, and no longer need the worktree, there are a few manual steps left:

1
2
3
4
5
6
7
8


# Remove the worktree directory
git worktree remove .claude/worktrees/feature-auth

# Delete the local branch
git branch -d worktree-feature-auth

# Prune stale worktree references (optional, but tidy)
git worktree prune

None of this is difficult, but it is the kind of housekeeping that accumulates if you spin up worktrees frequently and forget to clean up after merging.

The friction keeps dropping

If you read my previous post and thought this sounded useful but complex, this lowers the barrier:

1

claude --worktree

How I develop multiple features at once with AI agents and git worktrees

Sun, 15 Feb 2026 00:00:00 +0000

I’ve been running local coding agents like Claude Code for a while now, and one workflow change I’ve made lately isn’t about prompting or model selection. It’s git worktree. Most engineers I talk to haven’t even heard of it, and I didn’t use it myself until a few months ago.

I often have several independent features in flight on the same project at once — say a new feature, adding a new API endpoint, and creating test suites. All on separate branches. The old way of working? Check out a branch, start coding, get pulled into something else, stash everything or make some half-baked commit you’ll forget about, switch branches, lose your train of thought. You should be familiar with this.

I use a clean hub + spokes setup (one central repo, multiple worktrees): one folder is the “hub” (the bare repo and the main worktree), and each feature gets its own “spoke” worktree in a subfolder. Everything shares the same Git history and refs, but each spoke has its own working copy. More on the exact steps below.

Stashing works fine when it’s just you. But when you have an AI agent mid-way through a refactor on your working tree and you need to switch branches — that’s where things get messy.

What git worktree actually does

It’s been part of Git for years (official docs). The idea is simple: you can have the same repo checked out to multiple directories, each on a different branch, all at the same time. They share the same .git internals — history, refs, everything — but each directory has its own working tree. This means they aren’t fully sandboxed, but in practice they’re isolated enough for parallel development.

Hub + spokes setup

Do this once per project, in the folder you want to be the hub (e.g. ~/code/my-project).

1. Clone as a bare repo into this folder:

1

git clone --bare git@github.com:your-org/your-repo.git .git

2. Configure the bare repo to allow worktrees:

1
2


git config --local core.bare false
git config --local core.worktree .

3. Initialize the main worktree:

1

git worktree add main main

4. Create worktrees for features:

1
2
3


git worktree add -b feature-auth auth-wt main
git worktree add -b feature-new-api new-api-wt main
git worktree add -b chore-add-tests tests-wt main

Each git worktree add -b <branch> <path> main creates a new directory, checks out a new branch based on main, and puts the working copy there. You cd into that directory and you’re on that branch. Your main worktree stays exactly as you left it — dirty files, staged changes, all untouched.

I keep feature worktrees as sibling folders with a -wt suffix (auth-wt, new-api-wt, tests-wt). Nothing fancy, just consistent enough that I don’t lose track.

Where it gets interesting: running agents in parallel

So instead of having one agent work on one branch while I sit and wait, I set up a worktree per feature and fire up an agent in each:

1
2
3
4


~/code/my-project/main/ # my main checkout — quick fixes, reading code
~/code/my-project/auth-wt/ # Agent 1: auth refactor
~/code/my-project/new-api-wt/ # Agent 2: new endpoint or experiment
~/code/my-project/tests-wt/ # Agent 3: creating test suites

One terminal per worktree, one agent per terminal. They don’t know about each other, they can’t step on each other’s files, and I rotate between them checking output and steering as needed. My main directory stays clean the whole time.

Committing, pushing, and cleaning up

Do all your git operations — add, commit, push, status — inside the worktree folder, not in your main repo. Each worktree is a full working copy of its branch. If the agent’s changes live in ~/code/my-project/auth-wt/, that’s where you run git:

1
2
3
4


cd ~/code/my-project/auth-wt
git add .
git commit -m "Add auth refactor"
git push origin feature-auth

When the feature is done and pushed, clean up the worktree. Run git worktree remove from your main worktree (or the hub folder), pointing at the path you want to remove:

1
2


cd ~/code/my-project/main # your main checkout
git worktree remove ../auth-wt

That deletes the worktree folder. The branch and its commits stay in the repo and on the remote — you’ve already pushed them. You can merge the branch from your main checkout whenever you’re ready, or delete the branch after merging. The worktree was just a temporary workspace; removing it doesn’t touch the branch or its history.

Why I stuck with this workflow

The parallel speed-up is obvious. But there are a couple of things I didn’t expect.

In my experience, agents produce better results when they start from a clean state. No half-committed files from another branch, no untracked junk sitting around. The worktree gives each agent exactly what’s on that branch and nothing else. Sounds minor, but I noticed fewer confused outputs once I started doing this.

When an agent goes sideways — and they do — I just nuke that worktree (after pushing anything worth keeping) and start over. It doesn’t affect anything else. Compare that to untangling an agent’s bad changes from your only working copy while trying to remember what was yours and what wasn’t.

I’ve also started using this to compare approaches. Same branch point, two worktrees, two agents with different instructions. Diff the results, keep the one that’s better. Doing that without worktrees would be a pain involving branches, cherry-picks, and a lot of manual switching.

And one thing people miss: my main checkout stays on main through all of this. I’m never one absent-minded git push away from shipping a half-finished experiment.

Worktree habits that stuck

Name your worktree directories after the branch. When you’ve got four terminals open, you need to know which is which immediately.

Clean up when you’re done. git worktree list, find the ones you don’t need, git worktree remove them. Git won’t let you check out a branch that already has an active worktree elsewhere, and the error message it gives you isn’t great — so just stay on top of it.

1
2


git worktree list
git worktree remove ../auth-wt

Your editor won’t follow you — if you cd into a worktree from the terminal, VS Code (or whatever you use) stays on your original directory. Open the worktree folder explicitly when you want to work there.

Keep an eye on resource usage. Three agents running at once means three sets of API calls, three processes chewing through tokens. I check in every few minutes to make sure nobody’s going in circles.

Why I think this matters

In my setup, agents are getting good enough that the bottleneck isn’t just “can it do the task” anymore. It’s “how do I run several of them without everything colliding.” Git worktrees solve that at the filesystem level — no special tooling, no agent-specific setup, just Git giving each one its own workspace.

I started doing this to get more out of coding agents on my projects. Now it’s just how I work when I’m developing multiple things at once. If you’re already using coding agents day to day, it’s one of the highest-leverage workflow changes I’ve found.

1
2
3


git worktree add -b <branch> <path> main
git worktree list
git worktree remove <path>

Give it a shot next time you’ve got work happening on multiple branches.

Do agents already use worktrees?

Many local and cloud-based coding agents operate in isolated copies of a repository — sometimes through full clones, temporary sandboxes, or other workspace mechanisms. Conceptually, this solves a similar problem to Git worktrees: allowing parallel changes without interfering with the main working directory.

The advantage of setting up worktrees yourself is control. You can explicitly decide how to split the work and run different agents on different features in separate directories.

For example, you might prefer one agent for frontend layout tasks and another for broader architectural changes. Managing the worktrees yourself lets you choose the right tool for each task, rather than relying on a single agent’s workflow.