Git Worktree Branch Already Checked Out: Safe Fixes

A git worktree branch already checked out error means the branch is assigned to another worktree in the same repository. Git refuses to check out that branch in a second worktree by default. To access an agent’s work safely, find its worktree and inspect it there. If you need a separate directory, create a new branch at the agent branch’s commit or use a detached worktree. Release the original branch only after the agent has finished and you have checked its local changes.

Find the worktree that owns the branch

Run these commands from any worktree in the repository:

git worktree list
git branch -vv

git worktree list shows each worktree’s path, current commit, and checked-out branch. The -vv branch listing includes the path of a linked worktree beside its branch. Together, those outputs tell you whether the branch belongs to an active agent directory, the main worktree, or a path you no longer recognize.

For example, suppose the agent branch is agent/auth and the list associates it with ../agent-auth. Treat that path as the branch’s current home. First check whether the directory exists and whether its work is complete. A worktree path in Git’s records is not, by itself, evidence that an agent is still running.

If several agents use the same repository, give each a distinct branch name and directory. Git supports multiple worktrees so each can have its own checked-out branch; the error appears when you try to assign one branch to more than one worktree.

Inspect the agent’s work where it already lives

You do not need to check out the branch again to read its files. Open the directory from git worktree list, or run commands against it from your current directory. Git’s -C <path> option runs a command as though Git started in that path:

git -C ../agent-auth status --short
git -C ../agent-auth diff
git -C ../agent-auth diff --staged

Short status shows changed and untracked paths but omits ignored files by default. Check it before assuming the branch name contains all the agent’s work: a branch points to commits, while edits in the agent’s working tree and index may still be uncommitted.

Plain git diff shows unstaged changes, and git diff --staged shows staged changes. Neither command displays the contents of an untracked file; use the status output to identify those files and inspect them in the agent directory. If you want to compare committed branch tips from another worktree, you can run:

git diff main...agent/auth

Here main is an example base branch. The three-dot form compares agent/auth with its merge base with main. It is useful for reviewing the branch’s committed changes, but it does not include the agent worktree’s uncommitted edits.

Make a separate directory without claiming the branch

If you want a second checkout for inspection, create a detached worktree at the agent branch’s current commit:

git worktree add --detach ../review-auth agent/auth

This gives ../review-auth its own files and index without assigning agent/auth to it. It is a snapshot of the named commit when you run the command. Later agent commits will not automatically move its detached HEAD, and uncommitted files in ../agent-auth are not copied into it. Use the original agent directory when those edits matter.

A detached worktree is suitable for reading files or running an isolated check at that commit. If you make a commit there and want to keep it, give it a branch name before removing the worktree:

git -C ../review-auth switch -c review/auth

If you expect to make independent edits from the start, create a new branch instead:

git worktree add -b review/auth ../review-auth agent/auth

The new review/auth branch starts at the current agent/auth commit. It can then move independently as you commit, while the agent keeps its branch. Choose a fresh branch name and an unused directory. These commands work with committed history; they do not transfer the agent’s uncommitted changes.

The choice is practical: use the existing agent worktree to see all of its local edits, a detached worktree to inspect one commit, or a new branch when you intend to develop a separate version. If you are new to the relationship between worktrees and branches, Git worktrees explained covers the setup.

Reuse the exact branch after the agent is finished

Sometimes you need agent/auth itself in your current worktree—for example, because a task requires commits to keep advancing that branch. Coordinate the handoff first: stop work in the agent directory and examine its status. Save any changes you need before switching branches or removing the directory. A new checkout of the branch will not bring along uncommitted edits left in the agent worktree.

One way to free the branch while retaining the agent directory is to detach that directory at its current commit:

git -C ../agent-auth status --short
git -C ../agent-auth switch --detach
git switch agent/auth

Run the final command from the worktree where you want the branch. Git normally refuses to switch to a branch held by another worktree; detaching the former owner removes that branch assignment. Check the status of your destination worktree too. Git may refuse a switch when it would overwrite local changes there. Do not use --discard-changes as a shortcut unless discarding those changes is your intent.

If the agent directory is no longer needed, check for ignored files before removing it:

git -C ../agent-auth status --short --ignored

Inspect the ignored paths and save anything you need outside ../agent-auth. Git checks status before recursively deleting the worktree directory, so a clean worktree can still contain ignored files that removal will delete. Once the directory is safe to delete, run:

git worktree remove ../agent-auth
git switch agent/auth

git worktree remove requires a clean linked worktree in its normal mode. If it refuses because files are modified or untracked, inspect them rather than forcing removal. Also confirm you are removing the intended path: the command deletes that worktree’s directory. The branch remains a repository ref, available for checkout after the worktree releases it.

Handle a missing or moved agent directory

A branch can appear occupied even when its listed directory has disappeared. This often follows manual deletion of a worktree directory: Git can still have administrative records for it. Check before cleaning them up:

git worktree list --verbose
git worktree prune --dry-run

The dry run reports records that pruning would remove. If the directory really is gone and no longer needed, run:

git worktree prune

If the directory was moved rather than deleted, use git worktree repair with its new path instead of pruning its record:

git worktree repair ../moved-agent-auth

A worktree on an unmounted drive or network share may also look missing. Check whether it is temporarily unavailable before pruning. Git supports git worktree lock for worktrees stored at locations that are not always mounted; locking prevents their administrative records from being pruned. Avoid editing files under .git/worktrees by hand when the worktree commands can repair or remove the record.

Why forcing the checkout is usually the wrong fix

git worktree add --force can override the safeguard that blocks a branch already checked out elsewhere. git switch --ignore-other-worktrees can also make two worktrees hold the same branch. Those options exist, but they remove the clear ownership that helps parallel agent work stay understandable.

Both worktrees would refer to the same branch name. If one advances that shared branch, the other worktree’s files and index do not become a coordinated copy of those edits. That creates a confusing basis for reviewing or committing the other agent’s work. Keep the original branch in its owner, create a separate branch for independent edits, or perform an explicit handoff when the owner is finished.

Do not assume --force means the same thing on every Git command. In particular, forcing worktree creation can permit a second checkout, while forcing worktree removal can delete an unclean directory. Read the command and the path before using either form.

Where Parallel Code fits

Parallel Code is our free, open-source desktop app for macOS and Linux. It runs AI coding agents in parallel, each isolated in its own git worktree, and provides a diff-first review surface. The Git commands above still apply when you need to inspect an agent’s branch or hand it over to another worktree.

Frequently asked questions

Can I check out the agent branch in two worktrees?

Git provides options that allow it, including git worktree add --force and git switch --ignore-other-worktrees. For agent work, a separate branch or detached worktree is easier to reason about because each checkout has a clear role.

Does a detached worktree include uncommitted agent edits?

No. git worktree add --detach ../review-auth agent/auth checks out the commit named by agent/auth; edits still sitting in the agent directory’s working tree or index are separate. Inspect that directory’s status and diffs if you need the complete work in progress.

Will removing the agent worktree delete its branch?

git worktree remove removes the linked worktree, while branch refs are shared by the repository. Check for ignored files and save anything valuable outside the directory before removal.

What if Git lists a worktree path that no longer exists?

Use git worktree list --verbose and git worktree prune --dry-run to inspect the record. Prune it if the directory was deleted and is no longer needed; use git worktree repair if the directory was moved.