Claude Code iOS Simulator: Setup, Testing and Limits

Anthropic released the iOS Simulator pane in public beta on July 21, 2026. This guide covers the setup, a controlled first run, permissions, troubleshooting, verification, and shutdown paths using official Anthropic and Apple documentation checked on July 22, 2026. The launch workflow is a vendor demonstration; no independent device lab or App Store submission was performed for this article.

What launched in public beta

The dedicated pane puts Apple's iOS Simulator next to a Claude Code Desktop conversation. When Claude builds, installs, launches, or checks an app on a simulator, the pane opens and streams that simulated device. Claude can inspect screenshots and operate the app; the developer can also tap and swipe in the same pane.

Official launch quote: “Claude Code on desktop now works with the iOS simulator. Build and run your iOS app, and the simulator opens in a panel right next to your conversation. Available today in public beta.” Claude Developers, July 21, 2026

Anthropic's follow-up in the official thread says Claude can see the running app, interact with it, and iterate, while the developer can take over the simulator at any time. That describes the intended product loop, not a guarantee that Claude will find every defect or finish every task correctly.

The pane is separate from general computer use. Anthropic's simulator documentation says the Desktop pane drives the simulator directly, does not take over the Mac screen, and does not need macOS Accessibility or Screen Recording permission. By contrast, Claude Code CLI reaches a visible Simulator window through CLI computer use. This guide is about the dedicated Desktop pane.

Requirements and session limits

All four requirements need to be true before the pane can complete a run:

The docs do not give a minimum Xcode version or macOS version beyond requiring a working Xcode installation with the iOS platform. Do not invent a stricter compatibility floor. For a team rollout, record the actual macOS, Xcode, simulator runtime, and Claude Desktop versions that passed your own checks.

You also need a project that Xcode can build for an available simulator. Signing a build for a physical device is a separate path and is not required merely to run an ordinary simulator target.

Before involving Claude, open Xcode and then Apple's Simulator app once. If Xcode has no iOS runtime, install the iOS platform in Xcode's settings or use Anthropic's documented fallback:

xcodebuild -downloadPlatform iOS

Let the download finish, then reopen Simulator and Claude Desktop. Our broader Claude Code workflows guide covers local-session and worktree behavior outside this simulator-specific setup.

Set up the simulator pane

There is no feature flag or launch command for the pane. Use the shortest observable setup path:

1. In Claude Desktop, open the Code surface and start a local session in the iOS project's directory.
2. Check Claude → Check for Updates. Restart after updating and confirm the app is v1.24012.0 or later.
3. Start with Manual mode so the initial build and URL permission boundaries are visible.
4. Ask for an explicit simulator goal, including the device when it matters: Build the app for the iPhone SE simulator, launch it, and tap through the signup flow. Stop after reporting what you observed.
5. Approve the build if prompted. The first time Claude tries to control that simulator device, review the separate device-consent prompt.

The pane opens automatically when Claude launches the app. You can also open Views → iOS Simulator after the session has attached a simulator or edited Swift files. If no device appears, choose Attach simulator or select a device from the device menu. Selecting a shut-down device boots it.

The pane follows the device the app actually launched on. Naming the model in the prompt is more reliable than assuming the currently visible device is the build destination. A simulator that Claude boots also appears in Apple's Simulator app, and Claude can install the app on a simulator that you booted yourself.

Run and inspect the first app

Keep the first run narrow. A single deterministic flow makes it easier to distinguish build trouble, simulator trouble, and app behavior.

Build the Debug scheme for the iPhone SE simulator.
Launch the app and verify only this flow:
1. Open the signup screen.
2. Leave the email field empty and submit.
3. Report the visible validation message.
Do not change code yet. Stop and ask before opening any external URL.

For a successful run, expect the selected simulator to boot, the app to install and launch, and the pane to display the same device. Watch what happens instead of treating Claude's summary as the test record. If Claude takes control, the pane displays a Claude is using this device badge. Avoid tapping until that badge clears; you and Claude operate the same simulated state.

After you reproduce the behavior, give Claude one bounded change and ask it to repeat the same flow. A useful iteration record contains:

• the scheme, simulated device, and OS runtime;
• the exact start state and test steps;
• the expected visible result and the observed result;
• any build or runtime error, without secrets;
• the source diff and the result of rerunning the same flow.

You can click and drag to tap or swipe, use the device menu to switch simulators, and use the pane controls for rotation, Home, lock, volume, screenshots, and recordings. Anthropic documents Cmd+S for a screenshot and Cmd+R for a recording; files are saved to the Desktop. Treat captured app data as test evidence with the same confidentiality rules as screenshots made elsewhere.

Permissions and trust boundary

Simulator consent and the session's general permission mode cover different actions. Keeping them separate avoids approving more than the test needs.

Do not sign in to real accounts or seed a Claude-controlled simulator with production credentials. Use synthetic users, development endpoints, and disposable test data. Device consent lets Claude control only that simulated device, but the build process can still execute repository build scripts on the Mac, and URLs can cross the device boundary.

The dedicated pane does not require the macOS Accessibility and Screen Recording permissions used by general computer use. That narrower OS boundary is useful, but it is not a sandbox for the repository. Session permissions, reviewable diffs, safe build scripts, and ordinary secret handling still matter. The controls in our Claude Code best-practices guide remain applicable.

