Claude Code Learning Hub
中文 Mingyu's Library

Hub / Tips / C · Design & assets

Not done until it runs in the iOS Simulator

iOS code that "compiles" is still a very long way from "works" — have Claude install it in the simulator, open it, and run it through; only when verification passes is the job done.

Claude Code Desktop (macOS) has a built-in iOS Simulator pane: when Claude builds, installs, launches, or inspects your app, a live-streaming simulator view opens automatically next to the session, where Claude taps, reads the screen, and verifies its changes itself — you can watch and step in the whole time. This page covers how to use it, and how to turn "passes verification in the simulator" into a hard completion criterion for the task.

One-line answer

Answer Phrase iOS task instructions around "run it and verify" (e.g. "after building, run through onboarding in the simulator") and Claude will automatically open the iOS Simulator pane, install the app, and do its own tapping and screen-reading; then write "verified screen by screen in the simulator + report what you saw" into the definition of done, so it can't sign off on "it compiles" alone.OfficialThe pane is a public beta and requires macOS + Claude Code Desktop, on Pro/Max/Team plans (not available on Enterprise).

Steps

  1. Get the environment ready.OfficialYou need: Claude Desktop v1.24012.0+, a Mac (the iOS Simulator only exists on macOS), and Xcode with the iOS platform installed — use Xcode 26.x, as the pane does not yet support Xcode 27, which replaces Simulator with Device Hub (with multiple versions installed, point back with sudo xcode-select -s /Applications/Xcode-26.4.app). If it complains it can't find a simulator, run xcodebuild -downloadPlatform iOS to install the runtime. Also, the pane only works in local sessions — cloud and SSH sessions can't reach the simulators on your Mac.
  2. Phrase the task as "run it and verify".OfficialNo command or setting needed — the pane opens automatically when Claude launches the app in a simulator. Official example phrasing: "Build the app and run it in the simulator to check the onboarding flow." To pick a device, just say so ("run it on the iPhone SE simulator"). The first time a given device is used, the desktop app asks for authorization once (remembered per device; taps, typing, and screenshots don't re-prompt after that). Expect: the pane opens, the app installs, and Claude starts tapping on its own.
  3. Nail down the completion criteria.Our takeJust telling it to "give it a run" isn't enough — list a verification checklist in the task: which screens, which actions, what you expect to see, and require an item-by-item report of what it saw (general principle in Give it checks it can run itself).OfficialThe docs themselves recommend that after fixing a bug or changing the UI, you have Claude relaunch the app to verify the change — a relaunch automatically reopens the pane.
  4. Share the screen, cooperatively.OfficialThe pane is interactive: you can tap/drag the simulator directly, Cmd+Shift+H for the home screen, Cmd+S to screenshot / Cmd+R to record (saved to the desktop). You and Claude drive the same device — to have it inspect a particular page, navigate there yourself and then ask; when the "Claude is using this device" badge shows, keep your hands off until it finishes. Each session gets its own devices (up to 4), with no cross-talk between sessions; simulators Claude started shut down automatically 10 minutes after the session exits, is archived, or disconnects.
  5. Know the boundaries.OfficialThere is no pane in the CLI — there Claude drives an on-screen simulator through computer use, like a human would (the screenshot-comparison loop still applies). Physical devices are not supported — to test on a real iPhone, run it from Xcode yourself and give Claude your descriptions or screenshots. Privacy note: Claude's screenshots of the device are sent to Anthropic and stored per your session retention settings, so don't sign in to real accounts in a simulator it's using.

Copy-paste prompt

After implementing this feature, it only counts as done once it passes verification in the iOS Simulator:
1. Build the app and launch it in the iPhone 17 simulator (if the build fails, fix it until it runs).
2. Verify each item on this checklist, stating what you actually saw for every item:
   - Cold start lands on the home screen, with no crash and no blank screen
   - The new feature's entry point is visible, and the screen behind it matches the requirements
   - Walk the main flow end to end; every transition and state along the way is correct
   - Rotate the screen / go to the home screen and switch back; no state is lost
3. Fix any problems you find, rebuild, and walk through the simulator again, until the whole checklist passes.
4. At the end, report the verification result for every item and what you fixed; a completion report that only says "it compiles" is not accepted.

Sources & last verified