Git Worktrees for AI Agents: Setup and Cleanup

A Git worktree is an additional working directory attached to an existing repository. It lets you keep one branch open while an AI coding agent works on another, without making a separate clone.

Each worktree has its own files, HEAD, and index. Repository history and branch references are shared. This makes worktrees useful for parallel editing, but they do not prevent merge conflicts or restrict what an agent is allowed to access.

For a complete two-agent example, see running Claude Code and Codex in parallel. This guide covers the Git operations and the environment details that are easy to miss.

Create a worktree from a known commit

Start in a repository with at least one commit. Check your current branch and working tree:

git status
git branch --show-current

Commit or set aside any changes you want to preserve before choosing your starting point. A new worktree will not inherit uncommitted edits.

To create a branch called agent/navigation in a sibling directory:

git worktree add -b agent/navigation ../app-navigation HEAD

HEAD makes the starting point explicit: the current commit in the directory where you run the command. To use a different base, replace it with the appropriate branch or commit. The branch and directory names must be available.

For a branch that already exists:

git worktree add ../app-hotfix hotfix

Git normally refuses to check out a branch that is already checked out in another worktree. Keep that protection and assign a different branch to each editing task. The Git worktree manual documents these commands and their options.

Check where each agent is working

List the worktrees from any directory in the repository:

git worktree list

In the new directory, confirm the branch before launching an agent:

cd ../app-navigation
git branch --show-current

For this example, the result should be agent/navigation. Start your CLI here, or open this directory in the interface you use to run agents.

Worktree separation is a workflow convention, not an access-control boundary. An agent with permission to write elsewhere can still change another directory. Keep the CLI’s permissions appropriate for the task.

Prepare the environment for each worktree

The source files are separate; the rest of the development environment needs attention too.

Resource	What to check
Dependencies	Install them in the new directory using the project’s documented command.
Ignored configuration	Create the local configuration the task needs; Git does not check out ignored files.
Dev-server ports	Give simultaneous servers different ports.
Databases and fixtures	Use separate test data when sessions may write or run migrations.
Background processes	Stop servers and watchers before removing their worktree.

For example, an npm project with a committed lockfile can install dependencies with npm ci. A Python project may need a new virtual environment. Follow the repository’s setup instructions rather than assuming a worktree is ready as soon as Git creates it.

Copying a production .env into every worktree is rarely the right default. Use development configuration and only the credentials required by that task.

Review a branch before merging

First review the changes inside the agent’s worktree and commit what you intend to keep. From your integration checkout, inspect those commits:

git log --oneline HEAD..agent/navigation
git diff HEAD...agent/navigation

These commands inspect committed work. Check git status inside the worktree as well, so you do not overlook uncommitted files.

When the branch is ready, merge it into the intended integration branch:

git merge --no-ff agent/navigation

Run the project’s checks after the merge. A worktree prevents ordinary edits in its directory from overwriting files in another directory. It cannot make two competing changes to the same function compatible. Git’s merge documentation explains how conflicts are reported and resolved.

Remove a finished worktree

Close the agent and any processes using the directory. After merging the work you want to keep, run these commands from another worktree:

git worktree remove ../app-navigation
git branch -d agent/navigation

Git’s normal removal command refuses an unclean worktree. If it refuses, inspect the remaining files before deciding what to do with them. The branch deletion command also protects work that Git does not consider merged.

If a directory was deleted outside Git, preview stale administrative entries before pruning:

git worktree prune --dry-run

Run git worktree prune when the preview matches the entries you intend to remove. For a worktree stored on a temporarily disconnected drive, use git worktree lock so it is not treated as abandoned.

Let Claude Code create the worktree

Claude Code supports a named worktree session:

claude --worktree navigation-fix

Run it from your repository. Claude manages creation and checks for remaining work when an interactive session exits. Read the keep/remove prompt carefully: a worktree may contain new commits as well as uncommitted edits. The exact cleanup behavior is documented in Anthropic’s worktree guide.

If you prefer to see the branches alongside your sessions, Pivio’s Claude Code GUI includes a Worktrees panel. It shows the agents attached to each worktree and controls for reviewing and merging work.

Frequently asked questions

Do worktrees prevent merge conflicts?

No. They separate working files while tasks are in progress. Conflicts can still arise when branches are merged, and tests are still needed after a clean merge.

Do worktrees share dependencies?

They do not automatically share directories such as node_modules or a Python virtual environment. Each worktree needs an appropriate setup, though package-manager caches may reduce repeated downloads.

Is a worktree the same as a clone?

No. A linked worktree shares the existing repository’s history and references. A separate clone has its own repository database and can be moved or managed independently. Use a worktree when you want another checkout of the same local repository.

Can I remove a worktree before merging its branch?

A clean worktree can be removed while its branch remains. Make sure the work you need is committed and that the branch is retained. Removing a directory and deleting a branch are separate operations.