scripts/wt
The big picture: scripts/wt makes an isolated git worktree and branch for one issue,
and puts a status::wip label on the issue so a parallel session does not take it too.
For the working model, see Parallel work.
Why it matters: Two sessions picking the same issue, a stash popped into the wrong worktree, and a worktree reaped while someone is using it are the recurring ways parallel work loses time. Each subcommand below closes one of them.
This page is kept in step with the script by scripts/check-harness-reference.py
(make check-harness-reference): a subcommand in the usage block at the top of
scripts/wt that has no entry here fails the check. scripts/wt help prints that block.
Worktrees live at $WT_BASE (default ../<repo>-wt, a sibling of the main checkout).
The WIP cap is 10 (WT_CAP raises it for a deliberate burst, not to avoid finishing
things); it warns at 8.
Subcommands
Section titled “Subcommands”scripts/wt new <issue|branch-name> [--force]
Section titled “scripts/wt new <issue|branch-name> [--force]”Creates a worktree and a branch off the latest origin/<default>, or reuses an existing
branch (it says so, and warns with the count when it is behind). It refuses a branch that
is already merged. It then checks the issue out: a status::wip label plus a comment. It
refuses an issue that already carries the label. --force takes over that claim and also
bypasses the merged-branch refusal. Run source .envrc in the new worktree before running
tests: it exports the worktree’s own test database and E2E ports.
scripts/wt claim <issue> [--force]
Section titled “scripts/wt claim <issue> [--force]”Checks an issue out without creating a worktree yet (picked up, not started). Same lock
as new.
scripts/wt release <issue>
Section titled “scripts/wt release <issue>”Releases an issue check-out by clearing the label. Use it on a stale lock or a claim you dropped.
scripts/wt adopt <branch> [--force]
Section titled “scripts/wt adopt <branch> [--force]”Run inside a worktree that Claude Code created for an isolated subagent, under
.claude/worktrees/. A pinned /wave worker runs it first. It renames the worktree-*
branch to <branch> and drops its upstream. It then writes .wt-owner, the E2E ports and
.envrc, and records the .envrc hash in the worktree’s git dir. It does not symlink the
main checkout’s .venv or node_modules, because a worker’s install would write through
those links. It makes no forge call. The branch’s issue must already have a local claim
record, which scripts/wt claim writes.
It refuses:
- the main checkout;
- an issue number in place of a branch name;
- an unclaimed issue;
- a branch name that already exists;
- a branch that is not
worktree-*, unless you pass--force.
scripts/wt harness-diff <branch>
Section titled “scripts/wt harness-diff <branch>”Lists the harness paths that <branch> changes against origin/<default>, and exits 1 if
there are any. The paths are the single list in scripts/lib/harness-paths.txt. It counts:
- committed changes;
- uncommitted, untracked and gitignored files in the worktree that has the branch checked
out (an
.envrcpasses only if it matches the hashwt adoptrecorded). A worktree on a detached HEAD is not matched to the branch: when nothing has<branch>attached, every detached worktree is read, so a clean decoy cannot hide the branch’s real tree and another session’s dirty detached tree can cause an extra refusal. If there is no detached worktree to read, the command fails closed. A decoy worktree with<branch>attached elsewhere is not covered; tracked in macrodream/blueprint#360.
/wave runs it before it pushes a pinned worker’s branch. The pre-MR security gate runs
it as well, for a branch whose worktree is under .claude/worktrees/ (ADR 0010).
scripts/wt list
Section titled “scripts/wt list”Lists active worktrees and the WIP count, with branch, age and pushed-state so it is clear whose worktree is whose.
scripts/wt remove <issue|name>
Section titled “scripts/wt remove <issue|name>”Removes a worktree by issue number or name. It refuses when there is uncommitted work. If
the issue is closed it also clears its status::wip label; an open issue keeps it.
scripts/wt prune
Section titled “scripts/wt prune”Removes worktrees whose branches were merged to the default branch and deleted on origin,
including a tip rewritten after its last push, or a squash merge. It refuses a worktree
with uncommitted work and skips a worktree younger than the grace window (WT_GRACE_MIN,
default 30 minutes) unless --force. It releases each pruned worktree’s issue check-out.
Nothing runs it after a forge merge: run it yourself from the main checkout.
scripts/wt stash [push|pop [N]|apply [N]|list|show|drop [N]]
Section titled “scripts/wt stash [push|pop [N]|apply [N]|list|show|drop [N]]”A worktree-private stash. Use it instead of git stash: the plain stack lives in the git
common directory and is shared by every worktree, so a pop in one can apply another
session’s work and drop it. The pre-bash-deny hook refuses plain git stash for this
reason (see Hooks).
scripts/wt doctor
Section titled “scripts/wt doctor”Verifies the symlinks back to the main checkout’s dependency folders and that a running Docker Compose stack is shared.
scripts/wt help
Section titled “scripts/wt help”Prints the usage block, the environment variables (WT_BASE, WT_CAP, WT_WARN,
WT_LOCK_LABEL, WT_GRACE_MIN, WT_FORGE, WT_FORGE_TIMEOUT and the port bases), and the
parallel-safety notes.
Recovery recipes
Section titled “Recovery recipes”The check-out label is advisory and best effort: with no forge CLI, or on an API error,
the worktree is still created with a warning. Start any recovery with scripts/wt list.
A stale claim (the issue says it is checked out, but nobody is working on it). Check
scripts/wt list and the issue’s open merge requests first. If nothing is in flight, run
scripts/wt release <issue>, then scripts/wt new <issue>. To take over a live claim on
purpose, scripts/wt new <issue> --force.
An orphaned worktree (a directory that no longer matches a live branch). scripts/wt remove <name> removes it; it refuses when there is uncommitted work, so save that first
by committing or with scripts/wt stash. After a forge merge, scripts/wt prune clears
every merged-and-deleted one in a single pass.
After a session exits mid-wave. /wave resume mode ships in 0.8 (macrodream/blueprint#294): it classifies each
leftover claim and offers resume, hand back or release (/wave, Step 1b). To recover by hand
instead:
scripts/wt listshows each worktree, its branch, and whether it was pushed.- For each one, look at the branch:
git log origin/main..HEAD --onelinein the worktree shows what was committed, andgit statusshows what was not. Verify the merge request itself, not an agent’s summary of it. - Finish the work in that worktree, or hand it back with
scripts/wt release <issue>so another session can take the issue. - After the merge requests land, run
scripts/wt prunefrom the main checkout.
Do not delete a worktree directory by hand: scripts/wt remove also clears the label.