/dev

name: dev
compatibility: "Claude Code 2.1.277+"
description: "One-command dev loop: portless HTTPS subdomain, emulate API mocks, dev server and an agent-browser session keyed to the git branch. Use when starting a branch, switching worktrees or resuming a project."
argument-hint: "[start|stop|status] [--share|--funnel|--live H]"
user-invocable: true
disable-model-invocation: false
context: inherit
metadata:
  category: devops
  milestone: M127
  upstream-packages: ["portless", "emulate", "agent-browser", "tailscale"]
  version: "1.1.0"
  author: "OrchestKit"
  complexity: "medium"
  tags: "dev-loop, portless, emulate, agent-browser, vercel-labs, lab-stack, m125, m127"

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

| Situation | Command | |---|---| | Start work on a new branch | `dev` | | Resume after a session break | `dev` (idempotent — skips already-live processes) | | Tear down before deleting branch | `dev stop` | | Inspect state | `dev status` | | Share preview with stakeholder | `dev --share` (tailnet) or `dev --funnel` (public) | | Time-boxed live demo | `dev --live 4` (public funnel, 4-hour expiry) |

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

| Flag | Wraps | Reach | Tailscale CLI | |---|---|---|---| | (none) | `portless <slug> <pkg-mgr> run dev` | `https://<branch>.localhost` only | not required | | `--share` | `portless --tailscale ...` | tailnet members on `https://*.ts.net` | required | | `--funnel` | `portless --funnel ...` | **public on the internet** | required | | `--live N` | `portless --funnel ...` + N-hour expiry | **public**, tracked in `live-demos.jsonl` | required |

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.

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

{
  "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:

"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 ru