Git worktree explained: a practical guide for running AI agents in parallel

Short answer: git worktree lets one repository have several working directories at once, each on its own branch. They share the same history and objects, so creating one takes seconds and almost no disk space for git data. That makes worktrees the simplest way to give each AI coding agent its own isolated checkout.

What is a git worktree?

A normal clone has exactly one working directory: the files you see, plus one HEAD and one index (staging area). A worktree is an additional working directory attached to the same repository. Each worktree has its own HEAD, index and files, but all of them share one object database, one set of branches and tags, and one config.

In practice that means you can have main open in ~/code/app, a feature branch in ~/code/app-search and a bug fix in ~/code/app-fix-login, all at the same time, without stashing or switching branches.

Why worktrees matter more with AI coding agents

Claude Code, Codex, Gemini CLI and similar agents edit files directly. Two agents in the same directory overwrite each other’s changes and race for .git/index.lock. Separate clones work, but each one downloads the full history and drifts out of date. Worktrees sit in between: every agent gets its own directory and branch, while commits made in one are instantly visible to the others because the repository is shared.

The five commands you actually need

Every other subcommand and flag is in the git worktree cheat sheet.

Create a worktree on a new branch

git worktree add -b feat/search ../app-search main

This creates the directory ../app-search, creates feat/search from main, and checks it out there.

Create a worktree for an existing branch

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

List worktrees

git worktree list

Shows each path, the commit it’s on and its branch. It does not tell you whether that branch has been merged, pushed, or has uncommitted work. More on that below.

Remove a worktree

git worktree remove ../app-search

git refuses if the worktree has modified or untracked files. --force overrides that check and deletes those files for good. The branch itself is not deleted; remove it separately with git branch -d.

Clean up after a manually deleted folder

git worktree prune

If you deleted a worktree directory with rm -rf or Finder, git still keeps its bookkeeping in .git/worktrees/ and still considers the branch checked out. prune removes those stale entries.

Not sure whether you need a worktree or just another branch? See git worktree vs branch.

Gotchas worth knowing

One branch, one worktree. A branch can be checked out in only one worktree at a time. Trying to check it out elsewhere fails with an error naming the worktree that already uses it.
Ignored files don’t come along. A new worktree contains only tracked files. .env, node_modules and build output must be copied or reinstalled in every worktree.
Stashes are shared. git stash list shows the same stash list from every worktree, which makes it easy to pop someone else’s stash.
Dependencies and ports. Each worktree needs its own dependency install, and two dev servers can’t share a port.
They pile up. After a week of parallel agents you can easily have a dozen worktrees, some merged, some with unpushed commits, some with changes nobody committed.

Keeping track of many worktrees

The last gotcha is the one that costs work. git worktree list answers “where are they?”, not “which ones still matter?”. To know whether a worktree is safe to delete you have to check, in every one of them, for uncommitted changes, untracked files, unpushed commits, stashes and whether the branch landed in main, including through a squash merge. Our guide to cleaning up git worktrees safely walks through those checks by hand.

Orchard does those checks continuously for every worktree in every project on your Mac, shows which AI agent is working where, and explains each verdict, for example “PR #142 merged 3 days ago”.

FAQ

Do git worktrees use a lot of disk space?

No. Worktrees share one object database, so the history is stored once. Each worktree only adds its checked-out files, plus anything you install or build inside it, such as node_modules.

Can two worktrees use the same branch?

No. git allows a branch to be checked out in only one worktree at a time. Create a new branch for the second worktree, or use a detached HEAD if you only need to look at the code.

What is the difference between git worktree and git clone?

A clone is a separate repository with its own copy of the history. A worktree is an extra working directory of the same repository, so commits, branches and fetches are shared instantly and no history is duplicated.

Does deleting the worktree folder delete the branch?

No. The branch and its commits stay in the repository. Uncommitted and untracked files in that folder are gone, though. Run git worktree prune afterwards so git forgets the missing directory.