simulator-use

simulator-use

The fastest, most token-efficient way for an AI agent to use the iOS Simulator. simulator-use gives Claude Code, Codex, Cursor and any other MCP client a phone: it builds and runs your Xcode project, reads the screen as a few lines of text, taps and types by label, and runs your tests case by case. Its own native engine talks to the Simulator directly, so reading the whole screen takes about 250 ms and a tap goes out in under a millisecond, where tools that start a helper for every call take 1.5 to 3 seconds. Free and open source (MIT), on any Mac with Xcode, and from Linux, Windows or a Mac without Xcode through a cloud iPhone.

• Fast: a whole-screen read in about 250 ms, a tap sent in under 1 ms, a screenshot in about 60 ms (measured on an M6 Mac mini, October 2026).
• Token-efficient: one line per element the agent can use, nothing else; a dozen tools with short descriptions.
• Complete: build, install, launch, XCTest and XCUITest per case, logs and crashes, video, permission prompts, in-app purchases, iPhone and iPad.
• Continuously improved: weekly releases driven by thousands of daily sessions.
• Anywhere: npx simulator-use cloud start gives a cloud iPhone with Xcode to any machine.

It builds, runs and tests Xcode projects, reads and uses the screen of any app (SwiftUI, UIKit, React Native), answers iOS's permission prompts, reads the app's logs and crashes, and records video.

What the agent sees

Demo · Sign In · iPhone 17 Pro (iOS 27.0)

textfield "Email" #email @201,194 securefield "Password" #password @201,246 switch "Remember me" #remember off @341,298 button "Sign In" #signIn @201,350 text "Not signed in" #status @201,402 tabs: Login (selected) @158,822, Items @244,822

• One line per element: kind, label, #id (the app's accessibility identifier), state and @x,y, the center in points.
• Groups, icons inside buttons, scroll bars, the status bar and the keyboard's keys are folded away. The tab bar, scrolling and the keyboard are one line each.
• Only what can be tapped is listed. An alert, a sheet, a menu or a full-screen view in front hides the screen behind it, and iOS's own permission prompts read as alerts over the app. Rows under the navigation bar, the tab bar or the keyboard are counted as hidden (above, below, to the left or right), not listed.
• A web view in UIKit (Capacitor, React Native's WebView, a sign-in page inside most apps) is read point by point, and its headings, texts, fields, checkboxes, buttons and links are listed like the rest. Web views hosted by SwiftUI, Safari's own pages, in-app browsers, maps, games and iOS's out-of-process pickers have nothing for accessibility to read. They come back as one unreadable line with their place, so the agent knows to take a screenshot and tap by point.
• A screenshot, when asked for, is sized to points, so a point in the picture is a point to tap. screenshot_file saves the screen at full resolution as a PNG for a person, a report or the App Store; in cloud mode it is saved on your machine too. Either waits for the screen to hold still (up to 2 s), so it shows the screen, not an animation into it.
• The sign-in screen above is about 70 tokens. The full accessibility tree it comes from is about 40,000.

Using the screen

ui_act takes steps in the same words ui_look prints, runs them in order, and answers with what changed:

ui_act steps: ["fill #email gary@example.com", "fill #password secret1", "tap #signIn", "wait \"Welcome\""]

4 steps done in 4.5 s changed: #email "gary@example.com" · #password "•••••••" · #status "Welcome, gary@example.com"

Steps:

Every step is checked, so nothing succeeds silently:

• Typed text is read back from the field. When iOS's autocorrect or smart punctuation changes it (-- to —, ' to ’), the text is pasted instead, which iOS takes as is. A field that still shows something else stops the call and says what it shows.
• Text in any language (Café, 日本語, emoji) can be typed: what a US keyboard lacks goes through the Simulator's clipboard.
• fill refuses anything that isn't a text field, so keys never land in whichever field still has focus.
• A tap that changes nothing is reported, after waiting 2.5 s for late answers such as a permission prompt. A tap inside an area that can't be read says it can't be checked.
• A target that isn't on screen yet gets two seconds to appear, then fails with the next step: "2 elements are below: scroll down", or, when an alert came up in front, "Answer it first: tap "Cancel" or "Open"".
• The first failing step stops the rest and returns the screen as it is now.
• A new screen comes back whole; otherwise only what changed.

