Verify an Agent Is in the Correct Git Worktree

To verify an agent is in the correct Git worktree, have it run git rev-parse --show-toplevel and git symbolic-ref -q --short HEAD in the terminal where it will edit files. Compare the first result with the assigned worktree path and the second with the assigned branch. Repeat the check before staging or committing, especially if the agent has opened another terminal or changed directories.

Run the check in the agent’s working directory

Ask the agent to run this before its first edit:

git rev-parse --show-toplevel
git symbolic-ref -q --short HEAD
git status --short

The first command reports the top-level directory of the working tree containing the current directory. The agent can be in a subdirectory and still get the right worktree root. The second reports the branch attached to that worktree’s HEAD; -q makes a detached HEAD fail quietly instead of returning a branch name. git status --short shows staged, unstaged, and untracked changes, giving you a baseline before the agent starts.

Compare the results against an assignment written down before launching the agent. A plausible branch name is insufficient: the agent could be on the intended branch in a different clone, or in a different worktree of the same repository. Likewise, the intended directory does not establish that the intended branch is checked out there. Require both values to match.

Run the commands inside the agent’s execution context. Running them in your own terminal checks your terminal’s directory, which may differ from the agent’s. If an agent uses a tool that runs shell commands, have it report the command output before editing. If you launch an agent from a terminal, perform the check there and again through the agent once it starts.

Check whether GIT_DIR or GIT_WORK_TREE is set in that execution context. GIT_DIR disables normal repository discovery, and GIT_WORK_TREE can override the working-tree location. With either override, the reported root and branch establish Git’s effective context but may not establish where relative file edits will occur. Have the agent independently report the actual working directory used by its file-editing tool and compare it with the assigned worktree path before editing.

A useful handoff is: “Before changing files, report git rev-parse --show-toplevel, git symbolic-ref -q --short HEAD, and git status --short. Stop if the root or branch differs from the assigned values.” This makes a wrong directory an explicit stop condition rather than a detail to notice during review.

Confirm the path is a registered worktree

From any worktree in the repository, git worktree list shows the paths and checked-out branches of its registered worktrees. Use it to compare the agent’s reported root with the repository’s worktree list:

git worktree list

Find the exact path and inspect the branch shown beside it. The list also identifies detached worktrees and can annotate worktrees that are locked or prunable. For a script that consumes this list, use git worktree list --porcelain; Git defines that format for parsing and recommends adding -z when paths may contain unusual characters.

The list answers a different question from git rev-parse --show-toplevel. The latter identifies Git’s working-tree root for the agent’s current execution context. The list shows every worktree registered with that repository. If the expected path is listed but the agent reports another root, the path is registered; confirm its directory is accessible before concluding that the agent should use it. If the path is absent, check whether you are listing worktrees from the intended repository before treating the missing entry as a broken worktree.

Worktrees share a repository but have their own HEAD and index. That is why the path and branch checks belong together. For a broader explanation of that arrangement, see Git Worktrees: Why AI Agents Need Them.

Check repository identity when paths look alike

The same project may have multiple clones as well as multiple worktrees. A directory name and branch name can match in two unrelated clones. To distinguish them, compare the common Git directory from a known worktree and the agent’s directory:

git rev-parse --path-format=absolute --git-common-dir
git rev-parse --absolute-git-dir

Worktrees belonging to one repository use the same common Git directory. A linked worktree also has its own Git directory for worktree-specific state. Compare the first result with the result from a worktree you already trust. A mismatch means the two directories do not use the same common Git directory, even if their branch names match. The second result helps identify the particular worktree’s Git metadata; do not use it as a substitute for the working-tree path.

This check matters when an agent can reach an old clone, a second checkout made by another tool, or a similarly named project. It does not establish that the repository has the correct remote or that the branch contains the expected commits. It establishes which local repository’s Git metadata the commands are using.

Stop when the branch check fails

If git symbolic-ref -q --short HEAD fails, stop before editing or committing. Check its exit status to distinguish the cases: status 1 means HEAD is not a symbolic ref, as with a detached HEAD; status 128 means another error occurred. For a detached HEAD, decide which branch should own the work. For another error, resolve that error first. Then verify the path and branch again.

