git worktree you can't afford to miss in the AI era

Author: ssshooter Tags: Frontend, Backend, Interview

The git worktree command has been around since 2015 — older than any AI programming tool I've ever used. But it only truly showed its value once I started letting AI write code for me: multiple branches, multiple people (or multiple Agents) can work in parallel within the same repository history, each with its own independent working directory, never stepping on each other's toes.

Prologue: Your Agent is fighting you for the same working directory

You've probably seen this scene before.

You're modifying a feature on main, halfway through, when you suddenly remember there's an online bug to fix. You casually fire up an AI Agent (Cursor, Claude Code, WorkBuddy — any of them will do) and tell it to "go fix the login captcha expiration bug." It obediently switches to the fix branch right in your current directory, changes files, runs tests. By the time you come back to your senses, those half-finished uncommitted feature changes have already been stirred into its work.

An even more common scenario: you want two Agents working simultaneously — one refactoring an old module, the other adding tests for a new feature. But they're both in the same working directory; the moment the second one starts, it wipes out the first one's work. In the end, you can only queue them up, run them serially, and a single day stretches into three.

This really isn't your fault. It's the old assumption that "one repository has only one working directory" dragging you down.

What worktree actually is

Ordinary git checkout switches branches inside the same directory; at any moment you can only see the files of one branch.

git worktree does the opposite: it opens a separate directory for any branch, with multiple directories attached to the same .git history, each with its own file state.

~/code/
├── lumen/             # main working tree, branch main
│   └── .git/          # the sole git directory (object database lives here)
├── lumen-dashboard/   # linked working tree, branch feat/analytics-dashboard
└── lumen-login-fix/   # linked working tree, branch fix/login-captcha

Three directories share the same commit history, all connected to the same .git object database, but the files are each their own. You change Dashboard.tsx inside lumen-dashboard; Dashboard.tsx inside lumen stays untouched.

Usage is no different from normal checkout: change files, commit, push as usual. The difference is you never again have to repeatedly checkout + stash to "save your place."

Traditional branching vs worktree

In the past, if you wanted to do two things in parallel, the routine went like this:

git stash              # first, stuff your current work away
git checkout fix       # switch over to fix the bug
... fix done ...
git checkout feat      # switch back
git stash pop          # pull your work back out (pray for no conflicts)

The moment a production bug hits, your flow state shatters. When stashes pile up, you can't remember which blob belongs to which task, and committing code to the wrong branch becomes routine.

With worktree, you just open a new directory for the bug; the main directory stays exactly as it was:

# Attach an existing branch as a working tree
git worktree add ../lumen-login-fix fix/login-captcha

# Or do it in one step: create branch + open working tree
git worktree add -b feat/analytics-dashboard ../lumen-dashboard

The new directory appears alongside the main project, checked out to the branch you specified. After that, edit, commit, and push independently in each directory; the main working directory stays pristine.

One limitation to state upfront: the same branch cannot be attached to two worktrees at once; each worktree must check out a unique branch. This actually enforces a "one task = one branch = one directory" mapping, making it harder to get confused.

It only gets good in the AI era

The following points are written for you, who have already started using AI to write code.

Give each Agent its own room. The most straightforward play: open a working tree for each AI task, lock the Agent into that directory, and let it run.

git worktree add -b agent/dashboard ../lumen-dashboard
git worktree add -b agent/login-fix  ../lumen-login-fix

Agent A builds the dashboard inside lumen-dashboard/, Agent B fixes the login captcha inside lumen-login-fix/, and the main directory lumen/ stays on main. You can git diff to review both sides at any time, or hand-write some delicate work you don't want the Agent touching. The two Agents use the same Git history, but their filesystems don't interfere with each other. If A breaks Dashboard.tsx, it will never drag down B, let alone touch your main tree.

The main tree is always in a releasable state. Agents often spew a pile of intermediate artifacts, temp scripts, and debug logs when they run. If it runs in the main directory, your git status gets polluted, and you can't even tell "can this tree be released right now?" Once you lock it into a worktree, the main tree stays in the clean state you maintain by hand; whatever mess the Agent makes over there won't affect your ability to merge code, switch branches, or run CI at any moment.

