| name | kuri-ios |
| description | Use kuri-ios to drive iOS Simulators from the CLI — list sims, boot/shutdown, navigate Safari to URLs (openurl), launch and terminate apps by bundle id, capture PNG screenshots, list installed apps, and (on the Simulator only) tap, doubletap, longpress, swipe/pan, and type via native CGEvent into the Simulator window. Real iPhones over USB are supported for listing and launch/terminate via usbmuxd + xcrun devicectl. Tap/swipe/type/uitree on real devices and uitree on the Simulator are NOT supported in v1 (require XCUITest). Multi-touch (pinch, rotate, two-finger pan) and hardware buttons (Home, Lock, Volume) are not wired yet. Trigger phrases include "screenshot the iPhone sim", "tap on iOS simulator", "doubletap iOS sim", "long press iOS sim", "swipe up on iPhone sim", "pan the iOS simulator", "type into iOS simulator", "open Safari on simulator", "launch iOS Settings", "list booted simulators". |
kuri-ios
Drive iOS Simulators (and, where possible, real iPhones) through the
kuri ios subcommand. Implementation lives in
kuri-mobile/src/ios/ and the main kuri binary forwards
kuri ios … to the kuri-mobile binary.
⚠️ Host cursor & keyboard warning. On the Simulator, tap, doubletap,
longpress, swipe/pan, and type post real CGEvents into the macOS
WindowServer — they physically move your mouse pointer and seize keyboard
focus for the duration of the gesture. Do not run them while you are using
the machine, or from an unattended/background job; a stray click lands wherever
the pointer happens to be. Cursor-free, always-safe commands: list-devices,
boot, shutdown, openurl, launch, terminate, list-apps,
screenshot. An isolated input backend that bypasses the host pointer is
tracked in issues #180 and #183.
When to use this skill
-
Boot an iOS Simulator, open Safari to a URL, screenshot the result.
-
Launch or terminate any iOS app by bundle id on the Simulator.
-
List installed apps on the Simulator.
-
Enumerate real iPhones plugged in over USB (via usbmuxd, native Zig).
-
Launch / terminate an app on a real iPhone via xcrun devicectl.
-
Tap, swipe, pan, or type into the booted iOS Simulator (CGEvent posts
into the Simulator.app window; coords are device pixels matching the
screenshot). The first run will trigger a macOS Accessibility prompt
for your terminal — without that permission, taps are silently dropped.
Do not use this skill for:
- Tapping, swiping, typing, or reading UI tree on a real iPhone
(requires XCUITest; intentionally not in v1).
- Reading the UI tree of the iOS Simulator (the macOS AX of Simulator.app
does not expose the iOS app — that path is XCUITest only).
- Running JS inside a page — that's a browser task, use kuri-agent.
- Android — use the
kuri-android skill instead.
Prerequisites
- Xcode installed (
xcrun, simctl, devicectl).
- At least one iOS Simulator runtime installed.
xcrun simctl runtime list must show at least one (Ready) entry. If it's empty:
xcodebuild -downloadPlatform iOS (one-time ~7 GB download).
kuri-mobile built and either on $PATH or next to the kuri
binary (zig-out/bin/kuri-mobile).
Build
cd kuri-mobile
zig build
cp zig-out/bin/kuri-mobile ../zig-out/bin/
zig build test
Typical flow
kuri ios list-devices
xcrun simctl create "scratch" com.apple.CoreSimulator.SimDeviceType.iPhone-16 com.apple.CoreSimulator.SimRuntime.iOS-26-4
kuri ios boot --udid <UDID>
kuri ios openurl https://news.ycombinator.com
sleep 3
kuri ios screenshot hn.png
kuri ios launch com.apple.Preferences
sleep 2
kuri ios screenshot settings.png
kuri ios openurl "maps://?q=San%20Francisco"
Full command surface
| Command | Purpose |
|---|
kuri ios list-devices | Sims (from simctl JSON) + real devices (from usbmuxd) |
kuri ios boot --udid <U> | Boot a simulator |
kuri ios shutdown --udid <U> | Shut down a simulator |
kuri ios openurl <url> | Open URL (auto-resolves booted sim). Alias: navigate |
kuri ios launch <bundle-id> | Launch app on booted sim |
kuri ios launch --device --udid <U> <bundle-id> | Launch on real iPhone via devicectl |
kuri ios terminate <bundle-id> | Kill app on booted sim |
kuri ios terminate --device --udid <U> <bundle-id> | Kill on real device |
kuri ios screenshot [path.png] | PNG from booted sim (auto-resolves) |
kuri ios list-apps --udid <U> | List installed apps on sim |
kuri ios tap <x> <y> | Tap at device pixel coords on the booted sim |
kuri ios doubletap <x> <y> | Two quick taps at the same point (alias: dbltap) |
kuri ios longpress <x> <y> [hold_ms] | Press and hold (default 500ms — iOS haptic-touch threshold; alias: long-press) |
kuri ios swipe <x1> <y1> <x2> <y2> [ms] | Swipe/pan on the sim. Aliases: pan, scroll |
kuri ios type <text...> | Send keystrokes to the focused field on the sim |
Intentional limits (don't claim parity with upstream)
tap, swipe, type work on the iOS Simulator only (CGEvent into
the Simulator.app window). On real iPhones they return an explicit
"requires XCUITest" error — on purpose.uitree returns an explicit "requires XCUITest" error on both
Simulator and real device. The macOS AX tree of Simulator.app only
exposes the macOS window chrome, not the running iOS app.- Real-device screenshot is unavailable for the same reason.
- There is no on-device
run_code sandbox.
If a user needs any of the above, the route forward is the v2
"vendor on-device drivers" path described in kuri-mobile/README.md,
not this skill.
Native vs shelled-out surfaces (honesty)
| Surface | How it's implemented |
|---|
| simctl device listing | libc fork/exec xcrun simctl list devices --json, parse JSON in Zig |
| usbmuxd real-device listing | native Zig Unix-socket client, plist scan |
| openurl / launch / terminate / screenshot | shell out to xcrun simctl / xcrun devicectl |
| Simulator tap / swipe / pan | native Zig — CGEvent via ApplicationServices.framework, with osascript only used to (a) activate Simulator.app and (b) read the front window's position+size for the device→screen coord mapping |
| Simulator type | shell out to osascript (System Events keystroke), Unicode-safe |
| Resolve "booted sim" | iterate parsed list in Zig, match state == "Booted" |
Apple's iOS Simulator runtime renders the screens — Kuri orchestrates.
