A practical guide to
git worktrees.

How much of this week did you spend scrolling while a single Claude chewed through one task? Five minutes here, ten minutes there. It adds up fast.

There's a lot of noise right now about “agent swarms” and “multi-agent orchestration.” The underlying idea is pretty mundane: instead of running one Claude, run a few on different problems at the same time.

The reason most people don't is that nothing makes it easy. One terminal, one folder, one Claude. Point two Claudes at the same folder and they'll stomp on each other's edits within a minute.

The fix is a git feature called a worktree. It predates AI agents by over a decade and is useful in plenty of situations that have nothing to do with them. Most of this guide covers worktrees on their own terms: what they are, the four commands you'll actually use, the gotchas. The last couple of sections are about running agents across them, and about Harness, a tool built for that specific case.

You know branches. A repo normally has one working directory (the folder you cd into), and switching branches rewrites the files on disk. That works until you want two branches open at once. Then it's stash, checkout, stash-pop, and trying to remember which stash was which.

git worktree solves this. A worktree is a second working copy of the same repo, checked out to a different branch, sharing the same .git directory. You can have as many as you want. Create one like this:

git worktree add ../myrepo-feature-x -b feature-x

Now ../myrepo-feature-x exists on disk on the feature-x branch, while your main clone stays on main. Both are real checkouts you can edit, build, and test independently. Commits and fetches in one show up in the other immediately because they share git objects.

The one rule is that the same branch can't be checked out in two worktrees at once.

Worktrees aren't an everyday tool. They pay off in specific situations where swapping branches in place is a hassle:

• A production hotfix lands while your feature branch is half-rebased. Open a second worktree on main, fix it, ship it, come back.
• A slow test suite or build is running on one branch. Spin up a worktree so you can keep coding on another while it finishes.
• You want to review a colleague's PR locally without blowing away your WIP. Check their branch out into its own worktree, poke around, delete it when you're done.
• You're maintaining a long-running release branch alongside main. Keep each one checked out permanently instead of swapping back and forth.
• You're running several Claude agents in parallel. Each one needs its own folder. This is the case the second half of this guide focuses on.

A typical day looks like this. One worktree for a quick UI fix, another for some backend work running in parallel, and cleanup at the end.

# Spin up a worktree for a UI bug
git worktree add ../myrepo-ui-fix -b fix/login-flash
cd ../myrepo-ui-fix
npm install
claude
# ...work on the fix, commit, push, open a PR as usual...

# Meanwhile, in another terminal tab, another worktree for API work
git worktree add ../myrepo-api -b fix/api-400s
cd ../myrepo-api
npm install
claude
# ...work in parallel, commit, push...

# Whenever you lose track of what's open
git worktree list

# Once the PRs are merged, clean up
git worktree remove ../myrepo-ui-fix
git worktree remove ../myrepo-api

You can also check out an existing branch instead of creating one, which is handy for reviewing a teammate's PR locally:

git worktree add ../myrepo-review origin/their-branch

If you delete a worktree folder manually instead of using git worktree remove, git holds on to a stale reference. git worktree prune cleans those up.

git help worktree has the rest, including lock, move, and repair. You'll rarely need them.

• The same branch can't be checked out in two worktrees at once. Git errors out clearly when you try.
• Gitignored files don't follow. Every new worktree starts without .env, without node_modules, without any local-only config. Copy or symlink what you need.
• Dependencies install per-worktree. Each one gets its own node_modules / venv / target, and the disk bill adds up fast. Delete worktrees you're done with.
• Some tools assume a single working directory. Most are fine, but watch out for IDE project state, docker-compose volumes, and anything that caches absolute paths.
• Your shell prompt probably won't tell you which worktree you're in. If you've got several, label your terminal tabs or put the directory name in your prompt.

Claude Code edits files on disk. Five Claudes sharing one working directory means half-written files, conflicting edits, and broken builds nobody can explain.

One worktree per task fixes that. Each session gets its own folder, and they can't see each other's in-progress edits. You kick off task A, kick off task B, walk away, come back, and review A while Claude is still working on B.

This is the change that makes running several Claudes at once actually feasible.

git worktree add ../myrepo-bug-123 -b bug-123
cd ../myrepo-bug-123
npm install
claude

Repeat in a new terminal for every task. This works up to about two tasks. After that, you lose track of which terminal is running which branch. You can't tell at a glance which Claudes are waiting for input. Reviewing diffs means git diff in another pane. PR status lives on github.com. Cleaning up orphan node_modules folders eats a Sunday afternoon.

The primitive is right. It just needs a frontend.

Everything up to this point works with plain git and a terminal multiplexer. If that's enough for you, you can stop reading. The rest is a pitch for a tool I built for when it isn't.

Harness is a macOS app that puts every worktree and every Claude session in a single window. It's opinionated around the specific workflow of running several agents at once, and it handles the papercuts that pile up past two or three parallel tasks.

1. One worktree per task. Keep each one scoped to a single unit of work: one bug, one feature, one refactor.
2. Start with two or three. Kick off a couple of Claudes with clear instructions and let them run.
3. Let the status dots drive you. When a dot turns yellow, that Claude needs you. Jump over, unblock it, move on.
4. Scan diffs in the side panel before telling Claude to push. It's easier to catch problems while the context is still in your head.
5. When Claude opens a PR, watch CI from the PR panel. Delete the worktree after merge so the disk doesn't fill up.

• Parallel works best when tasks don't overlap. If two Claudes end up editing the same files, the merge conflict will eat the time you saved.
• Keep one worktree on main. It's useful for reviewing PRs or trying things out without disturbing the agents you've got running.
• Delete worktrees when you're done with them. Each one has its own node_modules and build output, and they add up quickly.
• Fresh worktrees are fresh folders. Dependencies install from scratch every time. A small script that detects this and runs the install is worth writing.
• Let Claude run. The point is to not babysit. Give it enough context up front that you can walk away for ten minutes.