internal-dev-workbench

internal-dev-workbench

Bootstraps an opinionated 3-pane tmux session for end-to-end Workflow SDK development. Each pane is launched through 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:

+----------------------+--------------------------+
|                      |  PANE_OBS: workflow web  |
|                      |  (observability UI       |
|  PANE_DEV: turbopack |   scoped to the          |
|  (Next.js dev)       |   workbench app)         |
|                      +--------------------------+
|                      |  PANE_SH: zsh scratchpad |
|                      |  (repo root, for build, |
|                      |   tests, e2e, git, etc.) |
+----------------------+--------------------------+

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:

REPO=/path/to/workflow--<worktree-suffix>
# Session name = basename of the branch (matches portless's subdomain prefix
# and the statusline's `tmux attach -t <prefix>` indicator). For branch
# `pgp/foo-bar` this resolves to `foo-bar`.
SESSION=$(git -C "$REPO" rev-parse --abbrev-ref HEAD)
SESSION="${SESSION##*/}"

# Create the session and capture the initial pane ID
PANE_DEV=$(tmux new-session -d -s "$SESSION" -c "$REPO" -P -F '#{pane_id}')
PANE_OBS=$(tmux split-window -h -t "$PANE_DEV" -c "$REPO" -P -F '#{pane_id}')
PANE_SH=$(tmux split-window -v -t "$PANE_OBS" -c "$REPO" -P -F '#{pane_id}')
tmux select-layout -t "$SESSION" main-vertical

# Pane DEV (left): Next.js turbopack workbench, with manifest exposed for e2e
tmux send-keys -t "$PANE_DEV" \
  'cd workbench/nextjs-turbopack && WORKFLOW_PUBLIC_MANIFEST=1 portless run --name turbopack pnpm dev' C-m

# Pane OBS (top-right): observability UI scoped to the workbench app
tmux send-keys -t "$PANE_OBS" \
  'cd workbench/nextjs-turbopack && portless run --name workflow-obs sh -c "pnpm workflow web --webPort \$PORT --noBrowser"' C-m

# Pane SH (bottom-right): scratchpad at repo root
tmux send-keys -t "$PANE_SH" 'echo "scratchpad: $(pwd)"' C-m

tmux attach -t "$SESSION"

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:

 dev  ·   obs  ·   tmux attach -t <worktree-prefix>

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:

{
  "statusLine": {
    "type": "command",
    "command": "$HOME/github/vercel/workflow/skills/internal-dev-workbench/statusline.sh"
  }
}

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.

tmux send-keys -t "$PANE_DEV" C-c
# Wait for the prompt to return
tmux send-keys -t "$PANE_DEV" \
  'cd workbench/nextjs-turbopack && WORKFLOW_PUBLIC_MANIFEST=1 portless run --name turbopack pnpm dev' C-m

Verify the new workflow is registered (use the portless-assigned local port from portless list, or the .localhost URL with the trusted CA):

/usr/bin/curl -s "$(portless get turbopack)/.well-known/workflow/v1/manifest.json" \
  | grep -o '<your-new-workflow>'

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:

PORT=$(portless list | awk '/turbopack/ {n=split($3,a,":"); print a[n]; exit}')
DEPLOYMENT_URL="http://localhost:$PORT" APP_NAME="nextjs-turbopack" \
  pnpm vitest run packages/core/e2e/e2e.test.ts -t "<test name>"

Or use the portless URL with the CA trust:

NODE_EXTRA_CA_CERTS=/tmp/portless/ca.pem \
  DEPLOYMENT_URL="$(portless get turbopack)" APP_NAME="nextjs-turbopack" \
  pnpm vitest run packages/core/e2e/e2e.test.ts -t "<test name>"

Teardown

tmux kill-session -t "$SESSION"

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).