Your IDE doesn't get interrupted. Many Agents will modify .vscode/, temporarily install dependencies, or even touch package.json. If it runs in the directory you're actively using, your editor frantically pops up "file changed" notifications, and npm processes in the terminal fight each other. worktree moves all of this to another directory; your IDE stays rock-solid and keeps doing what it was doing.

Real-world scenario: online login goes down, let the Agent fight the fire while you keep building the dashboard. The initial layout is just one main tree:

~/code/
└── lumen/           # main working tree, main

You're building a data dashboard inside lumen/ (not yet committed) when the alert group blows up: login captcha is broken, users can't get in. Open a fix working tree and toss the firefighting Agent into it:

cd ~/code/lumen
git worktree add -b fix/login-captcha ../lumen-login-fix

The layout becomes:

~/code/
├── lumen/             # main working tree, main (you keep building the dashboard)
└── lumen-login-fix/   # Agent fixes the login captcha here

Next: let the Agent locate, fix, and run tests inside lumen-login-fix/; you keep pushing the dashboard forward inside lumen/, completely uninterrupted; once the Agent finishes, you cd over, git diff to review, and when satisfied, go back to the main tree and git merge fix/login-captcha.

When a task gets interrupted, you no longer need stash to save your life — you just opened a new room.

Quick reference

See what working trees currently exist. Before deleting anything, first see what Git recognizes:

git worktree list

Output looks like:

/Users/you/code/lumen            66c16256 [main]
/Users/you/code/lumen-dashboard  0c8ba118 [feat/analytics-dashboard]
/Users/you/code/lumen-login-fix  a16e4be2 [fix/login-captcha]

At a glance you can see which branch is attached to which directory, saving you from reusing a branch already occupied by some worktree.

Merge a working tree back into the main branch. The merge logic is the same as ordinary Git, just with clearer context — each branch lives in its own directory:

# 1. Finish changes and commit inside the feature working tree
# 2. Switch back to the main working tree
cd ../lumen && git checkout main
# 3. Merge
git merge feat/analytics-dashboard
# 4. Resolve conflicts, push

Each worktree serves only one branch; it's nearly impossible to commit to the wrong branch, and a hotfix interrupting a feature won't lose your place.

Remove a working tree. Clean up when you're done:

git worktree remove ../lumen-dashboard

Only the working directory is deleted; the branch remains. The working tree must be clean (no uncommitted changes, no untracked files); force removal with --force. The main working tree cannot be removed. Before deleting, be sure to git status inside the corresponding working tree to confirm there are no uncommitted changes, or you'll easily lose the Agent's labor.

Prune orphaned metadata. If you impulsively rm -rf a working tree directory, Git still retains metadata under .git/worktrees/, and git worktree list will mark it missing. Clear out these zombie records:

git worktree prune

Only clears ones unused for a long time; add an expiration:

git worktree prune --expire 7.days.ago

To clean all zombies at once in a local environment: git worktree prune --expire now.

A few pitfalls when running Agents

• The same branch cannot be attached to two worktrees. Give each Agent its own branch, distinguish them by naming — for example, prefix everything with agent/.
• When launching an Agent, point the working directory correctly. Many Agents default to working in the current directory; opening the wrong room is the most common rollover point.
• Dependencies are not shared. worktrees are independent directories; node_modules, .venv do not follow by default. Either symlink them over, or make the Agent's first step installing dependencies — don't let it blindly run tests in an empty directory.
• Explicitly tell the Agent to only touch the current directory, and not to follow relative paths into sibling working trees or the main tree.
• After the Agent finishes, personally diff and review before merging. worktree only solves the isolation problem; whether AI-written code enters the mainline — the decision remains yours.

Closing

I used Git for years before discovering worktree. Before AI programming, it was just a small trick for occasionally running two features in parallel; after AI programming became widespread, it became the foundation for multi-Agent parallel development. Whoever gets comfortable with it first will be able to have several Agents working for them simultaneously, while the main branch stays clean, releasable, and reviewable at all times.

For simple sequential tasks, ordinary branch switching is enough. But the moment the thought "if only I could be in two places at once" crosses your mind — whether it's two Agents or an Agent plus yourself — worktree is the answer. Go open a room and lock the Agent inside.