← engineering logs / git-worktrees
developer workflow/

Git Worktrees — A Practical Workflow for Parallel LLM Sessions

How to run multiple agent tasks on one repo without them touching each other.

You already know what a worktree is: another checkout of the same repo, on its own branch, sharing one .git. This note is about using it properly, especially when LLM agents are editing your files.

One task, one worktree, one branch. Everything below follows from that.

1. Create a worktree

Always branch off an up-to-date base, not whatever your main checkout happens to have.

git fetch origin
git worktree add ../app-feat-auth -b feat/auth origin/main
  • -b feat/auth creates the branch
  • origin/main is the start point
  • ../app-feat-auth is the path, kept as a sibling of the repo

To check out an existing branch instead:

git worktree add ../app-hotfix hotfix/login

2. Set up the environment

A fresh worktree only has tracked files. Everything else needs to be recreated.

cd ../app-feat-auth
cp ../app/.env .env
npm install        # or bun install / pip install -r requirements.txt

Give each worktree its own port and database so they don't collide:

# .env in each worktree
PORT=3101
DATABASE_URL=postgres://localhost/app_feat_auth

3. Script it

You'll do this often, so make it one command. Example wt.sh in the main repo:

#!/usr/bin/env bash
set -euo pipefail

name="$1"                       # e.g. feat-auth
base="${2:-origin/main}"
dir="../$(basename "$PWD")-$name"

git fetch origin
git worktree add "$dir" -b "$name" "$base"

cp .env "$dir/.env"
cd "$dir" && npm install
echo "ready: $dir"
./wt.sh feat-auth

4. Run one agent per worktree

Open a separate terminal per directory and start the agent there.

cd ../app-feat-auth && <agent>
cd ../app-fix-upload && <agent>

Give each session a narrow task. Split work by area of the codebase so two agents aren't editing the same files.

5. Review before merging

Each task is a branch, so review it like one.

git -C ../app-feat-auth status
git -C ../app-feat-auth diff origin/main...HEAD
git -C ../app-feat-auth log --oneline origin/main..HEAD

Run tests inside the worktree, not in the main checkout:

cd ../app-feat-auth && npm test

6. Merge

From the main checkout:

git merge feat/auth
# or open a PR from the branch
git push -u origin feat/auth

If two worktrees touched overlapping files, resolve conflicts here. Merge the smaller change first.

7. Clean up

git worktree remove ../app-feat-auth
git branch -d feat/auth

remove refuses if there are uncommitted or untracked changes. Use --force only when you're sure you want to discard them.

If you deleted a directory manually:

git worktree prune

Useful commands

CommandWhat it does
git worktree listShow all worktrees, their paths and branches
git worktree add --detach <path> <ref>Check out a commit without a branch, for quick experiments
git worktree move <old> <new>Move a worktree directory
git worktree lock <path>Prevent pruning, useful for worktrees on removable drives
git worktree repairFix links after moving the main repo

Things that will bite you

  • •The same branch can't be checked out twice. Git blocks it.
  • •Untracked and ignored files aren't shared. .env, node_modules and build output are per worktree.
  • •Ports, databases and containers are shared with the host. Two worktrees running the same app collide unless you separate them.
  • •Stash and config are shared. git stash in one worktree is visible in all of them.
  • •Disk use adds up. Source is cheap, but each node_modules isn't.
  • •Review is the bottleneck. Three or four parallel agents is about the limit for reviewing carefully.

Closing

Worktrees don't make the agent better. They make running several of them safe, and they keep every mistake on a branch you can delete.

One repo, several isolated checkouts, each one disposable.

Related