kuri-ios

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    # optional: unit tests for adb framing, uitree parser, usbmuxd plist scan

Typical flow

# 1. List and boot a sim
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>

# 2. Navigate and screenshot (auto-resolves the booted sim — no --udid needed)
kuri ios openurl https://news.ycombinator.com
sleep 3   # let the page settle
kuri ios screenshot hn.png

# 3. Launch a built-in app, screenshot
kuri ios launch com.apple.Preferences
sleep 2
kuri ios screenshot settings.png

# 4. Open any URL scheme (not just https/http)
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.