Parallel Session Grid (isolated worktrees)¶

Run multiple Claude sessions in parallel without them tangling. Each session gets its own git worktree (isolated index + files), so two sessions can never race on one working tree. Backed by scripts/wt-grid.ps1; driven by four PowerShell aliases.

Why not the old 8w/8s grid? Those open every pane in the same main tree, which causes the 2026-06-05 collision class (a sibling's pre-commit stashes your unstaged edits, two sessions conflict mid-edit, pushes get blocked). The grid here makes that impossible — any real overlap becomes a safe merge conflict at merge time, never a live race that loses work. Policy: .claude/rules/concurrent-sessions.md.

Aliases (defined in your PowerShell profile)¶

Alias	Action	Common flags
`8wt`	Launch grid: pane 1 = main tree (servers + coordinator), panes 2..N = isolated worktrees	`-Tasks <file>`, `-Panes <2..8>`
`8wts`	Status: which slots exist, clean/dirty, commits ahead
`8wtm`	Merge every `wt/slot*` branch into your current branch	`-Into <branch>`
`8wtd`	Tear down all slots (safe) + delete merged branches	`-Force` (discard unmerged)

Every pane runs Opus: the launcher exports ANTHROPIC_MODEL=opus, which outranks the repo's checked-in .claude/settings.json "model": "opusplan" (that setting would otherwise plan on Opus and execute on Sonnet). There is no Sonnet grid — -Model sonnet is rejected.

If the aliases aren't found, reload the profile: . $PROFILE

First-time shakeout (do this once)¶

. $PROFILE          # load the aliases
8wt -Panes 3        # small grid, no tasks -> new wt window, panes in slot2/slot3
8wts                # from your original terminal: confirm slot2/slot3 show 'clean'
8wtd                # confirm clean teardown; 8wts should then show nothing

If panes open in the right directories and teardown is clean, it's ready.

Daily use¶

1. Write a task manifest (one task per line)¶

Blank lines and lines starting with # are ignored. Line 1 -> slot 2, line 2 -> slot 3, and so on. Save anywhere, e.g. tasks.txt:

# line 1 -> slot 2, line 2 -> slot 3, ...
Fix all TS errors under frontend/src/services/stackup
Add a golden recording for the run_pdn_analysis tool
Update docs/guides/AI_NATIVE_SHELL.md for the new export formats

2. Launch the seeded grid¶

8wt -Tasks tasks.txt

Each seeded pane writes its line to _TASK.md in its worktree and auto-starts Claude already told to read it and do the work — no typing or pasting. Panes beyond the task count open a plain session. (Seeded slots run in acceptEdits without plan-mode so they execute; an unseeded 8wt keeps opus + plan-mode.)

3. Merge the work back¶

From your main-tree / coordinator terminal:

8wtm

Clean slots merge into your current branch; conflicts are aborted-and-reported for manual resolution; dirty/incomplete slots are skipped.

4. Clean up¶

8wtd

Two rules that matter¶

Commit or 8wtm before 8wtd. Teardown force-removes the worktree checkout, so uncommitted edits in a slot are lost. Committed work survives on its wt/slot* branch even after teardown. (The seeded prompt tells Claude to commit, so the automated flow is safe.)
Write non-overlapping tasks. Isolation removes the live race but not scope overlap — two slots editing the same file collide at 8wtm as an ordinary merge conflict. Partitioning the work is the one piece only you can decide.

Troubleshooting¶

Symptom	Cause / fix
`8wt` errors `Slot worktree exists` / `Branch wt/slotN exists`	A previous grid wasn't torn down. Run `8wtd` (add `-Force` to discard unmerged branches).
Aliases not recognized	`. $PROFILE`, or open a new terminal.
A pane opened in the wrong directory	Likely the `wt` argument string; check `scripts/wt-grid.ps1` `Do-Launch`.
Slot has commits but `8wtm` says "nothing to merge"	It compares against your current branch — make sure you're on the same base branch the grid was launched from.

How it works (internals)¶

scripts/wt-grid.ps1 delegates all worktree create/teardown to scripts/worktree-session.ps1 (the proven, footgun-protected script) and never runs git worktree remove itself. Worktrees are named pcb-wt-slotN on branch wt/slotN, with backend/venv and frontend/node_modules junctioned to the main tree (usable in seconds, no installs) and the root .env copied. The dev servers (ports 8000/5180) always run from the main tree only.