ios-simulator-skill

iOS Simulator Skill for Agents

Production-ready skill for building, testing, and automating iOS apps. 31 scripts optimized for both human developers and AI agents.

If you prefer MCP, XC-MCP was the original source of this toolkit before Skills were even a thing, and can be run from NPM too)

https://github.com/user-attachments/assets/b1c4225a-e083-4c4b-96bd-0d20a41f9b1f

Xcode Build + Simulator Automation

This skill covers both sides of iOS development:

• Xcode builds via xcodebuild — compile, test, and parse results with progressive error disclosure
• Simulator interaction via xcrun simctl and idb — semantic UI navigation, accessibility testing, device lifecycle

Install it

Claude Code — plugin marketplace (recommended)

/plugin marketplace add conorluddy/ios-simulator-skill
/plugin install ios-simulator-skill@conorluddy

Codex — plugin marketplace (recommended)

codex plugin marketplace add conorluddy/ios-simulator-skill
codex plugin add ios-simulator-skill@conorluddy

Or run /plugins inside Codex and install it from the conorluddy marketplace. Start a new Codex session afterwards. Update later with codex plugin marketplace upgrade conorluddy.

Any agent — npx skills

The skills CLI finds SKILL.md inside the repo and copies it into the right directory for each agent it detects (Claude Code, Codex, Cursor and others). It needs Node.js 18+.

npx skills add conorluddy/ios-simulator-skill        # project-level (./.claude/skills, ./.agents/skills, ...)
npx skills add conorluddy/ios-simulator-skill -g     # user-level, for every project
npx skills add conorluddy/ios-simulator-skill -a claude-code   # only one agent

Restart your agent afterwards so it picks the skill up.

Manual install

A skill is loaded from SKILL.md at the root of its directory:

Agent	User-level skills	Project-level skills
Claude Code	~/.claude/skills/<name>/SKILL.md	.claude/skills/<name>/SKILL.md
Codex	~/.agents/skills/<name>/SKILL.md	.agents/skills/<name>/SKILL.md

The commands below use the Claude Code path; swap in ~/.agents/skills for Codex. This repository is a plugin, so the skill itself lives at ios-simulator-skill/skills/ios-simulator-skill/; cloning the whole repo into your skills directory puts SKILL.md three levels too deep and the skill will not load.

From a release (simplest):

curl -L https://github.com/conorluddy/ios-simulator-skill/releases/latest/download/ios-simulator-skill.zip -o skill.zip
unzip skill.zip -d ~/.claude/skills/ios-simulator-skill

From a clone (to track main):

git clone https://github.com/conorluddy/ios-simulator-skill.git ~/src/ios-simulator-skill
cp -R ~/src/ios-simulator-skill/ios-simulator-skill/skills/ios-simulator-skill \
      ~/.claude/skills/ios-simulator-skill

For a project-local install, use the project-level path from the table instead. Restart Claude Code afterwards (Codex picks up new skills automatically; restart it if the skill doesn’t appear). Verify SKILL.md sits at the root of the destination:

ls ~/.claude/skills/ios-simulator-skill/SKILL.md   # Claude Code
ls ~/.agents/skills/ios-simulator-skill/SKILL.md   # Codex

Prerequisites

Requirement	Version	Needed for
macOS	15 (Sequoia)+	everything
Xcode (full app, not just Command Line Tools)	26+	building, simctl, idb
Python	3.12+	every script
idb (CLI + companion)	1.5.1+ (1.6.3+ recommended)	tapping, swiping, typing
Pillow	any	visual diffs only (pip3 install pillow)

Install idb — required for every interactive script (navigator.py, gesture.py, keyboard.py):

brew install facebook/fb/idb      # installs idb-cli and idb-companion