git branch --show-current prints nothing when HEAD is detached. For a guard that must fail before work begins, git symbolic-ref -q --short HEAD gives you an exit status to check. Do not infer the current branch from a directory name: Git permits the path and branch to have different names.

Inspect pending changes before the first edit

A matching path and branch tell you Git’s working context; they do not tell you what is already there. Run git status --short before giving the agent a task. For tracked paths without unresolved conflicts, the first position describes the index and the second describes the working tree. For unmerged paths, the two positions describe the competing merge sides relative to their common ancestor. Resolve existing conflicts or explicitly hand them off before starting unrelated agent work.

?? marks an untracked path. An empty result means Git reports no staged, unstaged, or untracked changes under its normal status rules; ignored files are omitted unless requested separately.

If status contains changes, decide who owns them before the agent starts. They may be the agent’s earlier work, another person’s unfinished edit, or files from a prior run. The command identifies the paths and states; it does not identify their author. Record the baseline so later changes can be reviewed against it. This is particularly useful when several agents have separate worktrees and you plan to merge their branches.

Repeat git status --short immediately before staging. Inspect the paths rather than assuming everything in the worktree belongs in the next commit. A worktree gives each agent its own working files and index, but an agent can still stage an unintended file within its assigned worktree.

Add a guard before edits or commits

For a repeatable workflow, compare the actual root and branch with explicit expected values. For example, if the assigned worktree is /projects/app-agent-auth and its branch is agent/auth, use this guard in the same shell context as the agent’s next action:

expected_tree=/projects/app-agent-auth
expected_branch=agent/auth

actual_tree=$(git rev-parse --show-toplevel) || exit 1
actual_branch=$(git symbolic-ref -q --short HEAD) || exit 1

if [ "$actual_tree" != "$expected_tree" ] ||
   [ "$actual_branch" != "$expected_branch" ]; then
  printf 'Wrong Git context: tree=%s branch=%s\n' \
    "$actual_tree" "$actual_branch" >&2
  exit 1
fi

git status --short

Set the expected values from the task assignment, not from the agent’s current output; otherwise the check merely confirms that Git returned something. Run the guard before edits, and run it again before staging and committing. A successful check is a snapshot of Git’s current context, not a promise that a later command will run from the same directory. If GIT_DIR or GIT_WORK_TREE is set, check the file-editing tool’s working directory separately as described above.

If you need to inspect a particular worktree from another terminal, git -C <path> runs Git as though it started in that path. For example, git -C "$expected_tree" status --short inspects the assigned worktree without changing your terminal’s directory. It does not prove where the agent’s own commands will run; use the in-agent check for that.

Where Parallel Code fits

Parallel Code is our free, open-source desktop app for macOS and Linux. It runs several AI coding agents in parallel, each isolated in its own Git worktree, and provides a diff-first review surface. The path, branch, and status checks above remain useful before an agent edits or commits within its assigned worktree.

Frequently asked questions

Is git branch --show-current enough to verify an agent’s worktree?

No. It identifies the current branch but does not identify the worktree path or distinguish between separate clones with the same branch name. Pair a branch check with git rev-parse --show-toplevel, compare both results with the assignment, and check the agent’s actual working directory if Git environment overrides are set.

Can I run the checks from a subdirectory of the worktree?

Yes. Under normal repository discovery, git rev-parse --show-toplevel reports the worktree root from a directory inside it. Run the command in the directory where the agent will execute its Git commands so it checks the context that matters.

What if the branch command prints nothing?

Stop before editing or committing and check the exit status. For git symbolic-ref -q --short HEAD, status 1 means HEAD is not a symbolic ref, as with a detached HEAD; status 128 indicates another error that must be resolved before checking the branch again.

Does a clean status prove the agent is in the right worktree?

No. git status --short describes pending changes in Git’s current context; a wrong worktree can also have an empty status. Verify the root and branch first, then use status to establish what files are already changed.