ios-simulator-browser

iOS Simulator Browser

Before invoking Apple-only binaries, confirm the execution context is macOS. From Windows or Linux, run those steps in a Mac SSH project or through an already configured remote transport; do not retry missing Apple binaries locally.

Bundled commands use $PLUGIN_ROOT ($env:PLUGIN_ROOT in PowerShell; same path suffix) for the plugin root. Set it once: use the host's plugin-root variable when defined (Claude Code: PLUGIN_ROOT="$CLAUDE_PLUGIN_ROOT"), otherwise the absolute path of this plugin's root directory.

Routing Priority

Use this as the preferred user-facing Simulator surface whenever the task would benefit from the user seeing or interacting with the app in the Codex browser. Plain simulator debugging remains useful for build/run, logs, bundle IDs, UI trees, and headless automation; once it provides or launches a Simulator UDID, hand off to this browser workflow for visible proof unless the user explicitly asked for a headless or log-only check.

Browser Workflow

1. Obtain an explicit Simulator UDID from the existing iOS build/run workflow or from xcrun simctl list devices available.

2. Start serve-sim in a long-running terminal pinned to that simulator. Clean up any tracked stale helper for this simulator before starting, and install a trap so the helper is cleaned up when this terminal exits:

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

3. Open the exact local preview URL printed by serve-sim in the Codex in-app browser.

4. Verify that a real frame is rendering before reporting success. A loaded page alone is not proof that the simulator stream is healthy.

• Keep the terminal alive while the browser mirror is in use. When finished, stop the terminal and wait for it to exit so the trap runs.
• If the terminal disappeared or did not exit cleanly, run npx --yes serve-sim@latest --kill "$SIM" before starting another mirror for that simulator.
• Never run an unscoped serve-sim --kill; another thread may own a different simulator mirror.