Using Git Worktrees

Overview

A worktree is an exception for simultaneously checking out another Git history, not a general safety badge. Prefer the current workspace and reuse an existing suitable worktree. A branch decision and a worktree decision are separate.

Core principle: create only with necessity and ownership evidence; pair every created worktree with a cleanup path.

Announce at start: explain which concrete checkout conflict requires a worktree.

Step 0: Environment Detection

Before mutation, record the repository root, HEAD, branch/detached state, staged/unstaged/untracked paths, active Git operations, and:

git worktree list --porcelain

Classify the current host surface's task/chat-bound managed workspace semantics as managed, non-managed, or unknown. Use trusted host/session context, an explicit host contract, or a host-native lifecycle result; do not infer the classification from a product name, directory prefix, command-level workdir, missing tool, or absent metadata. non-managed requires positive evidence that the current surface lacks task-bound managed semantics. When the host exposes workspace fields, record the task workspace and the command's default cwd without a per-command directory override.

Stop on unresolved conflicts, an active merge/rebase/cherry-pick/revert/bisect, or an unexplained detached HEAD. A detached HEAD is acceptable only when trusted host binding evidence identifies it as the intended state of the current managed worktree; Codex-managed worktrees, for example, start detached by default. Preserve user state: no automatic stash, reset, clean, broad staging, or commit.

Before deciding necessity or placement, read the smallest relevant project AGENTS.md, CLAUDE.md, current authority, and existing worktree convention. Repository policy may require or forbid isolation and owns any approved in-repo location; do not discover that policy after creating the checkout.