Tools

The MCP server and the CLI are built from one list, so they always match. The tool list and instructions stay under 4,000 tokens; a test enforces it.

Build and run

app_run does the whole loop in one call: it finds the project (a workspace first, then a project, an XcodeGen spec, or ios/), picks the scheme, builds for the Simulator, installs, launches, and answers with the first screen.

The app's permissions are granted when it is installed and its first launch's prompts (notifications too) are answered, so no prompt stops the agent; permissions: "ask" keeps iOS's prompts, to test them. open_url answers iOS's "Open in …?" for a link that opens another app.

Built Demo in 4.2 s, installed dev.simtap.demo.

Launched Demo in 3.9 s. Demo · Sign In · iPhone 17 Pro (iOS 27.0) textfield "Email" #email @201,194 ...

• A failed build answers with the errors only, as Sources/App.swift:49:37: error: ..., and the path to the full log.
• Each folder (each git worktree) builds into its own DerivedData, so rebuilds are incremental and worktrees never share products. SIMULATOR_USE_CACHE_DIR puts it on a disk you keep, so the next machine's build is incremental too.
• An XcodeGen project is regenerated from project.yml before each build (skipped when nothing changed), so new files are always in it.
• The next call in the same folder needs no arguments.
• env: "API_URL=http://127.0.0.1:8080 MODE=test" gives the app those variables (it reads them from ProcessInfo), as an Xcode scheme does; they stay for its later launches, and env: "" clears them.
• An MCP call answers within 40 s; a longer build answers with a job, and job_status waits for it. From the CLI, simulator-use run simply waits.
• Two builds of one project never run at once, also from two processes: the second says which process is building it.
• Expo, React Native, Flutter and Capacitor builds are not done yet; build them with their own tools, then app_control install.

Tests

tests_run runs the scheme's tests and reads the answer from Xcode's result bundle, not from the scrolling output:

Tests failed: 1 passed, 2 failed (3 in 35.3 s). Result bundle: .../tests-1792370825323.xcresult

DemoTests/SignInTests/testRejectsAShortPassword(): Tests/SignInTests.swift:12: XCTAssertEqual failed: ("Welcome, gary@example.com") is not equal to ("Invalid email or password") DemoTests/rejectsAnEmailWithoutAt(): Tests/SignInTests.swift:18: Expectation failed: ...

• XCTest and Swift Testing both.
• Each failing test is named the way only takes it, to rerun just that one.
• "0 tests ran" (no test target, or a filter that matched nothing) is an error, never a pass.

In-app purchases

The App Store's sandbox cannot complete a purchase in a Simulator (Apple: purchases there need a device; signing in fails with AMSErrorDomain). StoreKit Testing can, and app_control storekit applies the app's .storekit file the way Xcode's Run does, with no Xcode window and no change to the app:

simulator-use app storekit Products.storekit   # the app launched last; app_control {action: "storekit", value: "Products.storekit", app: "com.example.app"}

simulator-use app launch # the app loads the file's products, and purchases complete at once simulator-use app storekit clear # back to the App Store

• Products, purchases, subscriptions and renewals are local (environment Xcode), with no Apple Account.
• Applying starts from the file's state: its products, no purchases. Purchases complete without iOS's purchase sheet, which is not in the app's accessibility tree.
• It lasts until the app is removed: building and installing over it keeps it.
• A relative path is looked up here, then in the folder of the project app_run built last (on a cloud phone, the uploaded project).

Any screen, and its screenshot

An app opens any screen without tapping through it when it reads launch arguments: -Key value sets Key in UserDefaults for that launch only, like the "Arguments Passed On Launch" of an Xcode scheme.

simulator-use app launch com.example.app -Onboarding 3 -Demo YES   # app_control {action: "launch", value: "-Onboarding 3 -Demo YES"}

simulator-use look --out shots/onboarding-3.jpg # sized to points (402x874 on an iPhone 17 Pro), to read simulator-use look --out store/onboarding-3.png # full resolution, for the App Store

• The words after the app are its arguments, quoted as in a shell: -Greeting "Hello there"