Dev

dev — Lab-Stack Boot

One command boots the four moving parts of a Vercel-Labs-flavored dev loop:

1. portless → named HTTPS https://<branch>.localhost (no port collisions across worktrees)
2. emulate → stateful API emulators on the same origin via @emulators/adapter-next
3. dev server → pnpm dev / npm run dev / yarn dev (auto-detected)
4. agent-browser → pre-warmed session named after the branch

State lives in .claude/state/dev-stack.json. Teardown via dev stop reads the PIDs and signals SIGTERM in reverse boot order.

Paired with expect: the agent-browser session that dev warms is the same one expect (and the M125 #2 auto-trigger) attach to — no second startup latency on the first UI test.

When to invoke

Resuming a backgrounded dev session (CC 2.1.144+): Sessions started via claude --bg now appear in /resume alongside interactive ones, marked bg — use /resume as the direct recovery path after a crash or session end instead of navigating the agent view.

Background shell sessions (CC 2.1.154+): In claude agents, type ! <command> to run a shell command as a backgrounded session you can attach to and detach from — also available as claude --bg --exec '<command>'. Useful for long dev-loop processes (watchers, builds, servers) you want to monitor without holding a terminal.

Modes (M127)

Tailscale is optional — required only behind --share/--funnel/--live. Default dev is unchanged for users who don't share.

When turbo.json or package.json workspaces is detected (#1562), the boot uses bare portless (zero-config) which auto-discovers each workspace's dev script and assigns subdomains via the task graph. State file shows mode: "monorepo"; list subdomains via portless list or dev status.

Boot sequence

portless is a wrapper, not a sidecar — portless <slug> <pkg-mgr> run dev is one fused command that owns the dev server's lifecycle. boot.sh tracks the wrapper PID; stop.sh walks its process tree to clean up children.

Copy code
0. Detect package manager      pnpm > yarn > bun > npm   (lockfile-based)
1. Resolve subdomain slug      <branch> → lower → / to - → DNS-safe → ≤63 chars
2. portless proxy start         (idempotent — skipped if `portless list` already responds)
3. emulate --seed <yaml>        (sidecar, optional — only if emulate.config.yaml exists)
4. portless <slug> <pkg-mgr> run dev   (FUSED — wrapper owns dev server's lifecycle)
5. portless get <slug>          (poll up to 30s for the route to register)
6. wait-on <baseUrl>            (poll up to 30s for the dev server through the proxy)
7. AGENT_BROWSER_SESSION=<slug> agent-browser open <baseUrl>   (warm + register session)
8. atomic state write           (.claude/state/dev-stack.json via jq + temp + mv)
9. print summary

The full annotated walkthrough: references/boot-sequence.md.

State file shape

jsonCopy code
{
  "bootedAt": "2026-04-27T12:34:56Z",
  "branch": "feat/m125-lane-b",
  "subdomain": "feat-m125-lane-b.localhost",
  "baseUrl": "https://feat-m125-lane-b.localhost",
  "mode": "single",
  "processes": {
    "portlessWrapper": {
      "pid": 86104,
      "command": "portless feat-m125-lane-b pnpm run dev"
    },
    "agentBrowser": { "sessionName": "feat-m125-lane-b" },
    "emulate":      { "pid": 86200, "command": "emulate --seed emulate.config.yaml" }
  },
  "emulators": ["github", "stripe"],
  "share": null,
  "notes": "portless proxy daemon is shared and not tracked here — stop.sh leaves it running."
}

When --share / --funnel / --live is used (M127 #1561 / #1565), share becomes:

jsonCopy code
"share": {
  "mode": "tailscale",
  "tailscaleUrl": "https://app.your-tailnet.ts.net",
  "expiresAt": "2026-05-03T20:00:00Z"
}

mode is "single" (default) or "monorepo" (when turbo.json/workspaces detected). Note portlessWrapper (not portless + devServer) — portless owns the dev server. Full schema: references/state-schema.md.

Auto-surfaced hints (M127)

When dev boots, it inspects package.json and emits hints:

• @json-render/* detected (#1560) → prints the devtools adapter import line so the inspector panel (Spec / State / Actions / Stream / Catalog / Pick) can be enabled in dev. Tree-shakes from production builds.
• @clerk/* detected (#1563) → if clerk is in emulate.config.yaml, prints the mock login URL (http://localhost:4012); otherwise warns to run emulate-seed --auto.

Prerequisites + graceful no-op

Copy code
$ dev
✓ portless     found
✓ agent-browser     found
✓ jq     found
[1] slug       feat-m125-lane-b

# OR with a missing prereq:
✗ portless not found.   Install: npm i -g portless

Skipping boot — install missing tools and re-run.

portless, agent-browser, and jq are required. emulate is optional — required only if emulate.config.yaml exists. The boot is all-or-nothing on the required set; with no emulate config the boot proceeds without emulators.

CI=1 short-circuits the boot (exits 0 immediately).

Status + teardown

Copy code
$ dev status
ork:dev — feat/m125-lane-b
  ✓ portlessWrapper    portless feat-m125-lane-b pnpm run dev
  ✓ agentBrowser       feat-m125-lane-b
  base url:  https://feat-m125-lane-b.localhost
  booted:    2026-04-27T19:36:54Z
  portless:  route registered ✓

$ dev stop
ork:dev — sending SIGTERM in reverse boot order…
  ✓ agent-browser session "feat-m125-lane-b" closed
  ✓ portless wrapper (pid 86104) + 21 descendant(s) stopped
Cleared .claude/state/dev-stack.json

Note: portless proxy daemon left running (shared). Run `portless proxy stop` if you really mean to stop the daemon.

Stop walks the wrapper's process tree (pgrep -P recursively) and SIGTERMs descendants leaves-first because portless doesn't always propagate signals cleanly. The portless proxy daemon itself is shared infrastructure and is never killed by dev stop.

Worktree behavior

Each git worktree gets its own subdomain — feat-foo.localhost and feat-bar.localhost coexist on the same machine. The state file lives under each worktree's .claude/state/, so dev from one worktree doesn't see the other's processes.

Idempotency

Re-running dev while the stack is already live is a no-op:

Copy code
$ dev
ork:dev — feat/m125-lane-b already running.
  https://feat-m125-lane-b.localhost  (uptime 2h 14m)
Run dev stop to tear down, or dev status for detail.

Liveness probe: process.kill(pid, 0) against each tracked PID. If any are dead, the skill prints which ones and offers to clean up state and reboot.

How agent-browser composes

The session name equals the subdomain — agent-browser commands targeting that session don't need a --session flag if it's the only one connected:

bashCopy code
agent-browser open "https://feat-m125-lane-b.localhost/dashboard"
# implicit session = "feat-m125-lane-b" because it's the only one

expect (M125 #2) reads the dev-stack state file and reuses this same session — no second handshake.

Integration with expect (M125 #2)

When auto-expect fires after a .tsx edit, it:

1. Reads .claude/state/dev-stack.json to find the agent-browser session and base URL.
2. Computes the affected route from the file path (app/dashboard/page.tsx → /dashboard).
3. Drives agent-browser against <baseUrl><route> using the live session.
4. Records the ARIA snapshot to memory keyed by (route, parentCommit) (M125 #6).

If the dev stack isn't live, auto-expect skips silently — dev is the prerequisite, not a hard dep.

When NOT to use

• CI — set CI=1; the skill exits 0 without booting.
• Production deploys — never; this is dev-loop only.
• Non-Vercel-Labs stacks — falls back to install hints; you can still run the underlying tools manually.
• Inside a tmux -CC session — agent-browser dashboard incompatible with iTerm2 tmux integration.

Scripts

dev invokes scripts/boot.sh; stop → stop.sh; status → status.sh. The shell scripts are the source of truth.

References

Rules

Running unattended with /goal

Set a completion condition with /goal (CC 2.1.139+) and this skill will keep working across turns until the condition is met. Works in interactive, -p, and Remote Control. The overlay panel shows live elapsed / turns / tokens.

Example completion condition for this skill:

Copy code
/goal until services.running == 4, or stop after 5 turns

Stops when: all 4 dev-loop services (portless + emulate + dev-server + agent-browser) report healthy on their respective ports/sockets. Compatible with claude.ai Remote Control runs.

Related skills

• expect — diff-aware browser tests; reuses the agent-browser session this skill warms
• emulate-seed — generates the emulator config that step 3 consumes
• portless (skill) — underlying tool docs
• browser-tools (skill) — agent-browser command reference