git says it cannot delete a branch used by a worktree

The short answer

Git will not delete a branch while any worktree has it checked out. Find that worktree with git worktree list, check that it holds nothing you need, remove it with git worktree remove, and then delete the branch with git branch -d.

What the error means

A worktree is an extra working folder attached to the same repository, so you can have several branches checked out at once. Git remembers which branch each worktree has checked out, and it refuses to delete a branch that is in use, because that would pull the ground from under that folder. The wording depends on your version of git:

$ git branch -d claude/checkout-redesign
error: cannot delete branch 'claude/checkout-redesign' used by worktree at '~/code/web/.claude/worktrees/checkout-redesign'

Older versions of git say Cannot delete branch 'name' checked out at 'path'. The cause and the fix are the same. The message already names the folder, which is the one thing you need for the next step.

Step 1: find the worktree that holds the branch

git worktree list shows every working folder attached to the repository and the branch each one has checked out.

$ git worktree list
~/code/web                                      651badc [main]
~/code/web/.claude/worktrees/checkout-redesign  1615dbb [claude/checkout-redesign]

The first line is your main checkout. Every other line is a linked worktree. A worktree whose folder has gone missing is marked prunable, and one that was locked on purpose is marked locked.

Step 2: check that nothing is lost

Removing a worktree deletes its folder, so look before you remove anything. There are two things that can exist only there.

Commits that are not in your main branch

$ git log --oneline main..claude/checkout-redesign
1615dbb redesign checkout

If this prints nothing, every commit on the branch is already in main. If it prints commits, they are not merged yet. They may also be on a remote, which git branch -vv shows, or they may exist nowhere else. Do not delete the branch until you know which.

Files that are not committed

$ git -C ~/code/web/.claude/worktrees/checkout-redesign status --short
?? notes.txt

Empty output means the worktree is clean. Anything listed, here an untracked notes.txt, exists only in that folder. Git protects you from the worst of this: it refuses to remove a worktree that has such files.

$ git worktree remove .claude/worktrees/checkout-redesign
fatal: '.claude/worktrees/checkout-redesign' contains modified or untracked files, use --force to delete it

Read that message as a stop sign, not a hurdle. The --force option deletes those files for good.

Step 3: remove the worktree, then the branch

Once the worktree is clean, remove it. A successful removal prints nothing.

$ git worktree remove ~/code/web/.claude/worktrees/checkout-redesign

Now the branch is free. git branch -d only deletes a branch whose commits are already merged, so if the work was never merged, git tells you so:

$ git branch -d claude/checkout-redesign
error: the branch 'claude/checkout-redesign' is not fully merged
hint: If you are sure you want to delete it, run 'git branch -D claude/checkout-redesign'
hint: Disable this message with "git config set advice.forceDeleteBranch false"

That is the check from step 2 happening again, and it is the one to take seriously. Merge the branch, push it somewhere, or decide the work is not needed, and then delete it. After the branch was merged into main:

$ git branch -d claude/checkout-redesign
Deleted branch claude/checkout-redesign (was 1615dbb).

The hash in that last line matters. If you delete a branch by mistake, git branch claude/checkout-redesign 1615dbb puts it back, for as long as git has not cleaned up the unreachable commits.

If you deleted the worktree folder by hand

Deleting the folder in Finder or the terminal leaves git's record of the worktree behind, and the branch stays locked to it. The worktree shows up as prunable:

$ git worktree list
~/code/web   1615dbb [main]
~/code/wt2   1615dbb [feature/two] prunable

$ git worktree prune -v
Removing worktrees/wt2: gitdir file points to non-existent location

git worktree prune only forgets worktrees whose folders are gone. It never touches a folder that exists, and it does not delete the branch, so run git branch -d afterwards. One warning: a worktree on an external drive that is not plugged in also looks gone. Plug the drive in before you prune, or git forgets a worktree that is perfectly fine.

Why AI coding agents leave these behind

Coding agents use worktrees so several tasks can run on one repository without disturbing each other. Claude Code can work in a worktree it creates inside the repository, under .claude/worktrees/, on a branch named worktree-<name>. The Claude Code worktrees guide covers what it removes by itself and what it leaves. Cursor, Codex and Conductor keep theirs in .cursor/worktrees, .codex/worktrees and conductor/workspaces according to their documentation, so check where your own install puts them. Branch names often start with claude/, cursor/ or codex/, which is a quick way to recognise them in git branch.

Depending on the tool and on how a run ended, a worktree is sometimes cleaned up for you and sometimes left behind: runs that made changes, runs that crashed and runs you abandoned. Each one is a full copy of your files, and if the agent installed dependencies there it is a copy of node_modules as well, so a pile of them takes real disk space. They also hold exactly the branches that git then refuses to delete.

When there are dozens of them

Two or three worktrees are easy to handle with the steps above. Twenty means running the same checks twenty times, and the cost of getting one wrong is a folder of uncommitted work that is gone. That is the case Lopper was made for, and it is described below.