I’m writing a book about claude code. in the parallelization chapter, I went deep into how to run multiple agent instances on the same repository without them stepping on each other’s toes. and I fell into a rabbit hole called git worktree.
the funniest part? the feature has existed since 2015. it was sitting there, quietly, waiting for us to have the right problem.
what git worktree is
worktree lets you create multiple working directories linked to the same repository. each directory sits on a different branch, but they all share the same .git.
in practice:
git worktree add ../my-repo-fix hotfix/loginthis creates a my-repo-fix folder next to your original repo, already on the hotfix/login branch. you edit, commit, push — all independent. when you’re done:
git worktree remove ../my-repo-fixno stash. no clone. no duplicating anything.
why they built it
the original use cases were legit:
hotfix without interrupting what you’re doing. imagine you’re in the middle of a heavy refactor, unstaged changes everywhere, and a critical production bug shows up. before worktree, your options were git stash (and pray you remember to pop it later) or cloning the whole repo. with worktree, you open another directory, do the fix, and come back to your work like nothing happened.
pr review with real context. instead of constantly checking out between branches and losing your editor’s state, you open the pr in a separate worktree. run the tests, navigate the code, close it, and your main branch stays intact.
parallel builds. local ci, performance comparisons between branches, running the test suite of one branch while developing on another.
why almost nobody used it
with all due respect to the cases above: git stash and git clone solved them. not gracefully, but they solved them.
most devs’ workflow is linear. you’re on a branch, you finish, you open a pr, you move to the next. the “I need two branches at the same time” scenario showed up, what, once a month? and when it did, a stash solved it in 5 seconds.
clone duplicated the whole .git and wasted space, but for a 50mb repo? nobody felt it. disk is cheap and most projects didn’t come close to being big enough for that to hurt.
worktree was the elegant answer to a question very few people were asking.
then came the coding agents
now picture this scenario: you want three claude code instances working in parallel on the same repository. one writing tests for an api, another refactoring the auth module, another updating the documentation.
if all three operate in the same directory, it’s chaos. one changes a file the other is reading. state conflicts everywhere. the agent has no idea another agent touched package.json two seconds ago.
cloning the repo three times on a small project is imperceptible. but think about a real monorepo — 1gb, 2gb of history. three clones is 3gb to 6gb of .git duplicated on your machine. five agents in parallel and you’re torching disk and clone time copying data that already exists right next door.
worktree shares the .git. it doesn’t matter if you create three or ten worktrees: the repository history exists exactly once. each worktree only adds the working directory files for that branch. in a large monorepo, the difference between clone and worktree isn’t convenience — it’s viability.
instead of multiplying the repo’s weight, worktree handles this surgically:
git worktree add ../repo-tests feat/api-tests
git worktree add ../repo-auth refactor/auth
git worktree add ../repo-docs update/docsthree directories. three branches. a single .git. each agent in its own corner, isolated, not interfering with the others. when each one finishes, you merge as usual.
the feature that was “nice but skippable” for a solo dev became essential infrastructure for whoever is orchestrating agents.
how claude code uses it
claude code has native worktree support. when you want to parallelize tasks, the flow is:
claude --worktreeit creates a worktree automatically, does the work on the isolated branch, and you decide what to do with the result. no manual setup, no collision risk.
and here’s the detail that ties it all together: each worktree can have its own CLAUDE.md. that means you can give each agent specific context depending on the task.
the worktree writing tests? its CLAUDE.md can say “use vitest, follow the test factory pattern already in the project, never mock the database.” the one refactoring auth? “keep compatibility with the public api, don’t change function signatures without a deprecation flag.”
each agent gets the context it needs, operates in its isolated space, and delivers a clean branch for review. it’s beautiful to watch in action.
the lesson I’m taking from this
we tend to evaluate tools by today’s problem. worktree in 2015 solved a minor inconvenience. worktree in 2026 solves a structural problem in how we work with ai.
nobody on the git team thought “one day people will run five ai agents on the same repo and need working directory isolation.” they thought about hotfixes and parallel builds. but the abstraction was good enough to survive an entire paradigm shift.
it reminds me it’s worth paying attention to the “obscure” features in the tools we already use. sometimes the solution to tomorrow’s problem is already installed on your machine — the problem just hasn’t shown up yet.
I’m always on linkedin and github. if you want to talk about agents, git, or anything in this universe, hit me up.