Spin up a portless + tmux dev session for the Workflow SDK that gives each git worktree isolated `<branch>.<name>.localhost` URLs for the Next.js workbench and the observability UI, plus a Claude statusline that surfaces those URLs. Use only when the user asks for a "portless dev session", a "tmux d

internal dev workbench Bootstraps an opinionated 3 pane tmux session for end to end Workflow SDK development. Each pane is launched through [portless](https://github.com/aleclarson/portless) so URLs are stable and worktree scoped (e.g. https://<branch .turbopack.localhost ), letting multiple worktrees run concurrently without port conflicts. A companion statusline script surfaces the active URLs in Claude Code's prompt. This is opt in contributor tooling . The repo's standard dev path ( pnpm dev from a workbench, no portless) is unaffected. Prerequisites tmux installed portless installed globally ( npm i g portless or via Homebrew). Verify with portless version . Repo bootstrapped: pnpm install && pnpm build . The first run on a fresh worktree must complete both before any dev server can start (the workbench apps depend on built workspace packages; without pnpm build you get MODULE NOT FOUND for workflow ). WORKFLOW PUBLIC MANIFEST=1 is required on the dev server when running e2e tests against it (otherwise /.well known/workflow/v1/manifest.json is gated). Layout With main vertical , the dev server takes the left column; the right column stacks the observability UI on top of a scratchpad shell: Setup The session name must match the worktree's portless prefix (the basename of the current branch) so the statusline and any other tooling that derives the prefix from the branch can locate it. Always run tmux ls first to confirm there's no pre existing session with that name; never kill an existing one. Pane indices in tmux depend on pane base index (0 by default, 1 with the common dotfile override). To stay correct under either, capture each pane's ID at split time with P F ' {pane id}' and use those IDs as targets: Once both servers are ready, portless list shows the routes. With portless run , each linked worktree gets a unique branch prefixed subdomain (e.g. stepflow test.turbopack.localhost ), so multiple worktrees coexist without changing config. Why each piece portless run name <name (instead of portless <name <cmd ): run auto detects git worktrees and prepends the sanitized branch name as a subdomain. The name flag overrides the inferred base name while preserving the worktree prefix. pnpm workflow web webPort $PORT noBrowser (instead of pnpm dev in packages/web ): the bundled CLI starts the observability UI configured against the current workbench app , hydrating it with that project's local World data. Running packages/web 's own dev script gives you the UI but pointed at nothing. sh c '... webPort $PORT' : portless's auto port injection only triggers for known frameworks it can detect on the command line. When the command is a CLI wrapper ( pnpm workflow web ), wrap in sh c and read $PORT (which portless always sets) explicitly. WORKFLOW PUBLIC MANIFEST=1 on the dev pane: required for e2e tests to fetch the workflow registry from the dev server. P F ' {pane id}' : makes the snippet correct regardless of the user's pane base index setting (defaults vary across configs). Claude statusline integration The skill ships a statusline helper at skills/internal dev workbench/statusline.sh that derives the worktree prefix from the current branch and emits a compact line: The dev / obs labels (Nerd Font rocket / graph glyphs) are OSC 8 hyperlinks that are clickable in iTerm2, Kitty, WezTerm, Terminal.app, and Ghostty. Bold, underlined, bright cyan styling identifies them as links. The tmux fragment (Nerd Font copy glyph) is bold bright green, signaling "copy this" rather than "click this". It's shown only when a session named exactly the worktree prefix exists, and it's printed as a full ready to paste tmux attach t <prefix invocation. The font must include Nerd Font glyphs for the icons to render correctly; without them you'll see substitution boxes, but the layout still works. Each piece is independent. If portless has no <prefix .turbopack.localhost route, the dev fragment is omitted, and so on. With nothing to show, the script prints nothing and the statusline stays silent. Wire it into ~/.claude/settings.json so it works across all sessions and worktrees. Point the path at your primary checkout, not at a worktree . Worktrees get deleted, so any path like ~/github/vercel/workflow <branch /... will break when you remove that worktree: Adjust the prefix if your main checkout lives elsewhere. The script itself is worktree aware: it reads Claude's workspace.current dir from stdin to derive the current branch, so the same script invocation from ~/github/vercel/workflow/... correctly surfaces routes for whichever worktree the Claude session is running in. Output rules: Nothing to show (no matching portless route, no matching tmux session) → empty output. Each piece appears independently. Start a server but no tmux session, and you'll see only the dev/obs fragments; the reverse shows only the tmux fragment. No git context but routes exist → falls back to the first matching turbopack / workflow obs route, no tmux indicator. If you already use a statusline and want to append the internal dev workbench info, run the helper and concatenate in your existing wrapper script instead of replacing command outright. Restarting after editing workflow files The workflow manifest is built at dev server startup. New workflows or steps added to workbench/example/workflows/ .ts (and their symlinks in other workbenches) do not appear at runtime , even with HMR, until the dev server restarts. Verify the new workflow is registered (use the portless assigned local port from portless list , or the .localhost URL with the trusted CA): NODE EXTRA CA CERTS=/tmp/portless/ca.pem is needed for Node clients hitting the HTTPS URL outside of portless managed children. Browsers are fine after portless trust . Running e2e tests against this session From the scratchpad pane. Use the portless assigned local port to bypass TLS for the test runner: Or use the portless URL with the CA trust: Teardown Portless removes routes when each child process exits (Ctrl+C the panes first if you want a clean portless list ). The proxy itself keeps running for other sessions; stop it explicitly with portless proxy stop if needed. Troubleshooting MODULE NOT FOUND: 'workflow' in the dev pane: Workspace packages haven't been built. Run pnpm build from the repo root, then restart the pane. Observability UI shows no runs : Verify the obs pane was started from inside workbench/nextjs turbopack (or whichever workbench you want to inspect). The CLI reads the local World from the current working directory . react router on :5173 instead of the portless port : This happens when the obs pane uses pnpm dev from packages/web . Switch to the pnpm workflow web webPort $PORT form above. Source map warning on startup ( failed to read input source map ... packages/serde/dist/index.js.map ): This warning is benign and doesn't block development. Stale workflow registration after editing 99 e2e.ts : Restart the dev pane; HMR doesn't rebuild the manifest. Statusline shows nothing : Confirm portless list has at least one matching route, the path in settings.json is absolute, and the script is executable ( chmod +x ).

internal-dev-workbench