Use Worktrees. Your Agents Already Understand Them.


If you want to move faster, you eventually want more than one agent working on your project at the same time. One is building search while another fixes billing while you plan the next thing. That’s the whole promise of agentic coding, and the first time you try it with both agents in the same project folder, this happens:

claude · ~/Projects/my-app
>the search feature looks done. verify and wrap up
Search is implemented. Running the test suite to verify before I hand off.
Bash(npm test)
FAIL src/billing.test.ts (7 failed)
FAIL src/invoice.test.ts (3 failed)
Tests: 10 failed, 74 passed, 84 total
… +41 lines (ctrl+o to expand)
Ten failures in billing and invoicing. My change doesn't touch either. Did I break a shared type? Let me check what changed in billing.
Bash(git diff src/billing.ts)
@@ -41,7 +41,8 @@ export function totalFor(order: Order) {
- const rate = 0.2;
+ // WIP: switching invoices to the new tax model
+ const rate = resolveTaxRate(order); // TODO finish
These edits are not mine. Another agent is mid-refactor of the tax model in this same folder. The failures are its half-finished work, not my feature.
Untangling (12m 4s · esc to interrupt)
>wait, is another agent editing this folder?
? for shortcuts
Twelve minutes and a pile of tokens to discover a problem that isn’t one. Both agents were doing their jobs.

That’s the expensive way agents step on each other’s toes: not the obvious one, where two agents edit the same file and confuse each other, but the sneaky one, where a finished feature’s tests go red because of a colleague’s half-done work sitting in the same folder. Typecheck breaks the same way. The agent figures it out eventually. “Eventually” is the expensive part: it’s your tokens and your time.This assumes you have a test suite your agents run. If you don’t, that’s the thing to fix first. Agents without a fast feedback loop are agents guessing.

Git has had the fix built in since 2015. It’s called a worktree, and you don’t need to understand it deeply, because your agents already do. You just need to know why to ask for it.


A desk for every agent

A worktree is a second folder for the same repository. Same history, same remotes, zero copying. Each worktree sits on its own branch, so each agent gets its own files, its own test runs, its own typecheck. A desk for every agent, instead of six people sharing one keyboard. Watch what actually happens when you ask:

It starts with one sentence in the prompt box. You describe the feature and add the only vocabulary this post asks you to learn: use a worktree.
You press enter. The agent runs one command, and a sibling folder appears on disk. That folder is a full copy of the project, on its own branch.
A second task, a second desk. Each agent now has its own files, its own test runs, its own typecheck. Nothing they do can show up in each other's folder.
Three folders, one repository. Same history, same remotes, zero copying. When a branch lands, its folder is one command to remove.
1/4
claude · ~/Projects/my-app
>build the search feature. use a worktree
press enter to send
~/Projects
my-app/
main · you

When the work is done

Ending it is the same move as starting it: you ask. The branch is green, so you tell the agent “merge it back into main.” It merges, reruns the test suite on main to be sure, and removes the worktree:

The feature is finished and green on its own desk. Ending it is the same move as starting it: one sentence in the prompt box.
The agent merges the branch into main and reruns the suite there, because green on the worktree is a claim and green on main is the proof.
Then it removes the worktree. The folder disappears as easily as it appeared, typed, once again, by nobody.
1/3
claude · ~/Projects/my-app
>search is done. merge it back into main and clean up
press enter to send
~/Projects
my-app/
main · you
my-app-search/
feat/search · done, tests green

That’s the entire mechanic, and notice who typed the git commands: nobody. You say “use a worktree,” a desk appears; you say “merge it back,” the desk disappears. Claude Code, Codex, and the rest all know these commands, and some harnesses will even offer isolation on their own when you spawn parallel work. The knowledge you need is not how. It’s that you should ask.

What isolation buys you, concretely

Every agent’s test suite tests only its own work. Every typecheck failure belongs to the agent that sees it. No agent ever burns twenty minutes investigating a colleague’s half-finished refactor. And a branch that goes wrong is a folder you delete, not an archaeology project in the only copy of your code.

One agent per desk solves the collision problem and creates a smaller, nicer problem: with three or four desks running, somebody is merging all day. I gave that job to an agent too, but that’s a story for its own post.

If you found this helpful, share it:

Share on X