You’re mid-refactor on a feature branch, files half-edited, tests failing on purpose while you work through them — and then someone pings you about a broken build on main that needs a fix in the next five minutes. You git stash, switch branches, fix the bug, switch back, git stash pop, and hope you remembered every step correctly. There is a better way, and it has been sitting in git since 2015.
git worktree lets you check out more than one branch of the same repository at the same time, each in its own separate folder on disk, all sharing one underlying .git history. Instead of stashing and switching, you cd into a different directory. Your original branch stays exactly as you left it — mid-refactor, tests still red — while you work on the hotfix somewhere else entirely.
The Problem Worktrees Solve
A normal git repository has one working directory and one HEAD — you can only be “on” one branch at a time. Every context switch (a code review, a hotfix, testing a colleague’s branch) forces you to either commit or stash whatever you’re mid-way through, switch, do the other thing, then switch back and hope you remember where you were.
Worktrees remove the single-directory constraint. The repository’s history — commits, objects, refs — lives in one place, but you can attach multiple working directories to it, each checked out to a different branch, each with its own uncommitted changes. Nothing about one worktree affects the file state in another.
Core Commands
Everything lives under git worktree:
# Create a new worktree with a new branch, checked out into ../myrepo-feature-x
git worktree add ../myrepo-feature-x -b feature-x
# Create a worktree for a branch that already exists
git worktree add ../myrepo-hotfix hotfix/login-bug
# List all worktrees attached to this repo
git worktree list
# Remove a worktree once you're done with it
git worktree remove ../myrepo-feature-x
# Clean up references to worktrees you deleted manually
git worktree prune
A few things worth knowing:
- Each worktree is a full checkout — its own files on disk — not a symlink or a shallow view.
- You cannot check the same branch out in two worktrees simultaneously; git will refuse, since two directories editing the same branch’s tip would conflict.
- Worktrees share the same object database, so creating one is fast — it’s not a second clone, and disk usage only grows by the size of the checked-out files, not the whole history again.
- Deleting a worktree’s folder directly (instead of
git worktree remove) leaves stale metadata behind;git worktree prunecleans that up.
When Worktrees Earn Their Keep
| Situation | Without worktrees | With worktrees |
|---|---|---|
| Urgent hotfix mid-feature | Stash, switch, fix, switch back, unstash | New worktree, fix, done — original branch untouched |
| Reviewing a teammate’s PR locally | Stash your work to check out their branch | Open their branch in a second folder |
| Running a long test suite on one branch while coding on another | Can’t — only one checkout | Run tests in worktree A, keep coding in worktree B |
| Running multiple AI agents on the same repo | They’d fight over the same files | Each agent gets its own worktree — zero collisions |
That last row is the one that matters most as AI coding agents become part of the daily workflow. An agent editing files is, from git’s point of view, indistinguishable from you editing files — and two agents (or an agent and you) editing the same working directory at the same time will absolutely step on each other: overwriting each other’s uncommitted changes, confusing each other’s test runs, producing a diff that’s a tangle of two unrelated changes.
Worktrees Are What Make Parallel Agents Safe
Once you’re running more than one AI coding agent at a time — one fixing a bug, another writing tests, a third exploring a refactor — isolation stops being a nice-to-have and becomes the only thing standing between “five agents working productively” and “five agents fighting over the same files.” Giving each agent its own worktree and branch means:
- No agent can overwrite another agent’s in-progress edits.
- No agent can accidentally commit on top of your own uncommitted work.
- Each agent’s diff is clean and attributable — you know exactly which changes came from which task.
- You can kill or discard any one agent’s worktree without touching the others.
This is precisely the model Agents is built around: every session in the sidebar checks out its own git worktree and branch automatically, so you can run several AI coding sessions against the same repo at once with no manual git worktree add bookkeeping and no risk of one session’s changes bleeding into another’s. Pair that with the right-side diff panel and you get the isolation of worktrees plus a place to actually review what each agent did before merging anything.
A Quick Worktree Habit for Solo Work
Even without any agents involved, a lightweight habit is worth adopting:
# Before starting anything urgent, spin up a scratch worktree
git worktree add ../scratch -b scratch/quick-fix
# Do the urgent thing, commit, push, open the PR
cd ../scratch && git commit -am "fix: urgent thing" && git push -u origin scratch/quick-fix
# Clean up when merged
cd .. && git worktree remove scratch
It removes the stash-switch-unstash dance entirely, and it composes naturally with running multiple agents once you’re ready to.
Common Worktree Mistakes to Avoid
- Trying to check out the same branch twice. Git will refuse with an error — create a new branch for the new worktree instead of reusing one that’s already checked out elsewhere.
- Deleting the folder by hand. Running
rm -rfon a worktree’s directory leaves stale entries in git’s metadata; always usegit worktree remove, or follow up a manual delete withgit worktree prune. - Forgetting worktrees exist and cloning the repo again instead. A second clone duplicates the entire object database on disk; a worktree shares it, so it’s dramatically cheaper in both time and space.
- Losing track of which folder is which. Give worktree directories descriptive names (
../repo-hotfix,../repo-feature-x) rather than generic ones, especially once you have several open for parallel agent sessions.
Worktrees vs. Cloning: When to Use Which
Worktrees and full clones solve overlapping but distinct problems. A second clone is right when you genuinely want a separate copy of history — for example, testing against a different remote. A worktree is right when you want a second working directory attached to the same history you already have locally, which is the far more common case for hotfixes, reviews, and parallel agent sessions. Worktrees are faster to create, use less disk space, and stay automatically in sync with the same set of remote-tracking branches — there’s no risk of the two copies drifting out of sync the way two independent clones can.
Getting Started
- Try
git worktree add ../scratch -b scratch/testin a repo you already have cloned, and get a feel for having two folders checked out at once. - Notice how your original branch’s working state is completely untouched while you work in the new folder.
- Once that clicks, apply the same idea to AI agents: give each one its own worktree instead of letting them share your main checkout.
- If you’d rather skip the manual
git worktreecommands, download Agents — every session gets a worktree and branch created for you, with a diff panel to review what came out of it.
Worktrees are one of those git features that quietly changes how you work once you start reaching for it — and it turns out to be exactly the primitive that makes running several AI agents at once feel safe instead of chaotic.