The Homebrew build is prebuilt: it needs an Apple silicon Mac, macOS 15+, and a full Xcode 26+ selected with xcode-select (Command Line Tools alone are not enough). Intel Macs are not supported (facebook/idb#954).

brew install idb-companion no longer works: idb-companion was removed from Homebrew core and now lives in Meta’s own facebook/fb tap. If you followed older instructions, see Updating idb.

To verify everything at once:

bash scripts/sim_health_check.sh          # add --json for machine-readable output

Updating idb

On Xcode 27, idb-companion must be 1.5.1 or newer. Older builds look for SimulatorKit.framework where Xcode 26 kept it. Under Xcode 27 the companion still starts and the accessibility tree still reads correctly, but every tap, swipe and keystroke is silently dropped — idb reports success and nothing happens on screen.

brew upgrade facebook/fb/idb-cli facebook/fb/idb-companion
brew list --versions idb-cli idb-companion   # expect matching versions, >= 1.5.1

Upgrade the CLI and companion together. Newer client features are served by the companion, so a 1.7 CLI talking to a 1.5 companion fails or falls back to older output. Companions that are already running keep the old binary until restarted, so run idb kill after upgrading.

Pinning or bisecting idb. The facebook/fb tap carries only the newest release, so Homebrew can’t install an older one. Upstream’s homebrew.py (in the root of facebook/idb) installs CI builds instead, into a separate local tap. It needs a GitHub token (GITHUB_TOKEN, GH_TOKEN or a logged-in gh):

curl -fsSLO https://raw.githubusercontent.com/facebook/idb/main/homebrew.py
python3 homebrew.py builds                # releases and recent CI builds of main
python3 homebrew.py install <commit-sha>  # or pr:<n>, run:<id>; a tag works only if it's the newest
python3 homebrew.py status                # what is installed, from which build
python3 homebrew.py uninstall --restore   # back to facebook/fb/idb

Coming from the old pip package? An old fb-idb (1.1.x) left in a pyenv or virtualenv shadows the Homebrew CLI if it comes first on your PATH, so check with which -a idb. Remove it with pip uninstall fb-idb (then pyenv rehash under pyenv). sim_health_check.sh detects this.

Xcode 27 notes

• There is no Simulator.app. Xcode 27 replaced it with DeviceHub.app, in Xcode.app/Contents/Applications/. Scripts drive simulators headlessly via simctl and idb, so you rarely need either — but open -a Simulator will fail.
• Quitting DeviceHub shuts down the simulator it is hosting.
• If idb calls start failing with Connection refused after a crash or a manual pkill, a dead companion is still registered. Clear it with idb disconnect <udid>; sim_health_check.sh detects this.

Features

Xcode Build with Progressive Disclosure

The build_and_test.py script wraps xcodebuild with token-efficient output. A build returns a single summary line with an xcresult ID:

Build: SUCCESS (0 errors, 3 warnings) [xcresult-20251018-143052]

Then drill into details on demand:

python scripts/build_and_test.py --get-errors xcresult-20251018-143052
python scripts/build_and_test.py --get-warnings xcresult-20251018-143052
python scripts/build_and_test.py --get-log xcresult-20251018-143052

Add --run to build, install and launch in one call (Launched: com.example.MyApp on iPhone 17 Pro (pid 4410)). If Xcode’s parallel test clones can’t boot, --test reports Tests: NOT RUN instead of a misleading FAIL; --no-parallel runs tests on one simulator.

This keeps agent conversations focused — no walls of build output unless you ask for them.

Simulator Navigation via Accessibility

Instead of fragile pixel-coordinate tapping, all navigation uses iOS accessibility APIs to find elements by meaning:

# Fragile — breaks if UI changes
idb ui tap 320 400

# Robust — finds by meaning
python scripts/navigator.py --find-text "Login" --tap

The raw accessibility tree is not cheap on its own: idb ui describe-all often costs more than a screenshot. The win is the summary the skill builds from it: element types, labels and tap targets in 3-5 lines. See AI-Accessible Apps for more on why accessibility-first navigation matters for AI agents.

What it costs to see a screen

Measured walking 6 screens of a real SwiftUI app on an iPhone 17 Pro simulator (iOS 27). Text tokens are estimated at characters ÷ 4, image tokens at width × height ÷ 750.

Way of seeing a screen	Per screen (median)	6-screen run
Screenshot, full size	~1,500	~9,000
Raw idb ui describe-all --json	~6,700 (largest: ~58,000)	~91,000
screen_mapper.py summary	~35	~250

A single lookup is smaller still: navigator.py --find-text "Springs" prints Found: Button "Springs" at (201, 1367), about 10 tokens.

Screenshot Token Optimization

When you do need pixels (visual verification, bug reports, diffs), app_state_capture.py and test_recorder.py resize screenshots with --size before an agent sees them:

--size	iPhone 17 Pro	Tokens per screenshot
full	1206×2622	~1,500 (up to ~4,000 on models that accept larger images)
half (default)	603×1311	~1,050
quarter	301×655	~260
thumb	120×262	~40

Token counts are for Claude (width × height ÷ 750, after it shrinks images over about 1.15 MP). Most providers already shrink or cap large images on their side, so halving a screenshot saves less than the 75% the pixel count suggests: about 30% here. quarter and thumb are where the real savings are, if the agent can still read what it needs at that size.

All 31 Scripts

Every script supports --help and --json. See SKILL.md for the complete reference.

Build & Development

Script	What it does	Key flags
build_and_test.py	Build Xcode projects, run tests, parse xcresult bundles	--project, --scheme, --test, --run, --no-parallel, --get-errors, --get-warnings
log_monitor.py	Real-time log monitoring with severity filtering	--app, --severity, --follow, --duration

Duo controls require an explicit booted iPhone Duo UDID. Use python3 scripts/duo.py --udid <UDID> --pose open, then read --state --json for the active display_id. Pass it with --display to app_state_capture.py or test_recorder.py (file or inline mode). The bundled private helper compiles with Xcode on first use and verifies observed state; inner-display coordinate touches remain unverified. See backend contracts and live verification.

Device State

Script	What it does	Key flags
duo.py	Duo hinge, orientation and active display readback	--udid, --state, --pose, --angle, --orientation, --json
appearance.py	Switch dark mode, dynamic type, increase contrast, locale, region	--theme, --text-size, --contrast, --locale, --region, --reset
location.py	Simulate GPS coordinates and run built-in scenarios	--lat, --lng, --city, --gpx, --list-scenarios, --clear
media.py	Seed or empty the photo library (--clear needs idb 1.7+ and --yes)	--add, --clear, --yes

Navigation & Interaction

Script	What it does	Key flags
screen_mapper.py	Analyze current screen, list interactive elements	--verbose, --hints, --deep
navigator.py	Find and interact with elements semantically	--find-text, --find-type, --find-id, --tap, --expect, --enter-text, --set-value
gesture.py	Swipes (finger direction), scrolls (content direction), pinch, long press, pull to refresh, double-tap, drag, rotate, shake	--swipe, --scroll, --pinch, --scale, --long-press, --refresh, --double-tap, --drag, --rotate, --shake
keyboard.py	Text input, keys, key chords, key sequences and hardware buttons	--type, --key (+ --shift/--control/--option/--command), --key-sequence, --button, --clear, --dismiss
app_launcher.py	Launch, terminate, install, deep link apps	--launch, --terminate, --install, --open-url, --list

Testing & Analysis

Script	What it does	Key flags
accessibility_audit.py	WCAG compliance checking on current screen	--verbose, --output
visual_diff.py	Compare two screenshots for visual changes	--threshold, --output, --details
test_recorder.py	Automated test documentation with screenshots	--test-name, --output
app_state_capture.py	Debugging snapshots (screenshot, hierarchy, logs)	--app-bundle-id, --output, --log-lines
sim_health_check.sh	Verify environment (Xcode, simctl, IDB, Python)	—
model_inspector.py	Inspect Core Data / SwiftData models from project files	--project-path, --raw, --show-versions
container.py	Inspect app sandbox: list, cat, UserDefaults, Core Data, export	--ls, --cat, --userdefaults, --core-data-path, --export
hang_watcher.py (HangBuster)	Record + summarise os_log hang events with progressive disclosure (session mode + raw NDJSON + legacy stream); auto-restart on stream death, automatic disk-cap cleanup	--start [--raw-capture --max-size-mb N --no-gzip], --stop, --get-details, --list-sessions, --diff, --budget-tokens, --auto-sample (legacy: --watch, --since)
localization_audit.py	Audit .xcstrings catalogs for missing keys, unused keys, placeholder mismatches	--catalog, --source, --strict

Permissions & Environment

Script	What it does	Key flags
clipboard.py	Copy text to simulator clipboard for paste testing	--copy, --test-name
status_bar.py	Override status bar (time, battery, network)	--preset, --time, --battery-level, --clear
push_notification.py	Send, list and clear simulated push notifications	--bundle-id, --title, --body, --payload, --list, --clear
privacy_manager.py	Grant, revoke, reset app permissions (15 services)	--bundle-id, --grant, --revoke, --reset

Device Lifecycle

Script	What it does	Key flags
simctl_boot.py	Boot simulators with readiness verification	--name, --wait-ready, --timeout, --all, --type
simctl_shutdown.py	Gracefully shutdown simulators	--name, --verify, --all, --type
simctl_create.py	Create simulators by device type and OS version	--device, --runtime, --list-devices
simctl_delete.py	Delete simulators (needs --yes)	--name, --yes, --all, --old
simctl_erase.py	Factory reset without deletion (needs --yes)	--name, --yes, --verify, --all, --booted

Configuration

Every operational limit — timeouts, output caps, polling intervals, cache size, post-action delays — is tunable via an IOS_SIM_* environment variable. Defaults are tuned for local development on Apple Silicon. Raise them on slow CI runners, large monorepos, or accessibility audits over complex screens. Lower them when you need faster failure or tighter token budgets.

There’s a universal tradeoff to keep in mind:

• Higher caps / longer timeouts → fewer false failures, more complete diagnostics, more tokens consumed by AI agents and slower failures when something is genuinely broken.
• Lower caps / shorter timeouts → faster feedback, tighter token usage, risk of silently dropped errors or premature timeouts on legitimately slow operations.

Boot & lifecycle timeouts

How long to wait on xcrun simctl operations.

Variable	Default	Tradeoff
IOS_SIM_BOOT_TIMEOUT	300 (s)	Wait for simulator readiness after boot. Lower → faster failure on broken sims. Higher → survives cold-start on slow CI runners (GitHub-hosted macOS can need 4–6 min).
IOS_SIM_BOOT_SUBPROCESS_TIMEOUT	60 (s)	Timeout for the simctl boot call itself (before readiness polling starts). Rarely needs changing; bump only if you see Boot command timed out on resource-starved CI.
IOS_SIM_ERASE_TIMEOUT	90 (s)	Wait for factory-reset verification. Larger simulators (lots of installed apps + data) can need more than the old 30s.
IOS_SIM_POLL_INTERVAL	0.5 (s)	How often to re-check boot/erase state. Lower → more responsive (more CPU). Higher → quieter on slow CI but adds latency to “ready” detection.
IOS_SIM_STATE_SUBPROCESS_TIMEOUT	15 (s)	Per-subprocess timeout in app_state_capture.py. Bump for apps with very large accessibility trees.

Build & test output caps

build_and_test.py returns counts by default and full details via xcresult ID; these caps govern what’s surfaced in human/JSON output before progressive disclosure kicks in.

Variable	Default	Tradeoff
IOS_SIM_BUILD_SUMMARY_CAP	15	Errors / failed tests in the default text summary. Lower → terser default output. Higher → less need to chase xcresult IDs for context.
IOS_SIM_BUILD_VERBOSE_CAP	100	Errors / warnings in --verbose mode. Mostly relevant for monorepos or first builds with many fixable warnings.
IOS_SIM_BUILD_JSON_CAP	50	Max errors / failed tests in --json output. Raise for CI dashboards that need exhaustive lists.
IOS_SIM_BUILD_LOG_PREVIEW	4000 (chars)	Chars of build log included in default output. Higher → more context for failures, more tokens.
IOS_SIM_BUILD_TIMEOUT	1800 (s)	Hard cap on a single xcodebuild build invocation. Default of 30 min covers most clean builds of large apps; raise for very large monorepos, lower to fail fast in CI when builds are expected to take seconds. Without this, a hung xcodebuild would block forever.
IOS_SIM_TEST_TIMEOUT	2700 (s)	Hard cap on xcodebuild test. Tests can take significantly longer than builds (45 min default) because of simulator boot + animation delays.
IOS_SIM_INTROSPECT_TIMEOUT	60 (s)	Timeout for xcodebuild -list and xcrun simctl list introspection calls. These should normally complete in <1s; 60s catches Xcode-toolchain hangs without disrupting cold-start.

Log monitor output

log_monitor.py aggregates os_log output; these caps shape both the text summary and the structured JSON.

Variable	Default	Tradeoff
IOS_SIM_LOG_TEXT_SUMMARY	15	Errors / warnings shown in the text summary. The default surfaces enough for most debugging without flooding terminal output.
IOS_SIM_LOG_LINE_MAX	300 (chars)	Per-line truncation. Crash messages with full Swift symbol mangling can exceed 200 chars; raise if you see “…” cutting off the actionable bit.
IOS_SIM_LOG_TAIL	200 (lines)	Recent log lines shown in verbose mode and JSON sample_logs. Also used by xcode log excerpt. Lower for tighter context, higher for richer post-mortems.
IOS_SIM_LOG_JSON_CAP	100	Max errors / warnings in JSON output. Raise if you’re piping into a dashboard that needs the full picture.
IOS_SIM_HANG_PREDICATE	(default)	Override the os_log predicate used by hang_watcher.py. The default catches RunningBoard watchdog kills, explicit “Hang detected” messages, and main-thread hang annotations. Hang events originate from system daemons (RunningBoard, SpringBoard, watchdog) — not the target app’s process — so the predicate intentionally stays simulator-global. --bundle-id is applied post-parse against the event payload, never ANDed into the predicate.
IOS_SIM_HANG_MIN_MS	250	HangBuster threshold: events below this duration never reach disk.
IOS_SIM_HANG_SESSION_TTL_HOURS	24	HangBuster session prune age. Pruning runs on every --start.
IOS_SIM_HANG_DEFAULT_TOP_N	3	Default top-N clusters in --stop L1 output.
IOS_SIM_HANG_BUDGET_TOKENS	(unset)	Default token budget for --stop (picks L0/L1/L2 to fit).
IOS_SIM_HANG_MAX_RESTARTS	3	HangBuster worker: bounded log stream respawn attempts on EOF/subprocess death before the session is marked crashed. Set to 0 to disable auto-restart.
IOS_SIM_HANG_TOTAL_CAP_MB	100	HangBuster aggregate disk cap. When total session-state exceeds this on --start, oldest sessions are dropped first. Set to 0 to disable.

UI navigation & screen mapping

These shape what AI agents see when exploring a screen. They’re the biggest direct lever on token consumption per navigation step.

Variable	Default	Tradeoff
IOS_SIM_MAX_ELEMENTS	25	Items listed by navigator.py --list and push_notification.py --list. Default is enough for most screens; raise to 100+ for dense Settings-style screens or audit workflows. High token impact at high values.
IOS_SIM_SCREEN_BUTTONS_PREVIEW	15	Button names in screen_mapper.py summary.
IOS_SIM_SCREEN_SECTION_ITEMS	10	Items per section in screen_mapper.py summary.
IOS_SIM_APPS_PREVIEW	30	Installed apps listed by app_launcher.py before truncation.
IOS_SIM_TAP_SETTLE_MS	500 (ms)	Delay after a tap before reading new state. Lower → faster navigation on snappy apps. Higher → safer on apps with heavy animations or async loading; raises end-to-end test runtime linearly.
IOS_SIM_RELAUNCH_DELAY_MS	1000 (ms)	Delay between terminate and re-launch in app_launcher.py --restart. Raise if you see relaunches catching the previous process still tearing down.

Accessibility audit

Variable	Default	Tradeoff
IOS_SIM_A11Y_TOP_ISSUES	10	Top issues surfaced per audit. Default of 3 in older versions was almost always too aggressive for real-world apps. Raise for first-pass audits, lower for regression checks.
IOS_SIM_A11Y_LABEL_MAX	80 (chars)	Max chars of AXLabel retained in audit output. Custom localized labels often exceed 30 chars; 80 catches almost all.

Progressive disclosure cache

ProgressiveCache stores large outputs (build results, log dumps) keyed by short IDs so the default output stays minimal.

Variable	Default	Tradeoff
IOS_SIM_CACHE_TTL_HOURS	1	How long cache entries remain valid. Lower → fresher data on next retrieve, more re-runs. Higher → faster reruns in long CI pipelines, risk of stale results if simulator state changed.
IOS_SIM_CACHE_MAX_ENTRIES	500	Hard cap; oldest entries (by mtime) are evicted on every save(). Prevents unbounded growth of ~/.ios-simulator-skill/cache/ in long-running environments. Raise only if you frequently need to retrieve entries older than ~500 saves.

Examples

# Slow GitHub Actions macOS runner — give boot up to 10 minutes
IOS_SIM_BOOT_TIMEOUT=600 python scripts/simctl_boot.py --wait-ready

# Monorepo with hundreds of warnings — see them all in verbose mode
IOS_SIM_BUILD_VERBOSE_CAP=500 python scripts/build_and_test.py --verbose

# Complex Settings-style screen — return more tappable elements
IOS_SIM_MAX_ELEMENTS=100 python scripts/navigator.py --list

# Snappy app — cut tap-settle delay in half for faster E2E runs
IOS_SIM_TAP_SETTLE_MS=250 python scripts/navigator.py --find-text "Login" --tap

# Long CI pipeline — keep cache entries valid for the whole job
IOS_SIM_CACHE_TTL_HOURS=8 python scripts/build_and_test.py --project MyApp.xcodeproj

You can also export the vars once for the whole session:

export IOS_SIM_BOOT_TIMEOUT=600
export IOS_SIM_LOG_TAIL=500
export IOS_SIM_MAX_ELEMENTS=50
# … all subsequent scripts honor them

Parse errors fall back to the documented default with a warning on stderr — no scripts will crash on a malformed env var.

Evaluation

Tested using Claude Code evals:

Condition	Pass Rate
With skill	100% (3/3)
Without skill	46% (~1.4/3)

claude evals run evals/evals.json --skill ios-simulator-skill

License

MIT