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:

1. screen_mapper.py → structured element list (5-7 lines, ~10 tokens)
2. navigator.py --find-text/--find-type/--find-id → semantic interaction
3. 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.

30 Production Scripts

Build & Development (2 scripts)

1. 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
   • Options: --project, --scheme, --clean, --test, --verbose, --json
2. 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 (3 scripts)

3. 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
4. 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
5. 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

Navigation & Interaction (5 scripts)

6. 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
7. 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
8. 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
9. 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
10. 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)

11. 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
12. 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
13. 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
14. 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
15. sim_health_check.sh - Verify environment is properly configured
    • Check macOS, Xcode, simctl, IDB, Python
    • List available and booted simulators
    • Verify Python packages (Pillow)
16. 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
17. 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

18. 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

19. 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)

20. clipboard.py - Manage simulator clipboard for paste testing
    • Copy text to clipboard
    • Test paste flows without manual entry
    • Options: --copy, --test-name, --expected, --json
21. 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
22. 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
23. 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)

24. 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
25. 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)

26. 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
27. 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
28. 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
29. 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
30. 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

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

1. Verify environment: bash scripts/sim_health_check.sh
2. Launch app: python3 scripts/app_launcher.py --launch com.example.app
3. Analyze screen: python3 scripts/screen_mapper.py
4. Interact: python3 scripts/navigator.py --find-text "Button" --tap
5. Verify: python3 scripts/accessibility_audit.py
6. 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.

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.