# Claude Code iOS Simulator: Setup, Testing and Limits

> Set up Claude Code Desktop's iOS Simulator, manage permissions, test a first app, troubleshoot failures, and understand the beta's limits.

- **Published**: 2026-07-22
- **Category**: AI Infrastructure
- **URL**: https://agentpedia.codes/blog/claude-code-ios-simulator-guide

---

> **Important callout**

**Bottom line:** Claude Code Desktop can build, install, launch, view, and interact with an iOS app in a side-panel simulator on a Mac. The public beta requires Claude Desktop v1.24012.0 or later, Xcode with the iOS platform installed, and a local session. Keeping the simulator beside the conversation can reduce window switching during UI iteration, but it does not replace testing on physical devices, App Store validation, Instruments, accessibility evaluation, or production QA.

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](https://x.com/ClaudeDevs/status/2079674432038248611)

Anthropic's [follow-up in the official thread](https://x.com/ClaudeDevs/status/2079674433854452046) 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](https://code.claude.com/docs/en/desktop-ios-simulator) 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](https://code.claude.com/docs/en/computer-use#test-a-simulator-flow). 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:

| Requirement | Documented baseline | Why it matters |
| --- | --- | --- |
| Claude Desktop | v1.24012.0 or later | Earlier builds do not provide this pane |
| Host | A Mac running macOS | Apple's iOS Simulator is not available on Windows or Linux |
| Apple tooling | Xcode with the iOS platform installed | Xcode supplies simulator runtimes and devices; Claude Desktop does not bundle them |
| Session | Local Claude Code Desktop session | Cloud and SSH sessions cannot reach simulator devices on the local Mac |

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:

```bash
xcodebuild -downloadPlatform iOS
```

Let the download finish, then reopen Simulator and Claude Desktop. Our broader [Claude Code workflows guide](/blog/claude-opus-4-8-claude-code-workflows) 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.

```text
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.

| Action | Approval boundary | Practical consequence |
| --- | --- | --- |
| You tap in the pane | No Claude device consent required | Declining Claude access still leaves the pane interactive for you |
| Claude taps, types, launches, or captures a device | One consent per simulator device | Later control on that device runs without another device prompt |
| Build with `xcodebuild` | Current session permission mode | Project build scripts execute on the Mac, not inside the simulated device |
| Open a URL in the simulator | Current session permission mode | A deep link or Safari URL can send data off the device |
| Screenshot used by Claude | Covered by device consent | Anthropic says screenshots are sent to Anthropic and follow normal conversation retention |

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](/blog/claude-code-best-practice-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](/blog/qa-app-with-claude-code). 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](https://developer.apple.com/documentation/Xcode/running-your-app-on-simulated-or-physical-devices) 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.

| Question | What the pane can establish | What still needs separate validation |
| --- | --- | --- |
| Does this UI flow render and respond in this simulated configuration? | Claude or a developer can observe and operate the flow | Repeat on other supported sizes, orientations, OS versions, locales, and state combinations |
| Does it work on real hardware? | Nothing conclusive | Run from Xcode on representative iPhones or iPads, including hardware-dependent features |
| Is the app fast and power-efficient? | Obvious stalls may suggest where to investigate | Profile with Xcode and Instruments, preferably on devices; Apple says device profiling gives higher-fidelity measurements |
| Is the app accessible? | A visible flow may reveal some layout problems | Use Accessibility Inspector, accessibility audits, VoiceOver, Dynamic Type, contrast checks, keyboard or switch paths, and testing with users where appropriate |
| Is the build ready for App Store review? | A debug simulator build may compile and launch | Archive, validate, upload, process in App Store Connect, test distribution such as TestFlight, metadata review, and Apple's App Review remain separate |
| Is the release production-ready? | One bounded path can pass | Automated regression coverage, backend behavior, security, privacy, observability, rollback, release controls, and human sign-off remain necessary |

Apple's [Accessibility Inspector documentation](https://developer.apple.com/documentation/Accessibility/accessibility-inspector) 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](https://developer.apple.com/documentation/xcode/improving-your-app-s-performance/) 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](https://developer.apple.com/help/app-store-connect/manage-builds/upload-builds) 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

| Symptom | Likely cause | Next action |
| --- | --- | --- |
| The pane never opens | The request did not clearly ask to run the app, tooling is missing, policy disabled it, or Desktop is too old | Ask explicitly to run and test in iOS Simulator; open Simulator yourself; update and restart Desktop |
| **No simulators were found** | Xcode has no installed iOS runtime | Install the iOS platform in Xcode settings or run `xcodebuild -downloadPlatform iOS` |
| The session can edit but cannot attach a Mac simulator | It is a cloud or SSH session | Start a local Desktop session in the project directory |
| The pane works for your taps but Claude cannot control it | Device consent was declined or simulator access is disabled | Use **Let Claude use it** in the pane if policy permits, or keep manual control |
| A build prompts even after device consent | Builds follow the session permission mode | Review the `xcodebuild` action and project scripts; device consent does not approve shell execution |
| A deep link prompts even after device consent | Opening a URL follows the session permission mode | Inspect the destination and data in the URL before approving |
| The wrong simulated model launches | The prompt did not name a target or the scheme selected another destination | Name the required device explicitly and verify the device label in the pane |
| Video is choppy while the app seems responsive | Stream settings or Mac load may be the bottleneck | Lower frame rate or resolution, try the other encoding, and avoid treating pane FPS as app performance |
| Manual taps make Claude's result inconsistent | Both actors changed the same device state | Wait for the **Claude is using this device** badge to clear, reset the flow, and rerun |
| The pane or tools are unavailable on a managed Mac | `disableMobileSimulatorTools` or an isolated-VM policy may apply | Ask the administrator which policy is set; Claude reports when either restriction applies |

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:

| Goal | Documented action | Result |
| --- | --- | --- |
| Stop the video stream but keep the device running briefly | Click **Detach simulator** | The pane returns to **Attach simulator**; a Claude-booted device shuts down after 10 minutes if unused |
| Shut down the attached simulator now | Use the pane's shutdown button | The attached simulated device stops immediately |
| End Claude-booted devices with the session | Quit Desktop or archive the session | Claude Desktop shuts down simulators that it booted |
| Preserve a device you started yourself | Boot it from the pane or Apple's Simulator app | Anthropic says user-booted devices are not shut down automatically |
| Revoke Claude's simulator capability | Turn off simulator access in Desktop settings | Claude can no longer operate simulator devices |
| Block Claude control across an organization | Set managed `disableMobileSimulatorTools` | Claude's tools are blocked; developers can still use the pane manually |
| Disable the pane and tools entirely | Require sessions to run in an isolated virtual machine | The dedicated simulator integration is unavailable |

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.

## FAQ

### What version of Claude Desktop supports the iOS Simulator pane?

Anthropic's documentation requires Claude Desktop v1.24012.0 or later. The feature also requires macOS, Xcode with the iOS platform installed, and a local Claude Code Desktop session.

### Does Claude Code's iOS Simulator work on Windows or Linux?

No. Anthropic documents the dedicated simulator pane as macOS-only because it uses Apple's simulator tooling supplied by Xcode. Claude Code Desktop itself may support other platforms, but this iOS pane does not.

### Can Claude Code test an iOS app on a physical iPhone or iPad?

Not through the simulator tools. Anthropic says they control simulated devices only. Run the app on physical hardware through Xcode yourself, then describe the result or attach a screenshot if you want Claude to help diagnose it.

### Why does Claude Code say that no iOS simulators were found?

Xcode may be installed without an iOS simulator runtime. Install the iOS platform in Xcode's settings or run xcodebuild -downloadPlatform iOS, then confirm Apple's Simulator app opens before retrying the local Desktop session.

### Does the simulator pane require Claude computer use permissions?

No. The dedicated Desktop pane controls the simulated device directly and does not require macOS Accessibility or Screen Recording access. Claude still asks once per simulator device before it may control that device and capture its screenshots.

### Can the simulator pane be used in cloud or SSH sessions?

No. Anthropic documents the pane as local-session only because cloud and SSH sessions cannot reach the simulator devices on the Mac running Claude Desktop.

### How do I stop Claude from controlling the iOS Simulator?

Turn off simulator access in Claude Desktop settings. An administrator can set disableMobileSimulatorTools to block Claude's simulator tools for everyone while leaving the pane available for manual interaction; an isolated-VM policy disables both the pane and tools.


---

[Join the Agentpedia newsletter](https://agentpedia.codes/blog)
[Browse related Agentpedia articles](https://agentpedia.codes/blog)

## Official sources

### Anthropic and Claude documentation

- [Claude Developers launch thread](https://x.com/ClaudeDevs/status/2079674432038248611) -- July 21, 2026 announcement, public-beta status, official 3840x2160 launch image, macOS and Xcode framing
- [Test iOS apps in the simulator](https://code.claude.com/docs/en/desktop-ios-simulator) -- current requirements, setup, controls, consent, managed disablement, limitations, troubleshooting, and shutdown behavior
- [Use Claude Code Desktop](https://code.claude.com/docs/en/desktop) -- local-session workflow, permission modes, worktrees, and distinction from general computer use
- [Computer use from the CLI](https://code.claude.com/docs/en/computer-use#test-a-simulator-flow) -- separate CLI path for operating Apple's visible Simulator app
- [Configure permissions](https://code.claude.com/docs/en/permissions) -- session permission modes and managed policy context

### Apple platform documentation

- [Running apps on simulated or physical devices](https://developer.apple.com/documentation/Xcode/running-your-app-on-simulated-or-physical-devices) -- simulator benefits, missing hardware behavior, and the need for physical-device checks
- [Improving app performance](https://developer.apple.com/documentation/xcode/improving-your-app-s-performance/) -- measurement, Instruments, and higher-fidelity device profiling
- [Accessibility Inspector](https://developer.apple.com/documentation/Accessibility/accessibility-inspector) -- accessibility inspection and audit scope
- [Uploading builds to App Store Connect](https://developer.apple.com/help/app-store-connect/manage-builds/upload-builds) -- upload, processing, testing, and release workflow beyond a simulator build


---

- [All articles](https://agentpedia.codes/blog)