Worktree Sandbox

Each worktree gets a slot (1–20) running one Docker Compose stack. All services in a stack share one network namespace, so the API and the dev server keep the ports the app hardcodes, and the stack's own Chromium reaches them on localhost exactly as on a normal dev machine — even when the frontend hardcodes the API's address. Stacks can't see each other. Per slot, only two ports reach the host, both on 127.0.0.1:

The tooling ships in this skill: scripts/wt.ps1 (PowerShell 7, runs on Linux, macOS, and Windows/WSL2) and the browser image in docker/browser/. The services come from ~/.wt/config.json — any image, command, port, and working folder — and wt generates each stack's Compose file from it. Config and per-branch state live in ~/.wt/, never in a repo.

• Before the first wt up on a machine, read references/setup.md (prerequisites, every config field, private package feeds, HTTPS, file ownership).
• To write the services block for a stack, read references/stacks.md (ready-made recipes). Read the repo's own dev scripts and README to fill in the commands and ports; never guess a port the app doesn't use.

When to use this skill

• The user wants several branches or worktrees running at once, each testable in a browser.
• An agent needs a browser pointed at its worktree's code while other sessions run theirs.
• The user wants to watch, or take over, what agents are doing in their browsers.

Commands

The branch argument defaults to the current worktree's branch.

Always give the branch when passing claude arguments, and put them after --, or PowerShell binds them to wt's own switches.

wt below is the alias from references/setup.md, which works inside a PowerShell session. From bash or any other shell there is no alias, and pwsh -File rejects --, so call it as:

pwsh -NoProfile -Command "& '<skill-dir>/scripts/wt.ps1' claude <branch> -- -p 'smoke test'"

Rules

1. The application repo is never changed

The whole point is a clean tree. wt writes nothing into the worktree except build output that is already gitignored.

❌ "The frontend hardcodes port 5000, so I edited its config to read the port from an env var." ✅ "The frontend keeps calling localhost:5000; inside slot 3 that is slot 3's API. No repo files changed."

If something only works with a repo change, stop and tell the user what and why. Before reporting done, run git status --porcelain in the worktree and quote it; any sandbox-caused line is a failure to report, not to hide.

2. Use only your own slot

Run wt which first. Sessions started with wt claude have WT_SLOT, WT_CDP_URL, and WT_VIEW_URL set and playwright / chrome-devtools MCP servers already pointed at the slot. Without them, connect with Playwright's chromium.connectOverCDP("<your CDP url>").

❌ "Slot 2's browser was free, so I used it." / "I restarted all stacks to pick up my change." ✅ "Slot 4 (feat/x): driving http://127.0.0.1:9224; other slots untouched."

Never stop, restart, attach to, or -Purge another slot's stack. -Purge on your own slot only when the user asks.

3. Open the app inside the stack's browser, never the host's

On the host, a hardcoded API address reaches nothing, or another stack.

❌ Opening http://localhost:3000 in the host browser or a separately launched Chrome. ✅ Navigating the stack browser (via CDP or the live view) to the app's normal dev URL.

4. A stack is up only when observed up

wt up returning is not the app running: package restores can take minutes.

❌ "Stack started, the page is working." ✅ "wt ls: slot 4 api:up web:up; the page loaded with title <title>."

A check you didn't run is not run, never passed. starting for more than a few minutes means read wt logs -Service <name> and quote the first error.

5. Tell the user where to watch

When browser work starts, give the live-view URL so the user can watch or take over. If another skill is driving the test (e2e-verify, if installed), hand it your slot's CDP URL as the browser to use; without it, drive the pages yourself through the MCP tools.

❌ Driving the stack's browser for ten minutes and reporting only "tests passed". ✅ "Watch at http://localhost:7904/vnc.html; starting the checkout flow now."

Report

End any sandbox task with this block:

Sandbox: slot <n> · branch <branch> · view http://localhost:<port>/vnc.html · CDP http://127.0.0.1:<port>
Health (wt ls): <service>:<up|starting|running|-> for each service
Repo clean: <quoted git status --porcelain output, or "clean (empty output)">
Not run: <checks skipped, or "none">

Troubleshooting