Parallel sessions do not share a device. Anthropic says each device belongs to the session that launched it, and each session can have up to four simulator panes. Switching sessions switches the simulator view. This separation reduces accidental state sharing, but each session still operates against files and services available to its own environment.

A defensible testing workflow

Use the pane for fast, reviewable UI loops rather than an open-ended request to “test everything.”

1. Define one flow. Name the start state, simulated device, steps, and expected visible behavior.
2. Observe the failing state. Have Claude launch and reproduce before editing. Take a screenshot when it will help compare the result.
3. Review the proposed change. Keep edits small enough to connect a behavior change to a diff.
4. Reset state deliberately. Relaunch, clear test data, or navigate back to the same start screen. A reused simulator preserves state that can hide a defect.
5. Repeat the exact flow. Ask Claude to report observed UI state, build failures, and unresolved uncertainty separately.
6. Run deterministic checks. Unit tests, UI tests, static analysis, and CI remain better evidence for assertions that can be automated.
7. Escalate to the right environment. Move hardware, performance, accessibility, release, and production risks to the tools that can actually measure them.

Lowering the pane's Frame rate or Resolution, switching Encoding between H.264 and JPEG, or displaying FPS changes the video stream, not the app's execution. A smoother or rougher stream is therefore not app-performance evidence.

For a larger release process, integrate these simulator observations into the repeatable checks described in our Claude Code QA app guide. The pane can make reproduction quicker; it should not become the only record of whether a release passed.

What simulator testing cannot prove

Apple's simulated and physical device guidance says simulators help debug across hardware configurations but do not reproduce all physical-device features or performance. Anthropic also states that Claude's simulator tools cannot control a physical iPhone or iPad.

Apple's Accessibility Inspector documentation describes audits for issues such as missing labels, clipping, text size, and contrast. A Claude-driven visual pass is not equivalent. Likewise, Apple's performance guidance calls for measurement and profiling, with higher-fidelity data from a physical device. The launch image's visible FPS control measures the pane's received stream, not application frame timing.

For release validation, App Store Connect's upload guide documents a separate build, upload, processing, testing, and review path. A successful simulator run does not validate signing, entitlements, distribution packaging, privacy declarations, or App Review compliance.

Troubleshooting common failures

If the project itself fails to build, read the Xcode or xcodebuild error before resetting simulators. Reinstalling a runtime will not fix a missing scheme, compile error, package-resolution failure, or incompatible deployment target.

Verification checklist

Run this acceptance check before making the pane part of team QA:

• [ ] Record Claude Desktop, macOS, Xcode, and selected iOS runtime versions.
• [ ] Confirm the session is local and the Desktop version is v1.24012.0 or later.
• [ ] Open Apple's Simulator app independently and confirm at least one iOS device exists.
• [ ] Build and launch a known project on a specifically named simulator.
• [ ] Confirm the pane's device name and OS match the requested target.
• [ ] Review the one-time device consent and separately observe the build permission decision.
• [ ] Reproduce one flow from a defined start state before changing code.
• [ ] Make one bounded change, review the diff, reset state, and repeat the same flow.
• [ ] Confirm screenshots contain no credentials or production user data before Claude captures them.
• [ ] Run the project's deterministic tests and CI checks outside the visual flow.
• [ ] Schedule physical-device, accessibility, performance, distribution, and production checks according to the release risk.
• [ ] Test detach, immediate shutdown, and the chosen access-disable path.

A pass means the integration works for the recorded configuration and flow. It does not generalize to every device, OS, user state, or release condition.

Detach, disable or roll back

Choose the control that matches the intended result:

Declining the first device prompt is also a safe manual-only choice: the simulator still boots and the developer can operate it, while Claude's access remains off. If access is later appropriate, use Let Claude use it in the pane.

Detaching is not a privacy reset. Simulator app state, screenshots saved to the Desktop, build products, conversation records, and any data already sent through a URL or to Anthropic need their own cleanup according to the team's retention policy.

Use it or wait

Use the beta when a Mac-based team already builds locally with Xcode and wants a faster, observable loop for bounded simulator flows. It is especially useful for reproducing a visible state, reviewing a small UI change, and rerunning the same interaction without moving between the conversation and Simulator windows.

Use it with manual control when the side-by-side view helps but device screenshots or autonomous taps cross the project's trust boundary. Decline Claude's device access and operate the pane yourself.

Wait or keep it out of required QA when the workflow depends on cloud or SSH sessions, managed policy disables the integration, or the team cannot separate synthetic simulator data from real credentials. In every case, keep physical-device, accessibility, performance, distribution, and production gates outside the beta's definition of done.

Official sources

Anthropic and Claude documentation

• Claude Developers launch thread — July 21, 2026 announcement, public-beta status, official 3840×2160 launch image, macOS and Xcode framing
• Test iOS apps in the simulator — current requirements, setup, controls, consent, managed disablement, limitations, troubleshooting, and shutdown behavior
• Use Claude Code Desktop — local-session workflow, permission modes, worktrees, and distinction from general computer use
• Computer use from the CLI — separate CLI path for operating Apple's visible Simulator app
• Configure permissions — session permission modes and managed policy context

Apple platform documentation

• Running apps on simulated or physical devices — simulator benefits, missing hardware behavior, and the need for physical-device checks
• Improving app performance — measurement, Instruments, and higher-fidelity device profiling
• Accessibility Inspector — accessibility inspection and audit scope
• Uploading builds to App Store Connect — upload, processing, testing, and release workflow beyond a simulator build