DEV Community

Cover image for Moved Your Repo Folder? Every Agent Worktree Broke. git worktree repair Fixes It
Gabriel Anhaia
Gabriel Anhaia

Posted on Edited on AI-assisted

Moved Your Repo Folder? Every Agent Worktree Broke. git worktree repair Fixes It

#git #ai #productivity #tutorial

You ran mv ~/code/shop ~/code/store to tidy your projects folder. The main checkout still works. Then you switch to the terminal where Claude Code was fixing the login bug, run git status, and get a fatal error that names a folder which no longer exists. The Codex worktree says the same. So does the third one.

Nothing is lost. Your commits, your branches and the agents' uncommitted edits are all still on disk. What broke is two small text files per worktree, each holding an absolute path that the mv just made wrong. Git ships a command that rewrites them: git worktree repair.

The two files that hold a worktree together

A linked worktree is not a copy of the repository. Its top folder has a .git file, not a directory, containing gitdir: and a path (gitrepository-layout). That path points into the main repository, at .git/worktrees/<name>, where the worktree's own HEAD and index live.

The link runs the other way too. Inside .git/worktrees/<name> is a file called gitdir, which the same page describes as "the absolute path back to the .git file that points to here." Git reads it to tell whether a worktree folder was deleted by hand.

Both links are absolute by default (the git-worktree docs list --relative-paths as "relative paths or absolute paths (default)"). Move either end and one side points at nothing:

  • Move the main repo, and every worktree's .git file points at the old location. Each git command inside the worktrees fails. The main checkout looks fine.
  • Move the worktrees, and the main repo's gitdir files go stale. git worktree list -v marks each one prunable: gitdir file points to non-existent location.
  • Move a folder that holds both, and both sides are wrong.

Which case you hit depends on where your agents keep their worktrees. Claude Code's --worktree creates them "under .claude/worktrees/<name>/ at your repository root" (docs), so moving the repo moves them too: case three. The Codex app "creates worktrees in $CODEX_HOME/worktrees" (docs), outside the repo: case one.

Editorial illustration of two folders joined by a taut orange thread, one folder being carried away in a moving box so the thread snaps
Every worktree is tied to its repo by a path in each direction. Move one end and that thread snaps.

Break it on purpose: three worktrees and one mv

Run this in a scratch folder. It makes a repo with one empty commit and three worktrees next to it, one per pretend agent task:

mkdir -p ~/scratch/wt-demo && cd ~/scratch/wt-demo
git init -q shop && cd shop
git commit -q --allow-empty -m "init"
for t in fix-login tidy-auth add-tests; do
  git worktree add -q -b "agent/$t" "../wt/$t"
done
git worktree list
Enter fullscreen mode Exit fullscreen mode

Now rename the repo, the way you would when tidying a projects folder, and look inside a worktree:

cd ~/scratch/wt-demo && mv shop store
cd wt/fix-login
git status
cat .git
Enter fullscreen mode Exit fullscreen mode

git status dies. In Git 2.48 the message is fatal: not a git repository: followed by the path the .git file points to (setup.c at v2.48.0). Newer releases reword it to gitfile does not point to a valid repository (setup.c at v2.56.0). Either way, cat .git shows the cause: a gitdir: line ending in shop/.git/worktrees/fix-login, and there is no shop folder any more.

Now check the other side, from the main checkout:

cd ~/scratch/wt-demo/store
cat .git/worktrees/fix-login/gitdir
git worktree list
Enter fullscreen mode Exit fullscreen mode

This side is still right. The worktrees didn't move, so gitdir still points at wt/fix-login/.git, and git worktree list shows all three as if nothing happened. The checkout you look at first tells you everything is fine.

Repair it: one command per case

The main repo moved and the worktrees stayed, so run repair in the main checkout. The docs: "Running repair in the main worktree will reestablish the connection from linked worktrees back to the main worktree."

cd ~/scratch/wt-demo/store
git worktree repair
git -C ../wt/fix-login status
Enter fullscreen mode Exit fullscreen mode

Now the harder case. Move the whole demo folder, so the repo and the worktrees both change places:

cd ~ && mv ~/scratch/wt-demo ~/scratch/wt-moved
cd ~/scratch/wt-moved/store
git worktree list -v
Enter fullscreen mode Exit fullscreen mode

Both links are stale now, and list -v flags every worktree as prunable. Git can't guess where you put them, so you tell it. For this case the docs say to run repair "in the main worktree and specifying the new <path> of each linked worktree":

