4 ファイル変更+175-10
この更新の概要
macOS版Claude Code Desktopに、iOSシミュレーターを専用ペインで操作・確認できる新機能が追加されました。これに伴い、CLI版では従来通りComputer Use（画面操作）を介してシミュレーターにアクセスし、デスクトップアプリ版では専用ペインを通じて効率的にアプリのテストやビルド状況の確認を行う仕組みが整理されています。また、プレビュー設定におけるカスタムURLの指定方法や、モデルのフォールバック動作におけるコンテキストウィンドウの制限など、実行構成とモデル選択に関する詳細仕様が更新されました。
@@ -31,7 +31,7 @@ Claude has several ways to interact with an app or service. Computer use is the
- If the task is browser work and you have [Claude in Chrome](/docs/en/chrome) set up, Claude uses that.
- If none of those apply, Claude uses computer use.
Screen control is reserved for things nothing else can reach: native apps, simulators, and tools without an API.
Screen control is reserved for things nothing else can reach: native apps, simulators, and tools without an API. In the Desktop app, running or testing an iOS app opens the dedicated [iOS Simulator pane](/docs/en/desktop-ios-simulator) rather than screen control; from the CLI, computer use is how Claude reaches the iOS Simulator.
## Enable computer use
@@ -158,7 +158,7 @@ Open the iOS Simulator, launch the app, tap through the onboarding
screens, and tell me if any screen takes more than a second to load.
```
Claude controls the simulator the same way you would with a mouse.
Claude controls the simulator the same way you would with a mouse. This flow applies to the CLI; in the Desktop app, the same request opens the [iOS Simulator pane](/docs/en/desktop-ios-simulator) instead of screen control.
## Differences from the Desktop app
デスクトップアプリ専用のiOSシミュレーターペインの利用要件、対話的な操作方法、セッション管理、アクセス権限の設定に関する詳細なガイドラインが新規作成されました。
@@ -0,0 +1,122 @@
---
title: desktop-ios-simulator
source: https://code.claude.com/docs/en/desktop-ios-simulator.md
---
# Test iOS apps in the simulator
> Claude Code Desktop opens your app in the iOS Simulator pane when Claude builds, runs, or checks it, with a separate simulator for each session.
The iOS Simulator pane is in public beta in Claude Code Desktop on macOS.
The iOS Simulator pane shows your app running in Apple's iOS Simulator next to your conversation in Claude Code Desktop. When Claude builds, installs, launches, or checks your app in a simulator, the pane opens automatically and streams the device screen live. Use it to watch Claude run and test your app, or to tap through the app yourself while Claude keeps working.
The pane drives the simulator directly, so it doesn't need [computer use](/docs/en/desktop#let-claude-use-your-computer) and never takes over your screen or hides your other windows. From the CLI, Claude reaches the iOS Simulator through [computer use](/docs/en/computer-use#test-a-simulator-flow) instead, which controls the simulator on your screen the same way you would with a mouse.
## Requirements
The pane uses Apple's simulator tooling, which the desktop app doesn't include. Before starting a session, make sure you have:
- macOS: the iOS Simulator doesn't run on Windows or Linux
- [Xcode](https://developer.apple.com/xcode/) with the iOS platform installed, which provides the simulator devices; if Xcode has none yet, see [The pane says no simulators were found](#the-pane-says-no-simulators-were-found)
On this page, the word device refers to a simulated iPhone or iPad, one of the same simulator devices you manage in Xcode under **Window → Devices and Simulators**, not physical hardware.
The pane is available in local sessions only. In [cloud](/docs/en/desktop#run-long-running-tasks-remotely) and [SSH](/docs/en/desktop#ssh-sessions) sessions, Claude runs on a machine that can't reach the simulators on your Mac.
## Run your app in the simulator
You don't need a command or setting to use the pane. Claude opens it when it runs your app in a simulator.
In Claude Code Desktop, open the **Code** tab and start a session with your app's project as the [project folder](/docs/en/desktop#start-a-session). Any project that builds an app for the iOS Simulator works.
Phrase the task around running or verifying the app. For example:
```text theme={null}
Build the app and run it in the simulator to check the onboarding flow.
```
When the app launches in a simulator, the iOS Simulator pane opens next to the conversation. The first time Claude uses a device, the desktop app asks you to allow it; see [Grant Claude access to a device](#grant-claude-access-to-a-device). Claude installs the app, taps through it, and reads the screen to verify its own changes while you watch.
The pane opens whenever Claude launches the app in a simulator, at any point in the session. When your request is about seeing the app, for example "does the new screen look right?", Claude starts a simulator before it begins the work. After Claude fixes a bug or changes a screen, ask it to verify the change: relaunching the app reopens the pane if it isn't open.
The pane shows whichever simulator the app actually launched in. To test on a specific device, name it in your request, for example "run it on the iPhone SE simulator", and Claude targets that device when it builds and launches.
A device Claude boots also appears in Apple's Simulator app, and Claude can install the app on a device you already have booted.
You can also open the pane yourself. Once the session has a simulator attached or has edited Swift files, the **Views** menu in the session toolbar shows an **iOS Simulator** entry. If the pane isn't showing a device yet, click **Attach simulator**, or pick a specific device from the device menu next to it; picking a shut-down device boots it. If Xcode or its simulators are missing, the pane shows the setup steps instead and checks them off as you complete them.
## Control the simulator yourself
The pane is interactive, not only a viewer. While Claude works, or between tasks, you can:
- Tap and swipe by clicking and dragging on the device screen
- Press hardware buttons with the same shortcuts as Apple's Simulator app: **Cmd+Shift+H** for Home, **Cmd+L** to lock, **Cmd+Up Arrow** and **Cmd+Down Arrow** for volume
- Rotate the device a quarter turn clockwise with the rotate button or **Cmd+Right Arrow**
- Switch which device the pane shows from the device menu, which lists each simulator's OS version and whether it's booted
- Save a screenshot with **Cmd+S** or a screen recording with **Cmd+R**, using the pane's capture buttons or the shortcuts; the files are saved to your Desktop
- Stop streaming a device without shutting it down by clicking **Detach simulator**, which returns the pane to its **Attach simulator** state
The row under the device name tunes the video stream from the simulator. Lower **Frame rate** or **Resolution** if the pane strains your Mac, switch **Encoding** between H.264 and JPEG, or check **FPS** to display the frame rate the pane is receiving. These settings change how the pane displays the device, not how the app runs.
You and Claude drive the same device, so your taps change the app state Claude sees. To have Claude check a specific screen, navigate to it by tapping, then ask. While Claude is driving the device, the pane shows a **Claude is using this device** badge above the screen; hold off tapping until the badge clears, so the result reflects the app rather than your input.
## How sessions manage devices
Each device belongs to the session that launched it, so [parallel sessions](/docs/en/desktop#work-in-parallel-with-sessions) don't share a device: what you see in one session's pane reflects that session's work, not another's. Switching sessions in the sidebar switches the simulator view along with the conversation, and switching back resumes the same device where it left off. If Claude works with more than one device, each opens its own pane, up to 4 per session.
Claude Code Desktop shuts down the simulators it booted once they're no longer in use: when you quit the app, when you archive the session, or 10 minutes after you detach a device from its pane. Devices you boot yourself, whether from the pane or in Apple's Simulator app, are never shut down automatically. To shut down the attached device right away, use the shutdown button in the pane.
## Grant Claude access to a device
Claude asks for your consent before it controls a device, while building the app or opening a URL on it follows your session's permission mode. You or your organization can also turn Claude's access off entirely.
### Allow a device the first time
The first time Claude uses a simulator, the desktop app asks you to allow it. The consent covers controlling that device and taking screenshots of it, and you give it once per device rather than once per session. Claude's screenshots of the device are sent to Anthropic and kept under your normal conversation retention settings, so don't sign in to real accounts on a device Claude uses.
After you allow a device, Claude's actions on it, such as tapping, typing, launching the app, and taking screenshots, run without further prompts. They carry the same trust as you clicking in the pane, and they only touch the simulated device, so the pane doesn't need the macOS Accessibility and Screen Recording permissions that computer use requires.
If you decline, the device still boots and the pane still works for your own taps; only Claude's access stays off. To change your mind later, click **Let Claude use it** in the pane.
### Actions that follow your permission mode
Two actions follow your session's [permission mode](/docs/en/permissions#permission-modes) instead of the one-time consent:
- Opening a URL on the device, for example to test a deep link or load a page in the device's Safari, because a URL can carry data off the device.
- Building the app, because `xcodebuild` runs your project's build scripts on your Mac. Checking on a build already in progress doesn't prompt.
### Turn off simulator access
You can turn Claude's simulator access off in the desktop app's settings. Organizations have two ways to turn it off for everyone:
- The `disableMobileSimulatorTools` [managed setting](/docs/en/desktop#managed-settings) blocks Claude's simulator tools. The pane stays usable for your own taps, and the setting can't be overridden from within the app.
- A policy that requires sessions to run inside an isolated virtual machine disables the pane and the tools entirely.
Claude tells you when either applies.
## Limitations
The pane works with simulators only: Claude can't drive a physical iPhone or iPad. To test on one, run the app on it from Xcode yourself, then describe what you see or attach a screenshot to the conversation for Claude to work from.
## Troubleshooting
### The pane doesn't open when Claude runs the app
Claude may not have recognized that you wanted to run or test the app, or the simulator tooling may be missing. Check the following:
- State the goal explicitly, for example "run the app in the iOS Simulator and tap through the signup flow".
- Confirm Xcode and the iOS Simulator are installed by launching the Simulator app on its own.
- If your organization manages Claude Code, the [simulator tools may be disabled by policy](#turn-off-simulator-access).
- The pane requires a recent desktop version. Open **Claude → Check for Updates**, then restart the app.
### The pane says no simulators were found
Xcode is installed but has no iOS simulators to list. The pane shows the setup steps to follow and checks them off as each one completes. To install the missing piece manually, download the iOS simulator runtime from Xcode's settings, or run `xcodebuild -downloadPlatform iOS`.
## See also
- [Computer use in Desktop](/docs/en/desktop#let-claude-use-your-computer): screen control for apps without a dedicated pane
- [Computer use from the CLI](/docs/en/computer-use): how the CLI reaches the iOS Simulator
- [Work in parallel with sessions](/docs/en/desktop#work-in-parallel-with-sessions): how sessions isolate changes
- [Get started with Claude Code Desktop](/docs/en/desktop-quickstart)
@@ -23,6 +23,7 @@ In the Code tab, each conversation is a **session**: it has its own chat history
- [Review and comment on diffs](#review-changes-with-diff-view), then [watch the resulting PR through CI](#monitor-pull-request-status)
- [Preview your running app](#preview-your-app) in the Browser pane while Claude verifies its own changes, and [open external sites](#browse-external-sites) alongside it
- Watch Claude [run and test your iOS app](/docs/en/desktop-ios-simulator) in the iOS Simulator pane
- [Arrange panes](#arrange-your-workspace) for the chat, diff, browser, terminal, and file editor side by side
- Ask a [side question](#ask-a-side-question-without-derailing-the-session) that uses the session's context without derailing it
- [Connect external tools](#connect-external-tools) like GitHub, Slack, and Linear
@@ -162,7 +163,7 @@ PR monitoring requires the [GitHub CLI (`gh`)](https://cli.github.com/) to be in
## Arrange your workspace
The Code tab is built around panes you can arrange in any layout: chat, diff, browser, terminal, file, plan, tasks, and subagent. Drag a pane by its header to reposition it, or drag a pane edge to resize it. Press **Cmd+\\** on macOS or **Ctrl+\\** on Windows to close the focused pane. Open additional panes from the **Views** menu in the session toolbar.
The Code tab is built around panes you can arrange in any layout: chat, diff, browser, terminal, file, plan, tasks, and subagent, along with the [iOS Simulator](/docs/en/desktop-ios-simulator) on macOS. Drag a pane by its header to reposition it, or drag a pane edge to resize it. Press **Cmd+\\** on macOS or **Ctrl+\\** on Windows to close the focused pane. Open additional panes from the **Views** menu in the session toolbar.
The pane layout, terminal, file editor, and view modes in this section require Claude Desktop v1.2581.0 or later. Open **Claude → Check for Updates** on macOS or **Help → Check for Updates** on Windows to update.
@@ -229,7 +230,7 @@ Click the usage ring next to the model picker to see your current context window
## Let Claude use your computer
Computer use lets Claude open your apps, control your screen, and work directly on your machine the way you would. Ask Claude to test a native app in a mobile simulator, interact with a desktop tool that has no CLI, or automate something that only works through a GUI.
Computer use lets Claude open your apps, control your screen, and work directly on your machine the way you would. Ask Claude to interact with a desktop tool that has no CLI, or automate something that only works through a GUI. For running and testing iOS apps, Desktop opens the dedicated [iOS Simulator pane](/docs/en/desktop-ios-simulator) instead of controlling your screen; the pane works without enabling computer use.
Computer use is a research preview on macOS and Windows that requires a Pro or Max plan. It is not available on Team or Enterprise plans. The Claude Desktop app must be running.
@@ -244,9 +245,10 @@ Claude has several ways to interact with an app or service, and computer use is
- If you have a [connector](#connect-external-tools) for a service, Claude uses the connector.
- If the task is a shell command, Claude uses Bash.
- If the task is browser work and you have [Claude in Chrome](/docs/en/chrome) set up, Claude uses that.
- If the task is running or testing an iOS app, Claude uses the [iOS Simulator pane](/docs/en/desktop-ios-simulator), which doesn't use screen control.
- If none of those apply, Claude uses computer use.
The [per-app access tiers](#app-permissions) reinforce this: browsers are capped at view-only, and terminals and IDEs at click-only, steering Claude toward the dedicated tool even when computer use is active. Screen control is reserved for things nothing else can reach, like native apps, hardware control panels, mobile simulators, or proprietary tools without an API.
The [per-app access tiers](#app-permissions) reinforce this: browsers are capped at view-only, and terminals and IDEs at click-only, steering Claude toward the dedicated tool even when computer use is active. Screen control is reserved for things nothing else can reach, like native apps, hardware control panels, or proprietary tools without an API.
### Enable computer use
@@ -428,6 +430,7 @@ Each entry in the `configurations` array accepts the following fields:
| `autoPort` | boolean | How to handle port conflicts. See below |
| `program` | string | A script to run with `node`. See [when to use `program` vs `runtimeExecutable`](#when-to-use-program-vs-runtimeexecutable) |
| `args` | string\[] | Arguments passed to `program`. Only used when `program` is set |
| `url` | string | The address the preview opens instead of `http://localhost:<port>`. See [open the preview at a specific URL](#open-the-preview-at-a-specific-url) |
##### When to use `program` vs `runtimeExecutable`
@@ -435,6 +438,45 @@ Use `runtimeExecutable` with `runtimeArgs` to start a dev server through a packa
Use `program` when you have a standalone script you want to run with `node` directly. For example, `"program": "server.js"` runs `node server.js`. Pass additional flags with `args`.
##### Open the preview at a specific URL
By default, the preview opens `http://localhost:<port>`. Set `url` when your server needs a different address. Common cases are servers that require local HTTPS, apps that use `*.localhost` subdomains, and apps that sign you in through a redirect.
```json
{
"version": "0.0.1",
"configurations": [
{
"name": "my-app",
"runtimeExecutable": "npm",
"runtimeArgs": ["run", "dev"],
"port": 8443,
"url": "https://localhost:8443"
}
]
}
```
Localhost addresses open directly, exactly like the default port address. This includes `localhost`, any `*.localhost` subdomain, `127.0.0.1`, and `::1`. For security, a localhost `url` must be just your server's origin — no path or query, and the port must match the entry's port. To show a specific page, ask Claude to navigate there after the preview opens. A localhost `url` with a path, query, or mismatched port is reported as a configuration error that names the url and shows the fix.
Any other address asks for your permission the first time it opens, the same way browsing to a new site in the preview does. External addresses may include paths. Choose **Always allow** to skip the prompt for that site in the future. Organization policies that restrict external sites in the preview still apply.
To preview a server you already run yourself, set `url` without a command. Claude attaches the preview to your running server instead of starting one:
```json
{
"version": "0.0.1",
"configurations": [
{
"name": "my-app",
"url": "https://app.localhost:3000"
}
]
}
```
The `url` must be `http` or `https`, and must not contain a username or password.
#### Port conflicts
The `autoPort` field controls what happens when your preferred port is already in use:
@@ -750,6 +792,7 @@ This table compares core capabilities between the CLI and Desktop. For a full li
| Multiple sessions | Separate terminals | Sidebar tabs |
| Recurring tasks | Cron jobs, CI pipelines | [Scheduled tasks](/docs/en/desktop-scheduled-tasks) |
| Computer use | [Enable via `/mcp`](/docs/en/computer-use) on macOS | [App and screen control](#let-claude-use-your-computer) on macOS and Windows |
| iOS simulator | Drive the simulator via [computer use](/docs/en/computer-use#test-a-simulator-flow) | [iOS Simulator pane](/docs/en/desktop-ios-simulator) opens automatically |
| Dispatch integration | Not available | [Dispatch sessions](#sessions-from-dispatch) in the sidebar |
| Scripting and automation | [`--print`](/docs/en/cli-reference), [Agent SDK](/docs/en/headless) | Not available |
@@ -167,7 +167,7 @@ Excluded models are hidden from the `/model` picker. A full model ID in the list
Model changes that Claude Code makes on your behalf are checked the same way:
- **[Fallback model chains](#fallback-model-chains)**: elements outside the allowlist are dropped
- **[Fallback model chains](#fallback-model-chains)**: entries outside the allowlist are dropped
- **Plan-mode upgrades**: on the Anthropic API and Claude Platform on AWS, an upgrade such as [`opusplan`](#opusplan-model-setting) to an excluded model uses the newest permitted version of the upgrade family. On providers with provider-specific model IDs, and when no version is permitted, the upgrade is skipped and planning continues on the session's model
- **[Automatic model fallback](#automatic-model-fallback)**: a fallback whose target is excluded does not run, so the flagged request ends with a refusal instead
- **[Auto mode classifier](/docs/en/permission-modes#eliminate-prompts-with-auto-mode)**: the classifier's Claude Sonnet 5 default applies only when the allowlist permits Sonnet 5. When it's excluded, the classifier runs on the session's model, which the allowlist already governs, or on an Opus model when the session runs on [Fable 5](#work-with-fable-5). On providers other than the Anthropic API, that Opus fallback runs on the provider's default Opus model without consulting the allowlist. Requires Claude Code v2.1.210 or later
@@ -369,14 +369,14 @@ To persist a chain across sessions, set `fallbackModel` in [settings](/docs/en/s
}
```
The `--fallback-model` flag takes precedence over the `fallbackModel` setting. Each element accepts a model name or alias, and `"default"` expands to the default model.
The `--fallback-model` flag takes precedence over the `fallbackModel` setting. Each entry accepts a model name or alias, and `"default"` expands to the default model.
Claude Code doesn't confirm the chain at startup and `/status` doesn't display it. The notice shown when a switch happens is the first visible sign that a fallback is configured.
Two cases cause an element to be skipped:
When a request fails over, Claude Code tries each entry in order until one accepts it. An entry that can't be reached either, such as a retired model pinned in settings, fails over to the next one the same way. Two kinds of entry are removed before that walk starts:
- **Unavailable model**: a model that can't be reached, such as a retired model pinned in settings, is skipped and Claude Code continues to the next element.
- **Outside the allowlist**: an element not permitted by [`availableModels`](#restrict-model-selection) is dropped when the chain is read and never tried.
- **Outside the allowlist**: any entry not permitted by [`availableModels`](#restrict-model-selection) is dropped when Claude Code reads the chain.
- **Smaller context window during compaction**: the chain also covers [compaction](/docs/en/context-window#what-survives-compaction), but Claude Code won't fall back to a model with a smaller context window than the primary's, since summarizing there would cut off part of the conversation first. If every fallback is smaller, compaction shows the original error and you can retry.
### Automatic model fallback