Lesson 0002

Inspect a Git worktree before you touch it

A worktree is another checkout attached to the same repository. In Agents View, that matters because useful background work may live in an isolated worktree path until you intentionally keep it, merge it, or remove it.

Mission: Claude Code Agents View Previous: Use Agents View Reference: git worktree quick reference Source: official Git manual

The one idea

Do not think of a worktree as a second clone. Think of it as a second working directory connected to the same repository storage. The official Git manual says one repository can have one main worktree and zero or more linked worktrees, letting you check out more than one branch at a time.

Mission fit: this lesson keeps the existing Agents View mission. It teaches the Git safety model you need before deleting or harvesting a background session that wrote into .claude/worktrees/.

What is isolated

Thing Worktree behavior Why you care
Files on disk Separate per worktree path. An agent can edit files without touching your main checkout.
HEAD and index Separate per worktree. Each worktree can have its own checked-out commit and staged changes.
Commits and branch refs Shared by the repository. A commit made in one worktree is visible from the others.
Same branch twice Git refuses by default. This prevents two directories from both pretending to own one branch.
Dirty removal git worktree remove refuses by default. Git tries to stop you from deleting uncommitted work by accident.

The inspection loop

Listgit worktree list Entercd <path> Statusgit status --short Branchgit branch --show-current Diffgit diff Decidekeep, merge, or remove

Use this loop whenever a session, tool, or teammate points you at a worktree path. The first decision is not "delete or merge"; it is "what branch, what files, what changes?" 

git worktree list
cd <worktree-path>
git status --short
git branch --show-current
git diff
git diff --cached
git log --oneline --decorate -5

Create one safely

The most common manual pattern is a sibling directory plus a fresh branch. From the main checkout: 

git worktree add ../task-name -b task-name

For throwaway testing with no branch, use a detached worktree: 

git worktree add -d ../scratch-test
Submodule caution: the Git manual still warns that multiple checkouts of a superproject are not recommended when submodule support matters. If a repo depends heavily on submodules, slow down before using worktrees as your default workflow.

Remove one safely

Remove a linked worktree through Git, not by deleting its folder first. Git tracks administrative metadata for linked worktrees, so the command can check whether the directory is clean. 

git worktree remove ../task-name

If someone already deleted a worktree directory by hand, inspect stale entries before cleanup: 

git worktree prune --dry-run
git worktree prune

Agents View checklist

  1. Find the path

    Peek or attach to the session and find the worktree path. Agents View reference material notes that Claude-created background work may be isolated under .claude/worktrees/.

  2. Inspect before cleanup

    Run the inspection loop in that path. Confirm whether changes are untracked, unstaged, staged, or committed.

  3. Keep useful work intentionally

    Commit it on its branch, push it, cherry-pick it elsewhere, or copy a patch. Choose one before deleting the session or removing the worktree.

  4. Remove only when boring

    A boring worktree has no useful uncommitted changes. Then git worktree remove <path> should succeed without force.

Practice: retrieve the safety loop

Type the command from memory, then check. The point is to make the inspection loop automatic before you need it under pressure.

Primary source

Ask follow-up questions: Bring this lesson back to the agent if you want to practice on a real repository, recover a session worktree, or compare worktrees with clone, stash, branch, and checkout.