git worktree repair ../wt/*
git worktree list -v
Enter fullscreen mode Exit fullscreen mode

Repair reports what it fixed on stderr. Its test suite checks for messages such as gitdir incorrect and .git file incorrect. For Claude Code's layout, the paths are .claude/worktrees/* from the repo root.

Do not run git worktree prune before you repair. Prune removes the $GIT_DIR/worktrees entry of every worktree whose folder it can't find, which after a case-two or case-three move is all of them, and that entry is where each worktree's HEAD and index live. git gc runs the same prune on entries older than three months (gc.worktreePruneExpire), so a repo you moved and forgot about can lose them later.

To confirm every worktree answers again, run this from the main checkout:

git worktree list --porcelain |
  sed -n 's/^worktree //p' |
  while read -r p; do
    if git -C "$p" rev-parse --git-dir >/dev/null 2>&1
    then echo "ok   $p"
    else echo "BAD  $p"
    fi
  done
Enter fullscreen mode Exit fullscreen mode

Agents can keep their own record of old paths. Claude Code's docs say its belongs to a different repository and is a leftover worktree errors "can happen after you copy or move a project", and the fix is to pass a different worktree name (troubleshooting). The same page says --continue "picks the most recent session recorded under the directory you launch from", so conversations from before the move are filed under the old path.

Stop it next time: relative paths, and two catches

Since Git 2.48, out in January 2025 (GitHub's release highlights), Git can write both links as relative paths. Turn it on for the repo, then convert the worktrees you already have. The commit that taught repair this says the links are replaced "even if the original path was correct":

git config worktree.useRelativePaths true
git worktree repair --relative-paths
Enter fullscreen mode Exit fullscreen mode

Relative links survive a move only when the repo and its worktrees move together, as with .claude/worktrees/, or a parent folder that holds both. Move the repo away from its worktrees and a relative path is as wrong as an absolute one. Repair still fixes that.

Catch one: older Git. The docs say turning the setting on "implies enabling the extensions.relativeWorktrees config", which makes the repo "incompatible with older versions of Git." That extension exists, per the 2.48 notes, "to prevent older Git versions from mis-interpreting worktrees created with relative paths." Git's repository-format rules say that if a version-1 repository names an extension the running Git hasn't implemented, "the operation MUST NOT proceed." So run git --version everywhere this checkout gets opened: a dev container that mounts it, a GUI client with its own bundled Git, an old machine you sync it to. Each one needs 2.48 or later.

Catch two: tools that read the paths. git worktree list --porcelain is the format scripts are meant to parse, and tools read its worktree lines as paths. A Claude Code issue opened in February 2026 reported that with worktree.useRelativePaths on, claude -r showed "No conversations found to resume." The reporter, on Claude Code 2.1.37 in a dev container, traced it to porcelain lines like worktree ../../../my-repo-branch being compared against an absolute working directory. Resuming by session ID still worked.

The issue was closed as a duplicate of a broader resume bug, with no fix noted on it, and I don't know whether current Claude Code still trips on this. The reporter's workaround was to set the option back to false and run git worktree repair, which writes absolute paths again. If you script against porcelain yourself, resolve each path before comparing it.

Where Hermes keeps each task's worktree

I build Hermes IDE, so weigh this section with that in mind. In Hermes, ⌘N (Ctrl+Shift+N on Windows and Linux) starts each task on its own hermes/<name> branch in its own worktree, with the task as the agent's first prompt (README). They are ordinary git worktrees, so everything above applies to them as written.

The Hermes New task sheet with a refund-endpoint task typed and chips for Claude Code, the orders-api project, a new hermes/ worktree, Accept edits, model and effort
The ⌘N New task sheet: Claude Code, the orders-api project, a new hermes/ worktree, Accept edits, model and effort, and a preview of the claude command Hermes will run.

Before you move a project, find out where its task worktrees are. Open the Review Desk (⌘G, or Ctrl+Shift+G) and go to its Worktrees tab. Running git worktree list in the project gives you git's view of the same thing.

The order that works:

  1. Let the agents finish, or stop them. On macOS and Linux, Hermes keeps agents running while the app quits, so quitting Hermes does not stop them.
  2. Write down the worktree paths from the Worktrees tab or git worktree list.
  3. Move the folder, then run git worktree repair in the main checkout, adding each worktree's new path if they moved too.
  4. Open the ⌘N project menu. Since 2.3.0, projects whose folder no longer exists are listed at the bottom so you can remove them. Add the new location with "Open folder…".

The Review Desk Worktrees tab listing one Hermes worktree each for orders-api, web-app and orders-types, with branch, task, age and disk size
The Review Desk's Worktrees tab: one Hermes worktree each for orders-api, web-app and orders-types under ~/code, with each one's hermes/ branch, task, age and disk size, and the free disk space.

Hermes is free, source-available under BSL 1.1, and runs on macOS, Windows and Linux. The current release is 2.3.4. It is not affiliated with Nous Research, Anthropic or OpenAI.

Which repair for which move

You moved Fix
The main repo only git worktree repair in the main checkout
One linked worktree git worktree repair inside it
The repo and its worktrees git worktree repair <new paths> in the main checkout
Never again worktree.useRelativePaths true, Git 2.48+ everywhere

To move a single linked worktree on purpose, git worktree move updates both links for you. It can't move the main worktree, or a worktree that contains submodules (docs). For everything else, there's repair.

If this was useful

If you run coding agents, the next questions are about what they read before they act. The RAG Pocket Guide covers retrieval, chunking and reranking, the same choices an agent makes when it picks which files to open. It's one of 8 short Pocket Guides for Developers, on agents, RAG, prompts, observability, events, databases and system design, and the whole series is here.

If you run several agents on one repo, Hermes IDE gives each task its own worktree, and a star on GitHub helps other developers find it.

RAG Pocket Guide: Retrieval, Chunking, and Reranking Patterns for Production

Top comments (0)