clean-worktree

Clean HQ Worktree

Use this when HQ work was done in a separate git worktree and you now need to bring those commits back into the primary HQ tree's main branch and remove the leftover worktree. Triggers: "clean up that worktree", "merge the worktree back", "fold the agent worktree into main", "reclaim the worktree", or noticing stale entries in .claude/worktrees/ or workspace/worktrees/.

This is HQ-internal builder work. It operates only on the local HQ git repository. HQ is local-only by hard policy (hq-root-never-push-remote): nothing in this workflow ever contacts a remote — no push, no fetch, no pull. Cross-machine state moves via hq-sync, never git push.

Recommended After /handoff

When HQ itself is running from a separate worktree (the active session's tree is .claude/worktrees/<name> or workspace/worktrees/<name> rather than the primary HQ root), the work and handoff artifacts land on that worktree's branch. Once /handoff has fully completed — thread file written, handoff.json saved, INDEX updated, finalize commit done — run /clean-worktree to merge that branch back into the primary tree's main and remove the worktree, so the next session starts from a single clean tree on main.

Do this after handoff finishes, never during it: handoff owns its own commit/finalize flow, and merging a worktree mid-handoff corrupts that state. The sequence is always: /handoff completes → then /clean-worktree.

Mental Model

The HQ root (${HQ_ROOT}) is itself a git repository, always checked out on main. Agent isolation and Codex worktrees create linked worktrees of that same repository:

• .claude/worktrees/<name>/ — typically on branch claude/<name>
• workspace/worktrees/<name>/ — typically on branch codex/<name>

A linked worktree shares the HQ object store. Cleaning it up means: land its branch's commits into main in the primary tree, then tear down the worktree and delete its branch so the tree is clean again. You cannot git checkout <branch> in the primary tree (the worktree holds it checked out, and the primary tree must stay on main) — you merge the branch into main from the primary tree instead.

Critical Guardrails

These are non-negotiable. Several are mechanically enforced.

1. Every git mutation in this workflow carries an explicit absolute -C anchor AND the HQ_ALLOW_HQ_ROOT_GIT=1 prefix, in the same Bash call. Worktree operations and merges into main mutate the shared HQ object store and are HQ-root-class. Bare HQ-root git mutations are mechanically blocked by .claude/hooks/block-hq-root-git-mutation.sh. Form: HQ_ALLOW_HQ_ROOT_GIT=1 git -C ${HQ_ROOT} <cmd> for primary-tree ops, HQ_ALLOW_HQ_ROOT_GIT=1 git -C ${HQ_ROOT}/.claude/worktrees/<name> <cmd> for in-worktree ops. Never rely on an earlier cd — shell cwd drifts across context compaction and parallel calls.
2. Never push, fetch, or pull HQ. No remote interaction anywhere in this skill. Do not ask "should I push HQ?" — the answer is always no.
3. Read-only inspection commands (git worktree list, git status, git log, git diff, git branch --merged) need neither the anchor-prefix nor confirmation. Run them freely.
4. Destructive steps require explicit confirmation in full prose. git worktree remove, git branch -D, and any --force permanently discard work. Before each, list exactly what will be lost (uncommitted files, unmerged commits) and wait for the user to confirm.
5. Resolve conflicts; never discard them. If the merge conflicts, resolve file-by-file, git add the resolution, and commit. Never git checkout --/git restore a conflicted path to make it go away, and never --no-verify on main.
6. One worktree at a time. If several are reclaimable, use AskUserQuestion to pick one per call — never batch the decision.
7. Do not run during /handoff. Run it only after handoff has fully completed (see "Recommended After /handoff" above).

Process

1. Discover candidates

git worktree list --porcelain

The entry whose branch is refs/heads/main and whose path is the HQ root is the primary tree — never a cleanup target. Every other entry under the HQ root (.claude/worktrees/... or workspace/worktrees/...) is a candidate.

If the user named a worktree or branch, resolve it to one candidate (match on directory basename or branch name). If not, present the candidates with their state and ask which one (AskUserQuestion, one pick). For each candidate gather, read-only:

git -C <WT> status --short | wc -l                 # dirty file count
git -C <WT> log main..HEAD --oneline               # commits to bring back
git -C <WT> diff --stat main...HEAD                 # change scope

If a candidate has zero commits ahead of main and no dirty files, there is nothing to merge — go straight to step 5 (cleanup only) for that one.

2. Capture uncommitted work in the worktree

If git -C <WT> status --short is non-empty, the worktree has uncommitted changes that the merge would otherwise leave behind. Commit them inside the worktree before merging:

HQ_ALLOW_HQ_ROOT_GIT=1 git -C <WT> add -A
HQ_ALLOW_HQ_ROOT_GIT=1 git -C <WT> commit -m "clean-worktree: capture uncommitted work from <name>"

If git commit reports nothing to commit (changes were only ignored/session files), note it and continue. Do not force-add ignored paths.

3. Pre-merge safety check on the primary tree

Before checking status, reconcile the handoff mirror left by /handoff in a linked worktree. This removes workspace/threads/handoff.json and its copied thread only when each main-checkout file is byte-identical to the version on the branch being merged. It leaves differing files in place and exits non-zero; surface those files to the user and stop before merging.

bash "${HQ_ROOT}/core/scripts/clean-worktree-reconcile-handoff.sh" \
  "${HQ_ROOT}" "<BRANCH>"

Replace <BRANCH> with the branch selected in step 1. Continue only after the script exits successfully. It does not stage files or create commits.

git -C ${HQ_ROOT} status --short

Untracked files in the primary tree that collide with incoming paths will abort the merge. HQ autocommit normally keeps the primary tree tidy; if there is unexpected dirty/untracked state that would collide, surface it to the user and resolve it (commit or move aside) before merging — do not blindly --force or clean.

4. Merge the branch into main

From the primary tree, on main:

HQ_ALLOW_HQ_ROOT_GIT=1 git -C ${HQ_ROOT} merge --no-ff <BRANCH> \
  -m "clean-worktree: merge <BRANCH> into main"

--no-ff keeps a visible reclaim point in history. A fast-forward (HQ_ALLOW_HQ_ROOT_GIT=1 git -C ${HQ_ROOT} merge --ff-only <BRANCH>) is acceptable when main has not advanced and the user prefers linear history — ask only if it matters; otherwise default to --no-ff.

On conflict: do not abort by default. Inspect with git -C ${HQ_ROOT} status, resolve each conflicted file deliberately (these are often skill/command/policy file deletions vs. edits — preserve the intended end state, do not just take one side blindly), then:

HQ_ALLOW_HQ_ROOT_GIT=1 git -C ${HQ_ROOT} add <resolved-paths>
HQ_ALLOW_HQ_ROOT_GIT=1 git -C ${HQ_ROOT} commit --no-edit

If conflicts are too entangled to resolve confidently, HQ_ALLOW_HQ_ROOT_GIT=1 git -C ${HQ_ROOT} merge --abort, report the conflicting paths to the user, and stop — do not guess.

5. Verify the merge landed

git -C ${HQ_ROOT} branch --merged main | grep -F "<BRANCH>"
git -C ${HQ_ROOT} log --oneline -3

<BRANCH> must appear in --merged. The reclaimed commits must be visible in main's log. Do not proceed to cleanup until this is confirmed.

6. Cleanup — destructive, confirm first

Before removing the worktree, check whether Docker Compose containers were started from it. Removing the directory out from under a running Compose project leaves orphaned containers and networks behind:

docker ps -a --filter "label=com.docker.compose.project.working_dir=<WT>" \
  --format '{{.Label "com.docker.compose.project"}}' | sort -u

If a Compose project is clearly worktree-scoped (its project name derives from the worktree directory name), stop it before removing the worktree:

docker compose -p <PROJECT> --project-directory <WT> down --remove-orphans

If the project name is shared across checkouts (for example privy), do not stop it automatically. Tell the user the shared project is still running and ask before stopping it — another checkout may be using those containers.

Then state explicitly to the user, in full prose, what is about to be permanently removed: the worktree directory at <WT>, the branch <BRANCH>, and confirm there is no uncommitted or unmerged work left (steps 2 and 5 should have ensured this). Wait for confirmation, then:

HQ_ALLOW_HQ_ROOT_GIT=1 git -C ${HQ_ROOT} worktree remove <WT>
HQ_ALLOW_HQ_ROOT_GIT=1 git -C ${HQ_ROOT} branch -d <BRANCH>
HQ_ALLOW_HQ_ROOT_GIT=1 git -C ${HQ_ROOT} worktree prune

• git worktree remove (no --force) refuses if the worktree is still dirty — that is a safety feature. If it refuses, return to step 2; only use --force after the user explicitly confirms the remaining changes are disposable.
• git branch -d (lowercase) refuses to delete an unmerged branch — also a safety feature. If it refuses, the merge in step 4 did not actually land; do not reach for -D. Only use git branch -D after the user explicitly confirms they intend to discard unmerged commits.
• If the directory lingers after worktree remove (rare), remove the now-empty path with rmdir <WT> and re-run worktree prune.

7. Report

Concise summary: branch cleaned up, number of commits and files merged into main, worktree path removed, branch deleted. End with git worktree list so the user sees the tree is clean.

Notes

• HQ non-repo edits autosave via .claude/hooks/hq-autocommit.sh, so most worktree work is already committed on its branch — step 2 usually finds nothing, but always check.
• This skill does not touch repos/ worktrees. Those are normal code repos with their own push/PR discipline; cleaning up an HQ orchestration-layer worktree is a different operation from landing a code branch.
• If the worktree's branch was already merged in a prior session, steps 4–5 are no-ops and you proceed straight to cleanup — that is the normal "just clean up the leftover" path.