ios-run-app
Build, install, launch and screenshot an iOS debug scheme on a simulator via xcodebuild and xcrun simctl, and run a journey on it when one is named.
SKILL.mdcodex/skills/ios-run-app/SKILL.md
GitHubRead the project AGENTS.md and applicable global guidance first. Fall back to CLAUDE.md if AGENTS.md is absent. Follow the global rules for optional tools, specialist agents and Git actions.
Run the app: the user request
Defaults: the simulator named in ~/.codex/machine.md or the project instructions, otherwise a compatible available iPhone from xcrun simctl list devices available, and
the project's workspace, default debug scheme and bundle id from its AGENTS.md. Never guess a scheme name. Quote xcodebuild -list.
xcodebuild -version, thenxcodebuild -list -workspace <ws>and confirm the scheme exists. CocoaPods repos: runpod installfirst whenPods/is missing orPodfile.lockchanged. SwiftPM-only repos need nothing.xcrun simctl list devices available, then record the selected simulator UDID and use it for every subsequent command. If the simulator is notBooted, runxcrun simctl boot <udid>, thenxcrun simctl bootstatus <udid> -b.open -a Simulatorwhen the caller wants to watch.- Build:
xcodebuild build -workspace <ws> -scheme "<scheme>" -destination 'platform=iOS Simulator,id=<udid>' -derivedDataPath <scratchpad>/DerivedData -quiet. On failure re-run without-quietand quote the firsterror:lines. - Locate the product:
xcodebuild -showBuildSettings … | grep -E 'BUILT_PRODUCTS_DIR|FULL_PRODUCT_NAME'. Install and launch:xcrun simctl install <udid> <path>.app, thenxcrun simctl launch <udid> <bundle id>(prints the pid). Deep link:xcrun simctl openurl <udid> <url>. - On the first screen:
xcrun simctl io <udid> screenshot <scratchpad>/<simulator>-<scheme>-<screen>.png. For accessibility or dark-mode checks:xcrun simctl ui <udid> content_size accessibility-extra-large,xcrun simctl ui <udid> appearance dark, then screenshot again. - When the caller names a journey file, hand it to the
ios-verifieragent with the UDID, the bundle id, the scratchpad directory and confirmation that the app is launched. It returns the JSON result described inreferences/journeys.mdin theios-standardsskill. If any action came back SKIPPED with "no driver" and this session has a simulator control tool that can tap and type, run the journey here with that tool, following the same reference. That result replaces the verifier's. When the verifier lists a missing driver under Findings, tell the user its install command once per session. - Report: simulator name, UDID and OS, scheme and configuration,
.apppath, launch pid, screenshot path(s), the journey result if one ran, and if the app crashed, the last 30 lines ofxcrun simctl spawn <udid> log show --last 2m --predicate 'processImagePath CONTAINS "<App>"'.
Do not erase or delete simulators, or change privacy permissions, without user authorization. Record the existing appearance and content-size settings before a visual check and restore them afterwards. Plain simctl cannot tap or type. Interaction uses the driver order in references/journeys.md: a simulator control tool, then AXe, then the project's XCUITests, otherwise interaction checks are Unverified.