iOS Simulator Skill
Build, test, and automate iOS applications using accessibility-driven navigation and structured data instead of pixel coordinates.
Quick Start
# 1. Check environment
bash scripts/sim_health_check.sh
# 2. Launch app
python3 scripts/app_launcher.py --launch com.example.app
# 3. Map screen to see elements
python3 scripts/screen_mapper.py
# 4. Tap button
python3 scripts/navigator.py --find-text "Login" --tap
# 5. Enter text
python3 scripts/navigator.py --find-type TextField --enter-text "user@example.com"
Paths: scripts/ is relative to the directory containing this SKILL.md, not the user's project.
Examples write scripts/... for brevity; run them by absolute path from the user's project
(e.g. python3 <skill-dir>/scripts/navigator.py ...) so relative Xcode project paths still resolve.
All scripts support --help for detailed options; most support --json for machine-readable output.
Navigation Strategy
Always prefer the accessibility tree over screenshots for navigation. The accessibility tree gives you element types, labels, frames, and tap targets — structured data that's cheaper and more reliable than image analysis.
Use this priority:
screen_mapper.py → structured element list (5-7 lines, ~10 tokens)
navigator.py --find-text/--find-type/--find-id → semantic interaction
- Screenshots → only for visual verification, bug reports, or visual diff
Screenshots cost 1,600–6,300 tokens depending on size. The accessibility tree costs 10–50 tokens in default mode.
31 Production Scripts
Build & Development (2 scripts)
build_and_test.py - Build Xcode projects, run tests, parse results with progressive disclosure
- Build with live result streaming
- Parse errors and warnings from xcresult bundles
- Retrieve detailed build logs on demand
--run builds, installs and launches the app in one call: Launched: <bundle> on <device> (pid N)
- Tests that never started (parallel clone failed to boot) report
Tests: NOT RUN, not FAIL; retry with --no-parallel
- Options:
--project, --scheme, --clean, --test, --run, --no-parallel, --verbose, --json
log_monitor.py - Real-time log monitoring with intelligent filtering
- Stream logs or capture by duration
- Filter by severity (error/warning/info/debug)
- Deduplicate repeated messages
- Options:
--app, --severity, --follow, --duration, --output, --json
Device State (4 scripts)
appearance.py - Control simulator appearance: dark mode, Dynamic Type size, contrast, and locale/region
- Toggle light/dark theme via
xcrun simctl ui
- Set Dynamic Type size with friendly aliases (XS through AX5)
--contrast high|normal toggles Increase Contrast and reads it back to confirm; --reset also restores normal contrast
- Write locale and region defaults; optional app restart via
--bundle-id
- RTL flagged automatically for ar/he/fa/ur/yi locales
- Options:
--theme, --text-size, --contrast, --locale, --region, --reset, --bundle-id, --udid, --json, --verbose
location.py - Simulate GPS coordinates, named city presets, and GPX scenario playback
- Fix a coordinate with
--lat/--lng or pick a city with --city
- Play a built-in scenario (City Run, Freeway Drive, etc.) via
--gpx <scenario>
- Animate multi-waypoint paths with configurable speed via
--waypoints and --speed
- Clear simulated location with
--clear; list available scenarios with --list-scenarios
- Options:
--lat, --lng, --city, --gpx, --waypoints, --speed, --clear, --list-scenarios, --udid, --json, --verbose
media.py - Seed or empty the photo library for photo-picker tests
--add a.jpg b.png via xcrun simctl addmedia
--clear --yes empties the library via idb photos clear (idb 1.7+); --clear --yes --add leaves exactly the added files
- Without
--yes, --clear refuses if the library has photos (they can't be recovered): ask the user first
- Fails fast on a missing file
- Options:
--add, --clear, --yes, --udid, --json
duo.py - Experimental iPhone Duo hinge and interface orientation controls
- Requires an explicit booted Duo
--udid; no automatic device selection
- Read observed angle, active cover/inner display ID and rotation (default or
--state)
--pose closed|partial|open (0°/90°/180°), --angle 0..180, or --orientation portrait|landscape|portrait-upside-down|landscape-flipped
- Changes verify observed readback; hinge endpoints also verify cover/inner display activation
- Bundled Objective-C helper compiles and signs with the selected Xcode on first use; no extra CLI
- Private APIs are experimental; inner-display coordinate touch routing is unverified
- Options:
--udid, --state, --pose, --angle, --orientation, --json, --verbose
Navigation & Interaction (5 scripts)
screen_mapper.py - Analyze current screen and list interactive elements
- Element type breakdown
- Interactive button list
- Text field status
- If labelled elements cover under 10% of the screen, adds a
Coverage: line suggesting --deep
--deep reads through idb's axbridge backend (idb 1.7+): also sees Safari/WKWebView content
and in-app alerts the default read misses, plus many unlabelled container views. It turns on
the device's accessibility automation mode (not restored afterwards). Web-content frames are
relative to the web view, so use --deep to find elements, not to take tap coordinates
- Options:
--verbose, --hints, --deep, --json
navigator.py - Find and interact with elements semantically
- Find by text (fuzzy, or exact with
--find-exact); interactive leaf elements rank above containers sharing the label
- Find by element type
- Find by accessibility ID
- Enter text or tap elements
--tap on a Button/Link/Switch/CheckBox/Tab with a unique accessibility ID or label uses an accessibility press
(idb 1.7+), so overlays like a floating search bar can't intercept it; output says
(accessibility press). Otherwise it taps the frame center
--set-value TEXT replaces a field's value without the keyboard (any characters, idb 1.7+).
Focus doesn't move, so use --enter-text when a Return key must submit afterwards
The value is read back before success is claimed (not for secure fields); a mismatch exits 1
--tap --expect VALUE taps only if the element's value is VALUE (toggles: 1 on, 0 off) and
exits 1 without tapping otherwise, so "turn X off" is safe to repeat
- iOS 27 reports toggles as
CheckBox. Only a press flips them (no HID touch does, even on the
switch itself); if neither ID nor label is unique, the output warns to check the value
- A frozen app stalls every read and tap until its main thread responds
- Failures include idb's stderr (e.g. a dead companion)
- Options:
--find-text, --find-exact, --find-type, --find-id, --index, --tap, --expect, --tap-at, --enter-text, --set-value, --list
gesture.py - Perform swipes, scrolls, pinches, and complex gestures
- Directional swipes (up/down/left/right) -
--swipe is the direction the finger moves
- Multi-swipe scrolling -
--scroll is the direction the content moves (down reveals content below)
- Pinch zoom via
idb ui pinch (--pinch out zooms in; --scale sets an explicit factor)
- Long press via
idb ui tap --duration
- Pull to refresh
--double-tap X,Y [--tap-count N] - multi-tap at a point (idb 1.7+)
--drag SOURCE DEST - press-hold, drag, release; each end is x,y or an accessibility label,
e.g. --drag "Row 1" "Row 4" (idb 1.7+)
--rotate portrait|portrait-upside-down|landscape-left|landscape-right - physical device rotation (idb 1.7+)
--shake - shake the device, for debug menus and undo (idb 1.7+)
- Options:
--swipe, --swipe-from/--swipe-to, --scroll, --scroll-amount, --pinch, --scale, --long-press, --duration, --refresh, --double-tap, --tap-count, --drag, --rotate, --shake
keyboard.py - Text input and hardware button control
- Type text (fast or slow; ASCII only)
- Special keys (return, delete, tab, space, escape, arrows), single letters, or raw HID codes
- Key sequences (
--key-sequence h,i,return)
- Key chords:
--key z --command --shift (redo); --shift/--control/--option need idb 1.7+
- Clear the focused field (Cmd+A, delete)
- Hardware buttons: home, lock/power, side, siri, apple-pay, volume-up/down (volume needs idb 1.6.3+)
- Options:
--type, --slow, --key, --shift, --control, --option, --command, --count, --key-sequence, --button, --clear, --dismiss
- app_launcher.py - App lifecycle management
- Launch apps by bundle ID
- Terminate apps
- Install/uninstall from .app bundles (
--uninstall needs --yes: the app's data is deleted)
- Deep link navigation
- List installed apps
- Check app state
- Pass launch arguments (
--args) and environment variables (--env KEY=VALUE, injected as SIMCTL_CHILD_*) to the app on launch/restart
- Options:
--launch, --terminate, --restart, --install, --uninstall, --yes, --open-url, --list, --state, --args, --env, --wait-for-debugger
Testing & Analysis (9 scripts)
accessibility_audit.py - Check WCAG compliance on current screen
- Critical issues (missing labels, empty buttons, no alt text)
- Warnings (missing hints, small touch targets)
- Info (missing IDs, deep nesting)
- Options:
--verbose, --output, --json
visual_diff.py - Compare two screenshots for visual changes
- Pixel-by-pixel comparison
- Threshold-based pass/fail
- Generate diff images
- Options:
--threshold, --output, --details, --json
test_recorder.py - Automatically document test execution
- Capture screenshots and accessibility trees per step
- Generate markdown reports with timing data
- Options:
--test-name, --output, --verbose, --json
app_state_capture.py - Create comprehensive debugging snapshots
- Screenshot, UI hierarchy, app logs, device info
- Markdown summary for bug reports
- Options:
--app-bundle-id, --output, --log-lines, --json
sim_health_check.sh - Verify environment is properly configured
- Check macOS, Xcode, simctl, IDB, Python
- List available and booted simulators
- Verify Python packages (Pillow)
model_inspector.py - Inspect Core Data and SwiftData models from project files
- Parse .xcdatamodeld packages (entities, attributes, relationships)
- Detect model versions and current active version
- Best-effort SwiftData @Model class extraction
- Raw source dump for any model on demand (
--raw ModelName)
- Options:
--project-path, --core-data-only, --swiftdata-only, --show-versions, --raw, --verbose, --json
container.py - Inspect app sandbox: files, UserDefaults, and Core Data store paths
- List data container files at configurable depth via
--ls
- Read files with auto-detected plist decoding via
--cat (large files cached)
- Dump UserDefaults as key=value or JSON via
--userdefaults
- Locate
.sqlite / .sqlite-wal / .sqlite-shm stores via --core-data-path
- Export full container snapshot via
--export
- Options:
--ls, --cat, --userdefaults, --core-data-path, --export, --udid, --json, --verbose
hang_watcher.py (HangBuster) - Record + summarise os_log hang events with progressive disclosure
- Session mode (HangBuster, agent-native): start a detached recorder, interact with the simulator, stop for a token-tight summary
--start → returns a session ID; detached worker normalises + thresholds events on the fly
--stop SESSION_ID → emits ~80–120 token L1 summary (header + top-N clusters + drill hint)
--get-details SESSION_ID [--cluster N | --raw] → L2 full clusters or L3 per-event detail
--list-sessions / --clear-sessions [--older-than 24h] / --diff A B (cross-session regression report)
- Filter pipeline: parse → normalise → threshold → bucket → cluster → aggregate → rank → format (in
common/hang_pipeline.py)
--budget-tokens N picks the densest level (L0/L1/L2) that fits; --terse forces L0
--auto-sample captures a main-thread stack on first event per cluster (soft dependency: main_thread_sampler.py #62; graceful no-op if absent)
- Raw capture mode (full fidelity for
jq exploration): skip the clustering pipeline, dump every matching log line verbatim to raw.ndjson
--start --raw-capture [--max-size-mb 10] [--no-gzip] — spawns log stream --style ndjson
- Per-session size cap (
--max-size-mb, default 10) — worker stops cleanly on cap; extras.truncated=true
--stop gzips raw.ndjson → raw.ndjson.gz (~15–19× compression; --no-gzip opts out)
--get-details SESSION_ID on a raw session prints the path with a zcat | jq ... hint
- Resilience (auto-restart on stream death): EOF or subprocess death triggers a
stream_died event then a bounded restart with 2s backoff. After IOS_SIM_HANG_MAX_RESTARTS (default 3) the session is marked crashed, never left in stale running state. --list-sessions shows capture=Xs and restarts=N.
- Cleanup is automatic: TTL prune (
IOS_SIM_HANG_SESSION_TTL_HOURS, default 24h) + aggregate cap (IOS_SIM_HANG_TOTAL_CAP_MB, default 100 MB, oldest-first eviction) both run on every --start.
- Legacy modes (unchanged for backward compat):
--watch [--duration N] (live stream) and --since 5m (historical)
- Filters:
--bundle-id (post-parse — hang capture stays simulator-global so RunningBoard/SpringBoard events are kept), --predicate (also via IOS_SIM_HANG_PREDICATE)
- All output supports
--json; session storage at ~/.ios-simulator-skill/sessions/<id>/{meta.json,events.jsonl,summary.json,raw.ndjson.gz}
Quick start (summarised mode):
SID=$(python3 scripts/hang_watcher.py --start --min-hang-ms 200)
# ... interact with the simulator (open sheets, scroll, navigate) ...
python3 scripts/hang_watcher.py --stop $SID # token-tight L1 summary
python3 scripts/hang_watcher.py --get-details $SID --cluster 1 # drill into cluster 1
python3 scripts/hang_watcher.py --diff $SID_BASELINE $SID # cross-session regression
Quick start (raw capture + jq exploration):
SID=$(python3 scripts/hang_watcher.py --start --raw-capture --max-size-mb 5)
# ... interact with the simulator ...
python3 scripts/hang_watcher.py --stop $SID
# → "Session ...: raw mode, 737 lines, 0.96 MB → 0.05 MB gzipped"
# Top processes by event count:
zcat ~/.ios-simulator-skill/sessions/$SID/raw.ndjson.gz \
| jq -s 'group_by(.processImagePath) | map({proc: (.[0].processImagePath | split("/") | last), n: length}) | sort_by(-.n) | .[:5]'
# All RunningBoard assertion invalidations:
zcat .../raw.ndjson.gz | jq -c 'select(.subsystem == "com.apple.runningboard" and (.eventMessage | startswith("Invalidating")))'
# Hangs per minute:
zcat .../raw.ndjson.gz | jq -r '.timestamp[:16]' | sort | uniq -c
localization_audit.py - Detect string catalog gaps, missing keys, and placeholder mismatches
- Report missing and
needs_review/new keys per locale in .xcstrings catalogs
- Cross-reference catalog keys against Swift source (
String(localized:) / NSLocalizedString) via --source
- Flag placeholder count mismatches (
%d, %@, %s, %lld) across locales
- Legacy
.strings and .stringsdict support via plistlib
- CI-friendly
--strict exits 2 on any finding
- Options:
--catalog, --source, --locale, --strict, --json, --verbose
Advanced Testing & Permissions (4 scripts)
clipboard.py - Manage simulator clipboard for paste testing
- Copy text to clipboard
- Test paste flows without manual entry
- Options:
--copy, --test-name, --expected, --json
status_bar.py - Override simulator status bar appearance
- Presets: clean (9:41, 100% battery), testing (11:11, 50%), low-battery (20%), airplane (offline)
- Custom time, network, battery, WiFi settings
- Options:
--preset, --time, --data-network, --battery-level, --clear, --json
push_notification.py - Send simulated push notifications
- Simple mode (title + body + badge)
- Custom JSON payloads
- Test notification handling and deep links
--list shows delivered notifications; --clear withdraws them all (both idb 1.7+; sending stays on simctl)
- A push sent while its app is in the foreground isn't delivered to Notification Center, so
--list won't show it
- Options:
--bundle-id, --title, --body, --badge, --payload, --list, --clear, --json
privacy_manager.py - Grant, revoke, and reset app permissions
- 13 supported services (camera, microphone, location, contacts, photos, calendar, health, etc.)
- Batch operations (comma-separated services)
- Audit trail with test scenario tracking
- Options:
--bundle-id, --grant, --revoke, --reset, --list, --json
Simulator Discovery (2 scripts)
sim_list.py - List simulators with progressive disclosure
- Concise summary by default (total / available / booted)
- Full details on demand via cache IDs
- Filter by device type
- Suggest recommended simulators with
--suggest
- 96% token reduction vs raw
simctl list (57k → 2k tokens)
- Options:
--get-details, --suggest, --device-type, --json
simulator_selector.py - Suggest the best simulator for the job
- Ranks candidates by recent use (from
config.json), latest iOS, common test models, and boot status
- List all available simulators with
--list
- Boot a selected simulator directly with
--boot
- JSON output for programmatic use
- Options:
--suggest, --list, --boot, --json
Device Lifecycle Management (5 scripts)
simctl_boot.py - Boot simulators with optional readiness verification
- Boot by UDID or device name
- Wait for device ready with timeout
- Batch boot operations (--all, --type)
- Performance timing
- Options:
--udid, --name, --wait-ready, --timeout, --all, --type, --json
simctl_shutdown.py - Gracefully shutdown simulators
- Shutdown by UDID or device name
- Optional verification of shutdown completion
- Batch shutdown operations
- Options:
--udid, --name, --verify, --timeout, --all, --type, --json
simctl_create.py - Create simulators dynamically
- Create by device type and iOS version
- List available device types and runtimes
- Custom device naming
- Returns UDID for CI/CD integration
- Options:
--device, --runtime, --name, --list-devices, --list-runtimes, --json
simctl_delete.py - Permanently delete simulators
- Delete by UDID or device name
- Refuses without
--yes (no prompt; the simulator and its data can't be recovered): ask the user first
- Batch delete operations
- Smart deletion (--old N to keep N per device type)
- Options:
--udid, --name, --yes, --all, --type, --old, --json
simctl_erase.py - Factory reset simulators without deletion
- Preserve device UUID (faster than delete+create)
- Erase all, by type, or booted simulators
- Optional verification
- Refuses without
--yes (apps, data and settings can't be recovered): ask the user first
- Options:
--udid, --name, --yes, --verify, --timeout, --all, --type, --booted, --json
Duo workflow
python3 scripts/duo.py --udid <DUO_UDID> --pose open
python3 scripts/duo.py --udid <DUO_UDID> --state --json
# Use the observed display_id, rather than assuming which display is active.
python3 scripts/app_state_capture.py --udid <DUO_UDID> --display 3 --output duo-state
python3 scripts/test_recorder.py --udid <DUO_UDID> --display 3 --test-name duo-layout
--display selects the screenshot display in file and inline modes; accessibility trees remain
independent and provide no verified coordinate mapping to that display. Rotation polls observed
interface state across native orientation candidates because sensor and interface orientation may
differ. The five-second verification polling window excludes initial reads and hinge dispatch;
individual commands have separate timeouts, so total requests can take longer. If a change times
out, inspect observed state before retrying. Inactive displays may capture black frames.
The private backend credits hinge and
duoctl mechanism research. Replace folding and rotation
independently when supported headless APIs offer equivalent control and observed readback;
XCTest-only hinge APIs are insufficient. Video display selection is outside this package's scope.
Common Patterns
Auto-UDID Detection: Most scripts auto-detect the booted simulator if --udid is not provided.
Device Name Resolution: Use device names (e.g., "iPhone 16 Pro") instead of UDIDs - scripts resolve automatically.
Batch Operations: Many scripts support --all for all simulators or --type iPhone for device type filtering.
Output Formats: Default is concise human-readable output. Use --json for machine-readable output in CI/CD.
Help: All scripts support --help for detailed options and examples.
Screenshot Sizing: Screenshots are resized to save tokens. Presets: full (3-4 tiles, ~5K tokens), half (1 tile, ~1.6K tokens, default), quarter (1 tile, ~800 tokens, less detail). Use quarter for quick visual checks, half for readable UI, full only when pixel-level detail matters. Scripts that capture screenshots (app_state_capture.py, test_recorder.py) default to half.
Typical Workflow
- Verify environment:
bash scripts/sim_health_check.sh
- Launch app:
python3 scripts/app_launcher.py --launch com.example.app
- Analyze screen:
python3 scripts/screen_mapper.py
- Interact:
python3 scripts/navigator.py --find-text "Button" --tap
- Verify:
python3 scripts/accessibility_audit.py
- Debug if needed:
python3 scripts/app_state_capture.py --app-bundle-id com.example.app
Configuration
Most operational limits can be tuned via environment variables. Defaults work for typical local development; raise them for slow CI runners, large monorepo builds, or accessibility audits on complex screens.
| Variable |
Default |
Controls |
IOS_SIM_A11Y_LABEL_MAX |
80 |
Max chars of AXLabel retained in accessibility audit output |
IOS_SIM_A11Y_TOP_ISSUES |
10 |
Top accessibility issues surfaced per audit |
IOS_SIM_APPS_PREVIEW |
30 |
App entries listed by app_launcher.py before truncation |
IOS_SIM_BOOT_SUBPROCESS_TIMEOUT |
60 |
Timeout for the simctl boot subprocess itself (seconds) |
IOS_SIM_BOOT_TIMEOUT |
300 |
Wait-for-ready timeout after boot (seconds) |
IOS_SIM_BUILD_JSON_CAP |
50 |
Max build errors / failed tests in JSON output |
IOS_SIM_BUILD_LOG_PREVIEW |
4000 |
Chars of build log preview in default output |
IOS_SIM_BUILD_TIMEOUT |
1800 |
Max seconds for an xcodebuild build invocation before kill |
IOS_SIM_INTROSPECT_TIMEOUT |
60 |
Timeout for xcodebuild -list and simctl list lookups (seconds) |
IOS_SIM_TEST_TIMEOUT |
2700 |
Max seconds for an xcodebuild test invocation before kill |
IOS_SIM_BUILD_SUMMARY_CAP |
15 |
Errors/failures in default build summary |
IOS_SIM_BUILD_VERBOSE_CAP |
100 |
Errors/warnings in verbose build output |
IOS_SIM_CACHE_MAX_ENTRIES |
500 |
Max entries in progressive disclosure cache (LRU eviction) |
IOS_SIM_CACHE_TTL_HOURS |
1 |
Cache entry expiration |
IOS_SIM_ERASE_TIMEOUT |
90 |
Wait-for-erase timeout (seconds) |
IOS_SIM_HANG_PREDICATE |
(default) |
Override the os_log predicate used by hang_watcher.py (default catches RunningBoard kills + "Hang detected" + main-thread hangs). Hang events originate from system daemons (RunningBoard, SpringBoard) so the predicate stays simulator-global — --bundle-id is applied post-parse, not ANDed in. |
IOS_SIM_HANG_MIN_MS |
250 |
HangBuster threshold — events below this duration never reach disk (smaller = more sensitive, larger summaries) |
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: max log stream respawn attempts on EOF/subprocess death before the session is marked crashed |
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. |
IOS_SIM_LOG_JSON_CAP |
100 |
Max errors/warnings in log_monitor.py JSON output |
IOS_SIM_LOG_LINE_MAX |
300 |
Per-line truncation in log summaries |
IOS_SIM_LOG_TAIL |
200 |
Lines of log tail in verbose / sample output |
IOS_SIM_LOG_TEXT_SUMMARY |
15 |
Errors/warnings shown in text-mode log summary |
IOS_SIM_MAX_ELEMENTS |
25 |
Items listed by navigator.py --list and push_notification.py --list |
IOS_SIM_POLL_INTERVAL |
0.5 |
Boot/erase state polling interval (seconds) |
IOS_SIM_RELAUNCH_DELAY_MS |
1000 |
Delay between terminate and re-launch in app_launcher.py |
IOS_SIM_SCREEN_BUTTONS_PREVIEW |
15 |
Button names listed by screen_mapper.py |
IOS_SIM_SCREEN_SECTION_ITEMS |
10 |
Items per section shown by screen_mapper.py |
IOS_SIM_STATE_SUBPROCESS_TIMEOUT |
15 |
Subprocess timeout in app_state_capture.py (seconds) |
IOS_SIM_TAP_SETTLE_MS |
500 |
Post-tap settle delay in navigator.py |
Example:
# Slow GitHub Actions runner: give boot 10 minutes
IOS_SIM_BOOT_TIMEOUT=600 python3 scripts/simctl_boot.py --wait-ready
Requirements
- macOS 15 (Sequoia)+
- Xcode 26+ (the full app; Command Line Tools alone are not enough for idb)
- Apple silicon Mac (the Homebrew idb build is arm64-only)
- Python 3.12+
idb 1.5.1+ (1.6.3+ recommended) - required for every interactive script (tap, swipe, type):
brew install facebook/fb/idb (installs both idb-cli and idb-companion)
- Pillow, for visual diffs only:
pip3 install pillow
Verify with bash scripts/sim_health_check.sh (add --json for structured output).
Troubleshooting
Taps, swipes and typing do nothing, but reads work. idb reports success and the screen
never changes. On Xcode 27 this means idb-companion is older than 1.5.1: it looks for
SimulatorKit.framework at the path Xcode 26 used. Upgrade both together, then restart running
companions: brew upgrade facebook/fb/idb-cli facebook/fb/idb-companion && idb kill.
SimulatorKit is required for HID interactions. Same cause, same fix.
Health check warns "idb companions started before idb-companion was last installed". Those
companions still run the pre-upgrade binary. Run idb kill; the next idb call starts a fresh one.
Connection refused or No such file from every idb call. A dead companion is still in
idb's registry at /tmp/idb/state, so idb dials a socket nobody is listening on instead of
starting a fresh companion. Fix: idb disconnect <udid>.
open -a Simulator fails. Xcode 27 has no Simulator.app; it was replaced by
DeviceHub.app in Xcode.app/Contents/Applications/. Boot headlessly instead:
xcrun simctl boot <udid>. Note that quitting DeviceHub shuts down the simulator it hosts.
idb: command not found. The companion and the CLI are separate packages;
brew install facebook/fb/idb installs both. If which -a idb shows more than one, the first on
PATH wins. An old pip fb-idb there needs pip uninstall fb-idb.
Known upstream idb issues (open as of idb 1.7.6):
- facebook/idb#964: on some iOS 26+ screens
describe-all returns only the application node, and SpringBoard alerts can't be tapped. The
default ax backend can't see across process boundaries; try
idb ui describe-all --json --api axbridge. Tap coordinates are points, not screenshot pixels.
After an app relaunch the default read can also stay stuck on a single zero-size Application
node; one screen_mapper.py --deep read (which may itself time out once) brings it back.
- facebook/idb#978: accessibility custom actions
are listed by
describe-all but can't be performed.
- facebook/idb#954: the Homebrew build is
arm64-only, so Intel Macs are unsupported.
Documentation
- SKILL.md (this file) - Script reference, requirements, troubleshooting
- README.md - Installation, updating idb, Xcode 27 notes
- AGENTS.md - Architecture and implementation details
Key Design Principles
Semantic Navigation: Find elements by meaning (text, type, ID) not pixel coordinates. Survives UI changes.
Token Efficiency: Concise default output (3-5 lines) with optional verbose and JSON modes for detailed results.
Accessibility-First: Built on standard accessibility APIs for reliability and compatibility.
Zero Configuration: Works immediately on any macOS with Xcode. No setup required.
Structured Data: Scripts output JSON or formatted text, not raw logs. Easy to parse and integrate.
Auto-Learning: Build system remembers your device preference. Configuration stored per-project.
Use these scripts directly or let Claude Code invoke them automatically when your request matches the skill description.
1---2name: ios-simulator-skill3version: 1.8.04description: Build, test, and drive iOS apps in the Simulator with 31 token-efficient scripts. Use when asked to build or test an Xcode project, launch an app on a simulator, tap/type/swipe through its UI by accessibility label, take screenshots or visual diffs, audit accessibility, read logs or diagnose hangs, or manage simulators (boot, erase, permissions, location, push, appearance). macOS only; needs Xcode, Python 3.12+ and idb.5metadata:6 source: https://skillmd.com/skills/conorluddy/ios-simulator-skill7---89# iOS Simulator Skill1011Build, test, and automate iOS applications using accessibility-driven navigation and structured data instead of pixel coordinates.1213## Quick Start1415```bash16# 1. Check environment17bash scripts/sim_health_check.sh1819# 2. Launch app20python3 scripts/app_launcher.py --launch com.example.app2122# 3. Map screen to see elements23python3 scripts/screen_mapper.py2425# 4. Tap button26python3 scripts/navigator.py --find-text "Login" --tap2728# 5. Enter text29python3 scripts/navigator.py --find-type TextField --enter-text "user@example.com"30```3132**Paths:** `scripts/` is relative to the directory containing this SKILL.md, not the user's project.33Examples write `scripts/...` for brevity; run them by absolute path from the user's project34(e.g. `python3 <skill-dir>/scripts/navigator.py ...`) so relative Xcode project paths still resolve.3536All scripts support `--help` for detailed options; most support `--json` for machine-readable output.3738## Navigation Strategy3940**Always prefer the accessibility tree over screenshots for navigation.** The accessibility tree gives you element types, labels, frames, and tap targets — structured data that's cheaper and more reliable than image analysis.4142Use this priority:431. `screen_mapper.py` → structured element list (5-7 lines, ~10 tokens)442. `navigator.py --find-text/--find-type/--find-id` → semantic interaction453. Screenshots → only for visual verification, bug reports, or visual diff4647Screenshots cost 1,600–6,300 tokens depending on size. The accessibility tree costs 10–50 tokens in default mode.4849## 31 Production Scripts5051### Build & Development (2 scripts)52531. **build_and_test.py** - Build Xcode projects, run tests, parse results with progressive disclosure54 - Build with live result streaming55 - Parse errors and warnings from xcresult bundles56 - Retrieve detailed build logs on demand57 - `--run` builds, installs and launches the app in one call: `Launched: <bundle> on <device> (pid N)`58 - Tests that never started (parallel clone failed to boot) report `Tests: NOT RUN`, not FAIL; retry with `--no-parallel`59 - Options: `--project`, `--scheme`, `--clean`, `--test`, `--run`, `--no-parallel`, `--verbose`, `--json`60612. **log_monitor.py** - Real-time log monitoring with intelligent filtering62 - Stream logs or capture by duration63 - Filter by severity (error/warning/info/debug)64 - Deduplicate repeated messages65 - Options: `--app`, `--severity`, `--follow`, `--duration`, `--output`, `--json`6667### Device State (4 scripts)68693. **appearance.py** - Control simulator appearance: dark mode, Dynamic Type size, contrast, and locale/region70 - Toggle light/dark theme via `xcrun simctl ui`71 - Set Dynamic Type size with friendly aliases (XS through AX5)72 - `--contrast high|normal` toggles Increase Contrast and reads it back to confirm; `--reset` also restores normal contrast73 - Write locale and region defaults; optional app restart via `--bundle-id`74 - RTL flagged automatically for ar/he/fa/ur/yi locales75 - Options: `--theme`, `--text-size`, `--contrast`, `--locale`, `--region`, `--reset`, `--bundle-id`, `--udid`, `--json`, `--verbose`76774. **location.py** - Simulate GPS coordinates, named city presets, and GPX scenario playback78 - Fix a coordinate with `--lat`/`--lng` or pick a city with `--city`79 - Play a built-in scenario (City Run, Freeway Drive, etc.) via `--gpx <scenario>`80 - Animate multi-waypoint paths with configurable speed via `--waypoints` and `--speed`81 - Clear simulated location with `--clear`; list available scenarios with `--list-scenarios`82 - Options: `--lat`, `--lng`, `--city`, `--gpx`, `--waypoints`, `--speed`, `--clear`, `--list-scenarios`, `--udid`, `--json`, `--verbose`83845. **media.py** - Seed or empty the photo library for photo-picker tests85 - `--add a.jpg b.png` via `xcrun simctl addmedia`86 - `--clear --yes` empties the library via `idb photos clear` (idb 1.7+); `--clear --yes --add` leaves exactly the added files87 - Without `--yes`, `--clear` refuses if the library has photos (they can't be recovered): ask the user first88 - Fails fast on a missing file89 - Options: `--add`, `--clear`, `--yes`, `--udid`, `--json`90916. **duo.py** - Experimental iPhone Duo hinge and interface orientation controls92 - Requires an explicit booted Duo `--udid`; no automatic device selection93 - Read observed angle, active cover/inner display ID and rotation (default or `--state`)94 - `--pose closed|partial|open` (0°/90°/180°), `--angle 0..180`, or `--orientation portrait|landscape|portrait-upside-down|landscape-flipped`95 - Changes verify observed readback; hinge endpoints also verify cover/inner display activation96 - Bundled Objective-C helper compiles and signs with the selected Xcode on first use; no extra CLI97 - Private APIs are experimental; inner-display coordinate touch routing is unverified98 - Options: `--udid`, `--state`, `--pose`, `--angle`, `--orientation`, `--json`, `--verbose`99100### Navigation & Interaction (5 scripts)1011027. **screen_mapper.py** - Analyze current screen and list interactive elements103 - Element type breakdown104 - Interactive button list105 - Text field status106 - If labelled elements cover under 10% of the screen, adds a `Coverage:` line suggesting `--deep`107 - `--deep` reads through idb's axbridge backend (idb 1.7+): also sees Safari/WKWebView content108 and in-app alerts the default read misses, plus many unlabelled container views. It turns on109 the device's accessibility automation mode (not restored afterwards). Web-content frames are110 relative to the web view, so use `--deep` to find elements, not to take tap coordinates111 - Options: `--verbose`, `--hints`, `--deep`, `--json`1121138. **navigator.py** - Find and interact with elements semantically114 - Find by text (fuzzy, or exact with `--find-exact`); interactive leaf elements rank above containers sharing the label115 - Find by element type116 - Find by accessibility ID117 - Enter text or tap elements118 - `--tap` on a Button/Link/Switch/CheckBox/Tab with a unique accessibility ID or label uses an accessibility press119 (idb 1.7+), so overlays like a floating search bar can't intercept it; output says120 `(accessibility press)`. Otherwise it taps the frame center121 - `--set-value TEXT` replaces a field's value without the keyboard (any characters, idb 1.7+).122 Focus doesn't move, so use `--enter-text` when a Return key must submit afterwards123 The value is read back before success is claimed (not for secure fields); a mismatch exits 1124 - `--tap --expect VALUE` taps only if the element's value is VALUE (toggles: `1` on, `0` off) and125 exits 1 without tapping otherwise, so "turn X off" is safe to repeat126 - iOS 27 reports toggles as `CheckBox`. Only a press flips them (no HID touch does, even on the127 switch itself); if neither ID nor label is unique, the output warns to check the value128 - A frozen app stalls every read and tap until its main thread responds129 - Failures include idb's stderr (e.g. a dead companion)130 - Options: `--find-text`, `--find-exact`, `--find-type`, `--find-id`, `--index`, `--tap`, `--expect`, `--tap-at`, `--enter-text`, `--set-value`, `--list`1311329. **gesture.py** - Perform swipes, scrolls, pinches, and complex gestures133 - Directional swipes (up/down/left/right) - `--swipe` is the direction the finger moves134 - Multi-swipe scrolling - `--scroll` is the direction the content moves (`down` reveals content below)135 - Pinch zoom via `idb ui pinch` (`--pinch out` zooms in; `--scale` sets an explicit factor)136 - Long press via `idb ui tap --duration`137 - Pull to refresh138 - `--double-tap X,Y [--tap-count N]` - multi-tap at a point (idb 1.7+)139 - `--drag SOURCE DEST` - press-hold, drag, release; each end is `x,y` or an accessibility label,140 e.g. `--drag "Row 1" "Row 4"` (idb 1.7+)141 - `--rotate portrait|portrait-upside-down|landscape-left|landscape-right` - physical device rotation (idb 1.7+)142 - `--shake` - shake the device, for debug menus and undo (idb 1.7+)143 - Options: `--swipe`, `--swipe-from/--swipe-to`, `--scroll`, `--scroll-amount`, `--pinch`, `--scale`, `--long-press`, `--duration`, `--refresh`, `--double-tap`, `--tap-count`, `--drag`, `--rotate`, `--shake`14414510. **keyboard.py** - Text input and hardware button control146 - Type text (fast or slow; ASCII only)147 - Special keys (return, delete, tab, space, escape, arrows), single letters, or raw HID codes148 - Key sequences (`--key-sequence h,i,return`)149 - Key chords: `--key z --command --shift` (redo); `--shift/--control/--option` need idb 1.7+150 - Clear the focused field (Cmd+A, delete)151 - Hardware buttons: home, lock/power, side, siri, apple-pay, volume-up/down (volume needs idb 1.6.3+)152 - Options: `--type`, `--slow`, `--key`, `--shift`, `--control`, `--option`, `--command`, `--count`, `--key-sequence`, `--button`, `--clear`, `--dismiss`15315411. **app_launcher.py** - App lifecycle management155 - Launch apps by bundle ID156 - Terminate apps157 - Install/uninstall from .app bundles (`--uninstall` needs `--yes`: the app's data is deleted)158 - Deep link navigation159 - List installed apps160 - Check app state161 - Pass launch arguments (`--args`) and environment variables (`--env KEY=VALUE`, injected as `SIMCTL_CHILD_*`) to the app on launch/restart162 - Options: `--launch`, `--terminate`, `--restart`, `--install`, `--uninstall`, `--yes`, `--open-url`, `--list`, `--state`, `--args`, `--env`, `--wait-for-debugger`163164### Testing & Analysis (9 scripts)16516612. **accessibility_audit.py** - Check WCAG compliance on current screen167 - Critical issues (missing labels, empty buttons, no alt text)168 - Warnings (missing hints, small touch targets)169 - Info (missing IDs, deep nesting)170 - Options: `--verbose`, `--output`, `--json`17117213. **visual_diff.py** - Compare two screenshots for visual changes173 - Pixel-by-pixel comparison174 - Threshold-based pass/fail175 - Generate diff images176 - Options: `--threshold`, `--output`, `--details`, `--json`17717814. **test_recorder.py** - Automatically document test execution179 - Capture screenshots and accessibility trees per step180 - Generate markdown reports with timing data181 - Options: `--test-name`, `--output`, `--verbose`, `--json`18218315. **app_state_capture.py** - Create comprehensive debugging snapshots184 - Screenshot, UI hierarchy, app logs, device info185 - Markdown summary for bug reports186 - Options: `--app-bundle-id`, `--output`, `--log-lines`, `--json`18718816. **sim_health_check.sh** - Verify environment is properly configured189 - Check macOS, Xcode, simctl, IDB, Python190 - List available and booted simulators191 - Verify Python packages (Pillow)19219317. **model_inspector.py** - Inspect Core Data and SwiftData models from project files194 - Parse .xcdatamodeld packages (entities, attributes, relationships)195 - Detect model versions and current active version196 - Best-effort SwiftData @Model class extraction197 - Raw source dump for any model on demand (`--raw ModelName`)198 - Options: `--project-path`, `--core-data-only`, `--swiftdata-only`, `--show-versions`, `--raw`, `--verbose`, `--json`19920018. **container.py** - Inspect app sandbox: files, UserDefaults, and Core Data store paths201 - List data container files at configurable depth via `--ls`202 - Read files with auto-detected plist decoding via `--cat` (large files cached)203 - Dump UserDefaults as key=value or JSON via `--userdefaults`204 - Locate `.sqlite` / `.sqlite-wal` / `.sqlite-shm` stores via `--core-data-path`205 - Export full container snapshot via `--export`206 - Options: `--ls`, `--cat`, `--userdefaults`, `--core-data-path`, `--export`, `--udid`, `--json`, `--verbose`20720819. **hang_watcher.py** (HangBuster) - Record + summarise os_log hang events with progressive disclosure209 - **Session mode (HangBuster, agent-native):** start a detached recorder, interact with the simulator, stop for a token-tight summary210 - `--start` → returns a session ID; detached worker normalises + thresholds events on the fly211 - `--stop SESSION_ID` → emits ~80–120 token L1 summary (header + top-N clusters + drill hint)212 - `--get-details SESSION_ID [--cluster N | --raw]` → L2 full clusters or L3 per-event detail213 - `--list-sessions` / `--clear-sessions [--older-than 24h]` / `--diff A B` (cross-session regression report)214 - Filter pipeline: parse → normalise → threshold → bucket → cluster → aggregate → rank → format (in `common/hang_pipeline.py`)215 - `--budget-tokens N` picks the densest level (L0/L1/L2) that fits; `--terse` forces L0216 - `--auto-sample` captures a main-thread stack on first event per cluster (soft dependency: `main_thread_sampler.py` #62; graceful no-op if absent)217 - **Raw capture mode (full fidelity for `jq` exploration):** skip the clustering pipeline, dump every matching log line verbatim to `raw.ndjson`218 - `--start --raw-capture [--max-size-mb 10] [--no-gzip]` — spawns `log stream --style ndjson`219 - Per-session size cap (`--max-size-mb`, default 10) — worker stops cleanly on cap; `extras.truncated=true`220 - `--stop` gzips `raw.ndjson` → `raw.ndjson.gz` (~15–19× compression; `--no-gzip` opts out)221 - `--get-details SESSION_ID` on a raw session prints the path with a `zcat | jq ...` hint222 - **Resilience (auto-restart on stream death):** EOF or subprocess death triggers a `stream_died` event then a bounded restart with 2s backoff. After `IOS_SIM_HANG_MAX_RESTARTS` (default 3) the session is marked `crashed`, never left in stale `running` state. `--list-sessions` shows `capture=Xs` and `restarts=N`.223 - **Cleanup is automatic:** TTL prune (`IOS_SIM_HANG_SESSION_TTL_HOURS`, default 24h) + aggregate cap (`IOS_SIM_HANG_TOTAL_CAP_MB`, default 100 MB, oldest-first eviction) both run on every `--start`.224 - **Legacy modes (unchanged for backward compat):** `--watch [--duration N]` (live stream) and `--since 5m` (historical)225 - Filters: `--bundle-id` (post-parse — hang capture stays simulator-global so RunningBoard/SpringBoard events are kept), `--predicate` (also via `IOS_SIM_HANG_PREDICATE`)226 - All output supports `--json`; session storage at `~/.ios-simulator-skill/sessions/<id>/{meta.json,events.jsonl,summary.json,raw.ndjson.gz}`227228 **Quick start (summarised mode):**229 ```bash230 SID=$(python3 scripts/hang_watcher.py --start --min-hang-ms 200)231 # ... interact with the simulator (open sheets, scroll, navigate) ...232 python3 scripts/hang_watcher.py --stop $SID # token-tight L1 summary233 python3 scripts/hang_watcher.py --get-details $SID --cluster 1 # drill into cluster 1234 python3 scripts/hang_watcher.py --diff $SID_BASELINE $SID # cross-session regression235 ```236237 **Quick start (raw capture + `jq` exploration):**238 ```bash239 SID=$(python3 scripts/hang_watcher.py --start --raw-capture --max-size-mb 5)240 # ... interact with the simulator ...241 python3 scripts/hang_watcher.py --stop $SID242 # → "Session ...: raw mode, 737 lines, 0.96 MB → 0.05 MB gzipped"243244 # Top processes by event count:245 zcat ~/.ios-simulator-skill/sessions/$SID/raw.ndjson.gz \246 | jq -s 'group_by(.processImagePath) | map({proc: (.[0].processImagePath | split("/") | last), n: length}) | sort_by(-.n) | .[:5]'247248 # All RunningBoard assertion invalidations:249 zcat .../raw.ndjson.gz | jq -c 'select(.subsystem == "com.apple.runningboard" and (.eventMessage | startswith("Invalidating")))'250251 # Hangs per minute:252 zcat .../raw.ndjson.gz | jq -r '.timestamp[:16]' | sort | uniq -c253 ```25425520. **localization_audit.py** - Detect string catalog gaps, missing keys, and placeholder mismatches256 - Report missing and `needs_review`/`new` keys per locale in `.xcstrings` catalogs257 - Cross-reference catalog keys against Swift source (`String(localized:)` / `NSLocalizedString`) via `--source`258 - Flag placeholder count mismatches (`%d`, `%@`, `%s`, `%lld`) across locales259 - Legacy `.strings` and `.stringsdict` support via `plistlib`260 - CI-friendly `--strict` exits 2 on any finding261 - Options: `--catalog`, `--source`, `--locale`, `--strict`, `--json`, `--verbose`262263### Advanced Testing & Permissions (4 scripts)26426521. **clipboard.py** - Manage simulator clipboard for paste testing266 - Copy text to clipboard267 - Test paste flows without manual entry268 - Options: `--copy`, `--test-name`, `--expected`, `--json`26927022. **status_bar.py** - Override simulator status bar appearance271 - Presets: clean (9:41, 100% battery), testing (11:11, 50%), low-battery (20%), airplane (offline)272 - Custom time, network, battery, WiFi settings273 - Options: `--preset`, `--time`, `--data-network`, `--battery-level`, `--clear`, `--json`27427523. **push_notification.py** - Send simulated push notifications276 - Simple mode (title + body + badge)277 - Custom JSON payloads278 - Test notification handling and deep links279 - `--list` shows delivered notifications; `--clear` withdraws them all (both idb 1.7+; sending stays on simctl)280 - A push sent while its app is in the foreground isn't delivered to Notification Center, so `--list` won't show it281 - Options: `--bundle-id`, `--title`, `--body`, `--badge`, `--payload`, `--list`, `--clear`, `--json`28228324. **privacy_manager.py** - Grant, revoke, and reset app permissions284 - 13 supported services (camera, microphone, location, contacts, photos, calendar, health, etc.)285 - Batch operations (comma-separated services)286 - Audit trail with test scenario tracking287 - Options: `--bundle-id`, `--grant`, `--revoke`, `--reset`, `--list`, `--json`288289### Simulator Discovery (2 scripts)29029125. **sim_list.py** - List simulators with progressive disclosure292 - Concise summary by default (total / available / booted)293 - Full details on demand via cache IDs294 - Filter by device type295 - Suggest recommended simulators with `--suggest`296 - 96% token reduction vs raw `simctl list` (57k → 2k tokens)297 - Options: `--get-details`, `--suggest`, `--device-type`, `--json`29829926. **simulator_selector.py** - Suggest the best simulator for the job300 - Ranks candidates by recent use (from `config.json`), latest iOS, common test models, and boot status301 - List all available simulators with `--list`302 - Boot a selected simulator directly with `--boot`303 - JSON output for programmatic use304 - Options: `--suggest`, `--list`, `--boot`, `--json`305306### Device Lifecycle Management (5 scripts)30730827. **simctl_boot.py** - Boot simulators with optional readiness verification309 - Boot by UDID or device name310 - Wait for device ready with timeout311 - Batch boot operations (--all, --type)312 - Performance timing313 - Options: `--udid`, `--name`, `--wait-ready`, `--timeout`, `--all`, `--type`, `--json`31431528. **simctl_shutdown.py** - Gracefully shutdown simulators316 - Shutdown by UDID or device name317 - Optional verification of shutdown completion318 - Batch shutdown operations319 - Options: `--udid`, `--name`, `--verify`, `--timeout`, `--all`, `--type`, `--json`32032129. **simctl_create.py** - Create simulators dynamically322 - Create by device type and iOS version323 - List available device types and runtimes324 - Custom device naming325 - Returns UDID for CI/CD integration326 - Options: `--device`, `--runtime`, `--name`, `--list-devices`, `--list-runtimes`, `--json`32732830. **simctl_delete.py** - Permanently delete simulators329 - Delete by UDID or device name330 - Refuses without `--yes` (no prompt; the simulator and its data can't be recovered): ask the user first331 - Batch delete operations332 - Smart deletion (--old N to keep N per device type)333 - Options: `--udid`, `--name`, `--yes`, `--all`, `--type`, `--old`, `--json`33433531. **simctl_erase.py** - Factory reset simulators without deletion336 - Preserve device UUID (faster than delete+create)337 - Erase all, by type, or booted simulators338 - Optional verification339 - Refuses without `--yes` (apps, data and settings can't be recovered): ask the user first340 - Options: `--udid`, `--name`, `--yes`, `--verify`, `--timeout`, `--all`, `--type`, `--booted`, `--json`341342## Duo workflow343344```bash345python3 scripts/duo.py --udid <DUO_UDID> --pose open346python3 scripts/duo.py --udid <DUO_UDID> --state --json347# Use the observed display_id, rather than assuming which display is active.348python3 scripts/app_state_capture.py --udid <DUO_UDID> --display 3 --output duo-state349python3 scripts/test_recorder.py --udid <DUO_UDID> --display 3 --test-name duo-layout350```351352`--display` selects the screenshot display in file and inline modes; accessibility trees remain353independent and provide no verified coordinate mapping to that display. Rotation polls observed354interface state across native orientation candidates because sensor and interface orientation may355differ. The five-second verification polling window excludes initial reads and hinge dispatch;356individual commands have separate timeouts, so total requests can take longer. If a change times357out, inspect observed state before retrying. Inactive displays may capture black frames.358359The private backend credits [hinge](https://github.com/artemnovichkov/hinge) and360[duoctl](https://github.com/skarol/duoctl) mechanism research. Replace folding and rotation361independently when supported headless APIs offer equivalent control and observed readback;362XCTest-only hinge APIs are insufficient. Video display selection is outside this package's scope.363364## Common Patterns365366**Auto-UDID Detection**: Most scripts auto-detect the booted simulator if --udid is not provided.367368**Device Name Resolution**: Use device names (e.g., "iPhone 16 Pro") instead of UDIDs - scripts resolve automatically.369370**Batch Operations**: Many scripts support `--all` for all simulators or `--type iPhone` for device type filtering.371372**Output Formats**: Default is concise human-readable output. Use `--json` for machine-readable output in CI/CD.373374**Help**: All scripts support `--help` for detailed options and examples.375376**Screenshot Sizing**: Screenshots are resized to save tokens. Presets: `full` (3-4 tiles, ~5K tokens), `half` (1 tile, ~1.6K tokens, default), `quarter` (1 tile, ~800 tokens, less detail). Use `quarter` for quick visual checks, `half` for readable UI, `full` only when pixel-level detail matters. Scripts that capture screenshots (`app_state_capture.py`, `test_recorder.py`) default to `half`.377378## Typical Workflow3793801. Verify environment: `bash scripts/sim_health_check.sh`3812. Launch app: `python3 scripts/app_launcher.py --launch com.example.app`3823. Analyze screen: `python3 scripts/screen_mapper.py`3834. Interact: `python3 scripts/navigator.py --find-text "Button" --tap`3845. Verify: `python3 scripts/accessibility_audit.py`3856. Debug if needed: `python3 scripts/app_state_capture.py --app-bundle-id com.example.app`386387## Configuration388389Most operational limits can be tuned via environment variables. Defaults work for typical local development; raise them for slow CI runners, large monorepo builds, or accessibility audits on complex screens.390391| Variable | Default | Controls |392|---|---|---|393| `IOS_SIM_A11Y_LABEL_MAX` | `80` | Max chars of `AXLabel` retained in accessibility audit output |394| `IOS_SIM_A11Y_TOP_ISSUES` | `10` | Top accessibility issues surfaced per audit |395| `IOS_SIM_APPS_PREVIEW` | `30` | App entries listed by `app_launcher.py` before truncation |396| `IOS_SIM_BOOT_SUBPROCESS_TIMEOUT` | `60` | Timeout for the `simctl boot` subprocess itself (seconds) |397| `IOS_SIM_BOOT_TIMEOUT` | `300` | Wait-for-ready timeout after boot (seconds) |398| `IOS_SIM_BUILD_JSON_CAP` | `50` | Max build errors / failed tests in JSON output |399| `IOS_SIM_BUILD_LOG_PREVIEW` | `4000` | Chars of build log preview in default output |400| `IOS_SIM_BUILD_TIMEOUT` | `1800` | Max seconds for an `xcodebuild build` invocation before kill |401| `IOS_SIM_INTROSPECT_TIMEOUT` | `60` | Timeout for `xcodebuild -list` and `simctl list` lookups (seconds) |402| `IOS_SIM_TEST_TIMEOUT` | `2700` | Max seconds for an `xcodebuild test` invocation before kill |403| `IOS_SIM_BUILD_SUMMARY_CAP` | `15` | Errors/failures in default build summary |404| `IOS_SIM_BUILD_VERBOSE_CAP` | `100` | Errors/warnings in verbose build output |405| `IOS_SIM_CACHE_MAX_ENTRIES` | `500` | Max entries in progressive disclosure cache (LRU eviction) |406| `IOS_SIM_CACHE_TTL_HOURS` | `1` | Cache entry expiration |407| `IOS_SIM_ERASE_TIMEOUT` | `90` | Wait-for-erase timeout (seconds) |408| `IOS_SIM_HANG_PREDICATE` | _(default)_ | Override the `os_log` predicate used by `hang_watcher.py` (default catches RunningBoard kills + "Hang detected" + main-thread hangs). Hang events originate from system daemons (RunningBoard, SpringBoard) so the predicate stays simulator-global — `--bundle-id` is applied post-parse, not ANDed in. |409| `IOS_SIM_HANG_MIN_MS` | `250` | HangBuster threshold — events below this duration never reach disk (smaller = more sensitive, larger summaries) |410| `IOS_SIM_HANG_SESSION_TTL_HOURS` | `24` | HangBuster session prune age; pruning runs on every `--start` |411| `IOS_SIM_HANG_DEFAULT_TOP_N` | `3` | Default top-N clusters in `--stop` L1 output |412| `IOS_SIM_HANG_BUDGET_TOKENS` | _(unset)_ | Default token budget for `--stop` (picks L0/L1/L2 to fit) |413| `IOS_SIM_HANG_MAX_RESTARTS` | `3` | HangBuster worker: max `log stream` respawn attempts on EOF/subprocess death before the session is marked `crashed` |414| `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. |415| `IOS_SIM_LOG_JSON_CAP` | `100` | Max errors/warnings in `log_monitor.py` JSON output |416| `IOS_SIM_LOG_LINE_MAX` | `300` | Per-line truncation in log summaries |417| `IOS_SIM_LOG_TAIL` | `200` | Lines of log tail in verbose / sample output |418| `IOS_SIM_LOG_TEXT_SUMMARY` | `15` | Errors/warnings shown in text-mode log summary |419| `IOS_SIM_MAX_ELEMENTS` | `25` | Items listed by `navigator.py --list` and `push_notification.py --list` |420| `IOS_SIM_POLL_INTERVAL` | `0.5` | Boot/erase state polling interval (seconds) |421| `IOS_SIM_RELAUNCH_DELAY_MS` | `1000` | Delay between terminate and re-launch in `app_launcher.py` |422| `IOS_SIM_SCREEN_BUTTONS_PREVIEW` | `15` | Button names listed by `screen_mapper.py` |423| `IOS_SIM_SCREEN_SECTION_ITEMS` | `10` | Items per section shown by `screen_mapper.py` |424| `IOS_SIM_STATE_SUBPROCESS_TIMEOUT` | `15` | Subprocess timeout in `app_state_capture.py` (seconds) |425| `IOS_SIM_TAP_SETTLE_MS` | `500` | Post-tap settle delay in `navigator.py` |426427Example:428429```bash430# Slow GitHub Actions runner: give boot 10 minutes431IOS_SIM_BOOT_TIMEOUT=600 python3 scripts/simctl_boot.py --wait-ready432```433434## Requirements435436- macOS 15 (Sequoia)+437- Xcode 26+ (the full app; Command Line Tools alone are not enough for idb)438- Apple silicon Mac (the Homebrew idb build is arm64-only)439- Python 3.12+440- `idb` **1.5.1+** (1.6.3+ recommended) - required for every interactive script (tap, swipe, type):441 `brew install facebook/fb/idb` (installs both idb-cli and idb-companion)442- Pillow, for visual diffs only: `pip3 install pillow`443444Verify with `bash scripts/sim_health_check.sh` (add `--json` for structured output).445446## Troubleshooting447448**Taps, swipes and typing do nothing, but reads work.** `idb` reports success and the screen449never changes. On Xcode 27 this means `idb-companion` is older than 1.5.1: it looks for450`SimulatorKit.framework` at the path Xcode 26 used. Upgrade both together, then restart running451companions: `brew upgrade facebook/fb/idb-cli facebook/fb/idb-companion && idb kill`.452453**`SimulatorKit is required for HID interactions`.** Same cause, same fix.454455**Health check warns "idb companions started before idb-companion was last installed".** Those456companions still run the pre-upgrade binary. Run `idb kill`; the next idb call starts a fresh one.457458**`Connection refused` or `No such file` from every idb call.** A dead companion is still in459idb's registry at `/tmp/idb/state`, so idb dials a socket nobody is listening on instead of460starting a fresh companion. Fix: `idb disconnect <udid>`.461462**`open -a Simulator` fails.** Xcode 27 has no `Simulator.app`; it was replaced by463`DeviceHub.app` in `Xcode.app/Contents/Applications/`. Boot headlessly instead:464`xcrun simctl boot <udid>`. Note that quitting DeviceHub shuts down the simulator it hosts.465466**`idb: command not found`.** The companion and the CLI are separate packages;467`brew install facebook/fb/idb` installs both. If `which -a idb` shows more than one, the first on468`PATH` wins. An old pip `fb-idb` there needs `pip uninstall fb-idb`.469470**Known upstream idb issues** (open as of idb 1.7.6):471- [facebook/idb#964](https://github.com/facebook/idb/issues/964): on some iOS 26+ screens472 `describe-all` returns only the application node, and SpringBoard alerts can't be tapped. The473 default `ax` backend can't see across process boundaries; try474 `idb ui describe-all --json --api axbridge`. Tap coordinates are points, not screenshot pixels.475 After an app relaunch the default read can also stay stuck on a single zero-size Application476 node; one `screen_mapper.py --deep` read (which may itself time out once) brings it back.477- [facebook/idb#978](https://github.com/facebook/idb/issues/978): accessibility custom actions478 are listed by `describe-all` but can't be performed.479- [facebook/idb#954](https://github.com/facebook/idb/issues/954): the Homebrew build is480 arm64-only, so Intel Macs are unsupported.481482## Documentation483484- **SKILL.md** (this file) - Script reference, requirements, troubleshooting485- **[README.md](https://github.com/conorluddy/ios-simulator-skill/blob/main/README.md)** - Installation, updating idb, Xcode 27 notes486- **[AGENTS.md](https://github.com/conorluddy/ios-simulator-skill/blob/main/AGENTS.md)** - Architecture and implementation details487488## Key Design Principles489490**Semantic Navigation**: Find elements by meaning (text, type, ID) not pixel coordinates. Survives UI changes.491492**Token Efficiency**: Concise default output (3-5 lines) with optional verbose and JSON modes for detailed results.493494**Accessibility-First**: Built on standard accessibility APIs for reliability and compatibility.495496**Zero Configuration**: Works immediately on any macOS with Xcode. No setup required.497498**Structured Data**: Scripts output JSON or formatted text, not raw logs. Easy to parse and integrate.499500**Auto-Learning**: Build system remembers your device preference. Configuration stored per-project.501502---503504Use these scripts directly or let Claude Code invoke them automatically when your request matches the skill description.