ios-simulator-browser

iOS Simulator Browser

Mirror a booted iOS Simulator into the Claude Code preview panel (the embedded preview browser in the sidebar) using serve-sim, which streams the Simulator's framebuffer as a web page with tap/gesture/keyboard control.

Requirements: macOS, Apple Silicon, Node.js, and a booted Simulator (xcrun simctl or XcodeBuildMCP). serve-sim runs via npx serve-sim — no install needed.

Workflow (preview panel)

1. Get the Simulator UDID. Reuse the UDID from the build/run workflow, or mcp__XcodeBuildMCP__list_sims, or xcrun simctl list devices available. Make sure the target app is built and launched on that Simulator first (see ../ios-debugger-agent/SKILL.md).

2. Register serve-sim as a dev server in the target app's .claude/launch.json (create the file if absent). Pin the exact UDID — device names can be ambiguous when duplicate simulators share a name:

   {
     "version": "0.0.1",
     "configurations": [
       {
         "name": "serve-sim",
         "runtimeExecutable": "npx",
         "runtimeArgs": ["-y", "serve-sim", "<simulator-udid>", "--host", "127.0.0.1", "-p", "3200"],
         "port": 3200
       }
     ]
   }
   

3. Start the preview with the preview_start tool (config name: serve-sim). It launches the serve-sim server — or reuses one already listening on the port — and binds the preview panel to it.

4. Verify a real frame renders with preview_screenshot, and LOOK at it. A loaded page is not proof — confirm the Simulator frame (status bar, app UI) is actually streaming before reporting success. Check preview_console_logs for errors if the frame is blank.

5. Drive it when asked: the panel supports tap/scroll directly; or use serve-sim's CLI control against the same UDID (npx serve-sim tap -d "$SIM" <x> <y> with normalized 0..1 coords), which requires the serve-sim helper to be running.

Cleanup (scoped — important)

serve-sim keeps a helper daemon (:3100) and a preview server (:3200) alive, and its supervisor respawns the preview if you kill only that process. To stop the mirror, kill scoped to this UDID:

npx --yes serve-sim --kill "<simulator-udid>"

• Never run an unscoped serve-sim --kill — another tool (e.g. a Codex session) may own a different Simulator's mirror on this machine, and an unscoped kill would tear it down.

• When you start serve-sim from a long-running terminal instead of the preview panel, install a trap so the scoped kill runs on exit:

  SIM="<simulator-udid>"
  cleanup() { npx --yes serve-sim --kill "$SIM" >/dev/null 2>&1 || true; }
  trap cleanup EXIT INT TERM HUP
  cleanup
  npx --yes serve-sim "$SIM"
  

Alternative: plain browser (no preview panel)

Run npx serve-sim "<simulator-udid>" and open the exact local URL it prints in any browser. The same scoped-cleanup rules apply.

Proof

Capture a preview_screenshot (or browser screenshot) showing the live Simulator frame — the app's actual UI, not a blank page.