Claude Code with git worktrees

The neat trick for running more than one Claude Code agent on the same project is not more terminals. It is git worktrees. A worktree gives each session its own checkout of the repository, on its own branch, in its own folder, so two agents can never fight over the same files.

What a worktree is

A normal clone has one working copy. git worktree lets one repository have several working copies at once, each on a different branch, sharing the same history and object store. No re-cloning, no duplicated .git, and a new worktree costs you a checkout rather than a full fetch.

Set one up per task

From inside your repo, create a worktree and branch per task:

git worktree add ../myapp-feature-a -b feature-a
git worktree add ../myapp-bugfix-b  -b bugfix-b

That makes two sibling folders, each on a fresh branch. Open a terminal in each and start Claude Code there:

cd ../myapp-feature-a && claude

Now one agent works on feature-a and another on bugfix-b, fully isolated. Merge each branch when it is ready, then remove the worktree:

git worktree remove ../myapp-feature-a

git worktree list shows what you currently have, and git worktree prune cleans up entries whose folder you deleted by hand.

Why it beats sharing one checkout

Point two agents at the same folder and they will eventually edit the same file in incompatible ways, or one will git checkout under the other. Worktrees remove the whole class of problem: separate folders, separate branches, separate working state. Each agent also gets clean, mergeable history instead of a tangle, and a failed experiment is a folder you delete rather than a branch you have to untangle.

One rule the tool enforces: the same branch cannot be checked out in two worktrees at once. If git worktree add refuses, you already have that branch open somewhere. Create a new branch with -b instead.

The untracked files problem

The one real friction with worktrees is everything git does not track. A fresh worktree has no .env, no node_modules, no build cache, so a naive git worktree add gives you a folder that does not run. Wrap the setup in a shell function and it stops being an issue:

wt() {
  local name="$1"
  local dir="../$(basename "$PWD")-$name"
  git worktree add "$dir" -b "$name" || return 1
  cp .env "$dir/" 2>/dev/null
  (cd "$dir" && npm install)
  cd "$dir" && claude
}

Now wt feature-a gives you a working folder with an agent already running in it. Adapt the middle two lines to your stack: copy whatever your project needs and skip the install if your package manager supports a shared store.

Watch out for anything that binds a fixed port. Two worktrees both running npm run dev on port 3000 will collide, so read the port from an environment variable and set a different one per worktree in its .env.

Picking up an existing branch

Worktrees are not only for new work. To review a colleague's pull request without disturbing whatever your main checkout is in the middle of:

git fetch origin
git worktree add ../myapp-review feature-x

When feature-x exists on exactly one remote and not locally, git creates the local branch and sets it to track, so you get a proper checkout rather than a detached head. You can then start an agent there to read the diff and run the tests while your own branch stays exactly as you left it. Delete the folder when you are done reviewing and nothing about your working state has changed.

Per-worktree settings

Because each worktree is a normal checkout, it reads the project's .claude/settings.json like any other, with the same permissions and hooks. You can also drop a .claude/settings.local.json in a specific worktree for a one-off tweak: wider permissions in a throwaway branch, a distinct notification sound per worktree, or a hook that only makes sense while you are on that task. It stays out of git, so it never leaks into the branch you merge.

Merge order matters more than isolation

Worktrees stop agents colliding while they work; they do not stop their branches colliding at merge time. Two sessions that both touch the same module will still produce conflicting diffs. Keep each task scoped to its own area of the codebase, merge the short branches first, and rebase the long-running one on top rather than letting it drift for days. The isolation buys you parallelism, not immunity.

The remaining problem: attention

Worktrees solve isolation. They do not solve attention: with three or four agents running across three or four folders, the hard part is still spotting which one is blocked on a permission and which just finished. Naming your terminals helps, and you can wire notifications (see running multiple Claude Code sessions), but the pings pile up and none of them tells you which folder they came from unless you scripted that yourself.

Blooby closes that last gap with a live mascot per session, so all your worktrees are visible at once in the corner of your screen: the one looking up needs you, the one celebrating just finished. Set up your worktrees, then stop babysitting them.