Parallel work — scripts/wt
The big picture: scripts/wt new <issue> gives each issue its own folder (a git
worktree) and branch, so several Claude sessions can work at once without stepping on
each other.
Why it matters: Two sessions in one checkout fight: one runs git checkout and the
other’s files change underneath it. Separate worktrees make that impossible, and the
guards below make the shared parts (stash, test database, ports) safe too.
The commands:
scripts/wt new 1234 # worktree + branch off origin/<default>scripts/wt list # branch, age, pushed-state, pathscripts/wt remove 1234 # refuses if there is uncommitted workscripts/wt claim 1234 # check out an issue without a worktree yetscripts/wt release 1234 # clear a check-out (stale lock, or a claim you dropped)scripts/wt prune # remove merged-and-deleted worktrees — run after every mergescripts/wt stash # worktree-PRIVATE stash (see guard 4 below)scripts/wt doctor # verify symlinks and shared stack reuseWorktrees live at ../<repo>-wt/<branch-leaf>/, with heavy dependency folders
(node_modules, .venv, …) linked back to the main checkout so nothing is installed
twice.
wt warns at 8 active worktrees and refuses at 10 — a WIP guard, not a resource limit.
Worktrees are cheap here (dependencies symlinked, dev stack shared); what the cap
protects is your ability to finish things. Raise it per-invocation for a deliberate burst
(WT_CAP=16 scripts/wt new 1234) — see
Working the harness — a day in the life.
Claiming the issue. Every session shares one forge identity, so an assignee or a
comment cannot tell two sessions apart. wt new (and wt claim) therefore check the
issue out: they apply the status::wip label and post a 🔒 checked out comment naming
the branch and worktree. A second wt new on the same issue is refused and quotes that
comment; --force takes the issue over deliberately. The label is cleared when
wt prune reaps the branch, and by wt remove once the issue is closed — removing
unmerged work leaves it on an open issue, because then the label is the only signal that
the issue is spoken for. /wave skips issues that carry
it, and the push-time collision gate warns when a branch’s issue is labelled but has no
MR yet. The lock is advisory and best-effort: with no glab/gh, or on an API error,
wt warns and still creates the worktree. Use another label with WT_LOCK_LABEL. A
wt claim holds the label too, so starting the worktree later needs wt new <issue> --force
(or wt release <issue> first) — you are taking over your own claim.
Reusing a branch. If the branch already exists, wt new reuses it and says so
(REUSED existing branch). It also warns with the count when that branch is behind
origin/main (N commit(s) BEHIND), so rebase before working, and it refuses a branch
whose work already merged (a merged MR with the tip’s SHA, or every patch already in
main) instead of silently starting on finished work. --force bypasses that refusal as
well as the claim check; it still prints the warning. A branch created but never committed
to is not treated as merged. This ships in 0.8.
Every glab/gh call wt makes is time-bounded (WT_FORGE_TIMEOUT, default 20 seconds) when
perl is installed (it ships with macOS and most Linux distributions; the Alpine CI image needs
apk add perl). Without perl, wt warns at startup and the calls run unbounded. On a timeout
wt warns and carries on: prune still removes the worktree and names the issue so you can run
wt release <issue>, claim and new say the label was not confirmed instead of reporting
success, and a timed-out merged-MR lookup keeps the worktree.
Go deeper: why it’s safe with many sessions
Section titled “Go deeper: why it’s safe with many sessions”Concurrent wt use is safe by construction, not by coordination. Five structural
guards keep sessions from damaging each other’s work:
--no-trackon branch creation. Without it a fresh branch inheritsorigin/<default>as its upstream, and all three ofprune’s conditions then line up for a never-pushed worktree — an upstream exists,origin/<branch>does not, and the branch is trivially an ancestor of the default. The worktree gets reaped while someone is working in it.--no-trackleaves no upstream, so the never-pushed check correctly skips it.- A
.wt-ownermarker and a freshness grace window.prunenever removes a worktree younger thanWT_GRACE_MIN(default 30 minutes) unless--forceis passed, protecting one that another session created moments ago and has not pushed yet. - A per-worktree
WT_TEST_DB. Each generated.envrcexports a unique test database name, so parallel test runs in sibling worktrees get isolated databases and no external lock file is needed. Have the project’s test settings read it, andsource .envrcbefore running the suite. scripts/wt stashinstead ofgit stash.refs/stashlives in the git common dir, so it is not worktree-scoped: every worktree of a repo shares one stack. Worktree A pushes, B pushes, A pops — and A gets B’s work. Because a clean apply also drops the entry, B’s uncommitted work is now gone from the stash and mixed into an unrelated tree, with nothing in either session’s output naming it. (A conflicting apply keeps the entry — that is the lucky branch of the same bug.) There is nopre-stashhook, so nothing can catch it where it happens; it has to be replaced.wt stash [push|pop|apply|list|show|drop]keeps entries underrefs/wt-stash/<worktree>and never reads or writesrefs/stash.wt doctorwarns whenrefs/stashis non-empty while worktrees are active. Untracked files are not captured (git stash createcannot) and the command says so rather than letting you assume otherwise — for a one-file detour,cpaside and back is still simplest.- Per-worktree E2E ports. Each
.envrcalso exportsWT_E2E_PORTandWT_E2E_DEV_PORT, derived from the worktree’s slug and probed forward past any port a sibling worktree has claimed or a live process holds. Playwright’sreuseExistingServeridentifies a running server by port alone, so with one hardcoded port every worktree shares one preview server and a local run can pass against another branch’s bundle. Read the variables in your E2E config (see.claude/rules/tests.md); unset — the main checkout and CI — your defaults apply.
prune recognizes every way a branch lands. A branch counts as merged when its tip
is an ancestor of the default branch (a merge commit), when git cherry finds every one
of its patches already there (a tip amended or rebased after its last push), or when the
forge has a merged MR/PR whose head is exactly the local tip (a squash merge). If none
can be shown — including when the forge cannot be reached — the worktree is kept. A
tracked .envrc or .wt-owner does not count as local work. Nothing reaps a worktree
after a forge merge, so run scripts/wt prune from the main checkout after merging;
/mr reminds you, and /mass-merge removes each worktree as its MR lands. /mass-merge
only lands MRs if your session may run glab mr merge, which the template denies by
default; see /mass-merge.
wt list shows age and pushed-state per worktree so it is obvious at a glance whose
worktree is whose.
Git hooks are shared, not per-worktree. .git inside a worktree is a file pointing at
the main checkout’s real git dir, not a directory — make setup resolves the actual hooks
directory with git rev-parse --git-common-dir rather than assuming a literal .git/hooks
path, and that resolved directory is the same one the main checkout uses. Run make setup
once, from anywhere — the main checkout or any worktree — and every worktree you create
afterward already has the hooks installed; you never need to re-run it per worktree.
Working across multiple terminals
Section titled “Working across multiple terminals”scripts/wt is the mechanics — one worktree, one branch, one safe place to stand. This
section is the human layer on top of it: what to actually run in each of those terminal
panes once you have several of them open. The organizing unit is the editor window — one
window per project, as in the VS Code setup
— and inside that window it is normal to have somewhere around six to eight terminal
panes open at once, each running its own Claude Code session against the same
checkout. They are not all doing the same kind of work.
1. Parallel execution — most panes, most of the time. Each pane owns a discrete unit
of work — a worktree, an issue, a gate run, a /mass-merge batch — and runs it to
completion independently of the others. Running /wave for a wave of issues keeps this
cheap: each agent defaults to Sonnet, and /wave escalates an issue to Opus only for a
named reason, and to Fable only as a rescue you approve after Opus failed (see /wave). Because each pane checked out its own worktree
with scripts/wt new, one session’s git checkout never swaps the working tree under
another (see the structural guards above). At six to eight terminals deep, most of them
are this: grinding through a backlog of independent, mechanically similar tasks in
parallel rather than one at a time.
2. A research / triage pane. One pane whose job is investigation, not execution — reading a CI log, checking whether something is already tracked, confirming a change is safe before another pane acts on it. It is rarely “done” in the sense of producing a diff; its output is a conclusion, and that conclusion has to be written down — an issue, a scratch note, a memory entry — before the pane is cleared or closed, or it is gone.
3. An “actioned but not forgotten” pane. Distinct from research: this is where
things go that you have identified as necessary but that are not the next thing to do —
a follow-up issue to file, a finding that needs a fix, a flaky test worth a look later.
The discipline is externalizing immediately rather than letting it sit in one pane’s
scrollback: file the issue, add a TODO(#NNN) reference, drop a note. With six to eight
terminals open, this pane is what stops “I noticed that earlier” from meaning “and now
it’s lost in pane 5’s history.”
Keep it running: /compact and /clear
Section titled “Keep it running: /compact and /clear”Running this many sessions concurrently makes context hygiene a survival trait, not a nicety — a window kept alive across a full day of parallel work needs deliberate upkeep, or it gets slow and expensive to reason in long before it gets useless.
/clearbetween units of work. A pane that just finished one issue, worktree, or gate run should/clearbefore starting the next rather than carry the finished task’s context forward. With eight panes cycling through a backlog, this is the difference between each pane staying cheap and fast indefinitely, versus every one of them creeping toward the same bloated-context wall at the same time./compactmid-task, not after. For the research/triage pane and any long-running job that cannot just/clear— it is still mid-investigation, or the worktree’s work is not done — compact before the transcript gets unwieldy. Long tool output and file reads accumulate fast, and recall degrades before you would expect.
