Skip to content
Back to search

conorluddy

MarketplaceWorks with Claude CodeGitHub

iOS simulator automation skills for Claude Code and Codex

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/conorluddy-ios-simulator-skill/badge.svg)](/listings/conorluddy-ios-simulator-skill)

HTML

<a href="/listings/conorluddy-ios-simulator-skill"><img src="/api/listings/conorluddy-ios-simulator-skill/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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](https://github.com/vercel-labs/skills) 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](https://github.com/facebook/idb/issues/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](#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

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 14 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. {
  2. "name": "conorluddy",
  3. "owner": {
  4. "name": "Conor Luddy"
  5. },
  6. "description": "iOS simulator automation skills for Claude Code and Codex",
  7. "plugins": [
  8. {
  9. "name": "ios-simulator-skill",
  10. "source": "./ios-simulator-skill",
  11. "description": "31 scripts for iOS app building, testing, and simulator automation. Semantic UI navigation via the accessibility tree, xcodebuild with progressive error disclosure, accessibility audits, hang detection, and simulator lifecycle management."
  12. }
  13. ]
  14. }
README.md · README · 428 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # iOS Simulator Skill for Agents
  2. Production-ready skill for building, testing, and automating iOS apps. 31 scripts optimized for both human developers and AI agents.
  3. If you prefer MCP, [XC-MCP](https://github.com/conorluddy/xc-mcp) was the original source of this toolkit before Skills were even a thing, and can be run from [NPM](https://www.npmjs.com/package/xc-mcp) too)
  4. https://github.com/user-attachments/assets/b1c4225a-e083-4c4b-96bd-0d20a41f9b1f
  5. ## Xcode Build + Simulator Automation
  6. This skill covers both sides of iOS development:
  7. - **Xcode builds** via `xcodebuild` — compile, test, and parse results with progressive error disclosure
  8. - **Simulator interaction** via `xcrun simctl` and `idb` — semantic UI navigation, accessibility testing, device lifecycle
  9. ## Install it
  10. ### Claude Code — plugin marketplace (recommended)
  11. ```
  12. /plugin marketplace add conorluddy/ios-simulator-skill
  13. /plugin install ios-simulator-skill@conorluddy
  14. ```
  15. ### Codex — plugin marketplace (recommended)
  16. ```bash
  17. codex plugin marketplace add conorluddy/ios-simulator-skill
  18. codex plugin add ios-simulator-skill@conorluddy
  19. ```
  20. Or run `/plugins` inside Codex and install it from the `conorluddy` marketplace. Start a new
  21. Codex session afterwards. Update later with `codex plugin marketplace upgrade conorluddy`.
  22. ### Any agent — `npx skills`
  23. The [`skills` CLI](https://github.com/vercel-labs/skills) finds `SKILL.md` inside the repo and
  24. copies it into the right directory for each agent it detects (Claude Code, Codex, Cursor and
  25. others). It needs Node.js 18+.
  26. ```bash
  27. npx skills add conorluddy/ios-simulator-skill # project-level (./.claude/skills, ./.agents/skills, ...)
  28. npx skills add conorluddy/ios-simulator-skill -g # user-level, for every project
  29. npx skills add conorluddy/ios-simulator-skill -a claude-code # only one agent
  30. ```
  31. Restart your agent afterwards so it picks the skill up.
  32. ### Manual install
  33. A skill is loaded from `SKILL.md` at the root of its directory:
  34. | Agent | User-level skills | Project-level skills |
  35. |---|---|---|
  36. | Claude Code | `~/.claude/skills/<name>/SKILL.md` | `.claude/skills/<name>/SKILL.md` |
  37. | Codex | `~/.agents/skills/<name>/SKILL.md` | `.agents/skills/<name>/SKILL.md` |
  38. The commands below use the Claude Code path; swap in `~/.agents/skills` for Codex.
  39. This repository is a *plugin*, so the skill itself lives at
  40. `ios-simulator-skill/skills/ios-simulator-skill/`; cloning the whole repo into your skills
  41. directory puts `SKILL.md` three levels too deep and the skill will not load.
  42. **From a release** (simplest):
  43. ```bash
  44. curl -L https://github.com/conorluddy/ios-simulator-skill/releases/latest/download/ios-simulator-skill.zip -o skill.zip
  45. unzip skill.zip -d ~/.claude/skills/ios-simulator-skill
  46. ```
  47. **From a clone** (to track `main`):
  48. ```bash
  49. git clone https://github.com/conorluddy/ios-simulator-skill.git ~/src/ios-simulator-skill
  50. cp -R ~/src/ios-simulator-skill/ios-simulator-skill/skills/ios-simulator-skill \
  51. ~/.claude/skills/ios-simulator-skill
  52. ```
  53. For a project-local install, use the project-level path from the table instead.
  54. Restart Claude Code afterwards (Codex picks up new skills automatically; restart it if the skill
  55. doesn't appear). Verify `SKILL.md` sits at the root of the destination:
  56. ```bash
  57. ls ~/.claude/skills/ios-simulator-skill/SKILL.md # Claude Code
  58. ls ~/.agents/skills/ios-simulator-skill/SKILL.md # Codex
  59. ```
  60. ### Prerequisites
  61. | Requirement | Version | Needed for |
  62. |---|---|---|
  63. | macOS | 15 (Sequoia)+ | everything |
  64. | Xcode (full app, not just Command Line Tools) | 26+ | building, `simctl`, idb |
  65. | Python | **3.12+** | every script |
  66. | `idb` (CLI + companion) | **1.5.1+** (1.6.3+ recommended) | tapping, swiping, typing |
  67. | Pillow | any | visual diffs only (`pip3 install pillow`) |
  68. **Install idb** — required for every interactive script (`navigator.py`, `gesture.py`, `keyboard.py`):
  69. ```bash
  70. brew install facebook/fb/idb # installs idb-cli and idb-companion
  71. ```
  72. The Homebrew build is prebuilt: it needs an Apple silicon Mac, macOS 15+, and a full Xcode 26+
  73. selected with `xcode-select` (Command Line Tools alone are not enough). Intel Macs are not
  74. supported ([facebook/idb#954](https://github.com/facebook/idb/issues/954)).
  75. > `brew install idb-companion` no longer works: idb-companion was removed from Homebrew
  76. > core and now lives in Meta's own `facebook/fb` tap. If you followed older instructions,
  77. > see [Updating idb](#updating-idb).
  78. To verify everything at once:
  79. ```bash
  80. bash scripts/sim_health_check.sh # add --json for machine-readable output
  81. ```
  82. ### Updating idb
  83. **On Xcode 27, `idb-companion` must be 1.5.1 or newer.** Older builds look for
  84. `SimulatorKit.framework` where Xcode 26 kept it. Under Xcode 27 the companion still starts and
  85. the accessibility tree still reads correctly, but every tap, swipe and keystroke is silently
  86. dropped — `idb` reports success and nothing happens on screen.
  87. ```bash
  88. brew upgrade facebook/fb/idb-cli facebook/fb/idb-companion
  89. brew list --versions idb-cli idb-companion # expect matching versions, >= 1.5.1
  90. ```
  91. Upgrade the CLI and companion together. Newer client features are served by the companion, so
  92. a 1.7 CLI talking to a 1.5 companion fails or falls back to older output. Companions that are
  93. already running keep the old binary until restarted, so run `idb kill` after upgrading.
  94. **Pinning or bisecting idb.** The `facebook/fb` tap carries only the newest release, so Homebrew
  95. can't install an older one. Upstream's `homebrew.py` (in the root of
  96. [facebook/idb](https://github.com/facebook/idb)) installs CI builds instead, into a separate local
  97. tap. It needs a GitHub token (`GITHUB_TOKEN`, `GH_TOKEN` or a logged-in `gh`):
  98. ```bash
  99. curl -fsSLO https://raw.githubusercontent.com/facebook/idb/main/homebrew.py
  100. python3 homebrew.py builds # releases and recent CI builds of main
  101. python3 homebrew.py install <commit-sha> # or pr:<n>, run:<id>; a tag works only if it's the newest
  102. python3 homebrew.py status # what is installed, from which build
  103. python3 homebrew.py uninstall --restore # back to facebook/fb/idb
  104. ```
  105. Coming from the old pip package? An old `fb-idb` (1.1.x) left in a pyenv or virtualenv shadows
  106. the Homebrew CLI if it comes first on your `PATH`, so check with `which -a idb`. Remove it with
  107. `pip uninstall fb-idb` (then `pyenv rehash` under pyenv). `sim_health_check.sh` detects this.
  108. ### Xcode 27 notes
  109. - **There is no `Simulator.app`.** Xcode 27 replaced it with `DeviceHub.app`, in
  110. `Xcode.app/Contents/Applications/`. Scripts drive simulators headlessly via `simctl` and `idb`,
  111. so you rarely need either — but `open -a Simulator` will fail.
  112. - Quitting DeviceHub shuts down the simulator it is hosting.
  113. - If `idb` calls start failing with `Connection refused` after a crash or a manual `pkill`, a dead
  114. companion is still registered. Clear it with `idb disconnect <udid>`; `sim_health_check.sh`
  115. detects this.
  116. ## Features
  117. ### Xcode Build with Progressive Disclosure
  118. The `build_and_test.py` script wraps `xcodebuild` with token-efficient output. A build returns a single summary line with an xcresult ID:
  119. ```
  120. Build: SUCCESS (0 errors, 3 warnings) [xcresult-20251018-143052]
  121. ```
  122. Then drill into details on demand:
  123. ```bash
  124. python scripts/build_and_test.py --get-errors xcresult-20251018-143052
  125. python scripts/build_and_test.py --get-warnings xcresult-20251018-143052
  126. python scripts/build_and_test.py --get-log xcresult-20251018-143052
  127. ```
  128. 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.
  129. This keeps agent conversations focused — no walls of build output unless you ask for them.
  130. ### Simulator Navigation via Accessibility
  131. Instead of fragile pixel-coordinate tapping, all navigation uses iOS accessibility APIs to find elements by meaning:
  132. ```bash
  133. # Fragile — breaks if UI changes
  134. idb ui tap 320 400
  135. # Robust — finds by meaning
  136. python scripts/navigator.py --find-text "Login" --tap
  137. ```
  138. The raw accessibility tree is not cheap on its own: `idb ui describe-all` often costs more than a
  139. screenshot. The win is the summary the skill builds from it: element types, labels and tap
  140. targets in 3-5 lines. See [AI-Accessible Apps](https://www.conor.fyi/writing/ai-access) for more on
  141. why accessibility-first navigation matters for AI agents.
  142. ### What it costs to see a screen
  143. Measured walking 6 screens of a real SwiftUI app on an iPhone 17 Pro simulator (iOS 27).
  144. Text tokens are estimated at characters ÷ 4, image tokens at width × height ÷ 750.
  145. | Way of seeing a screen | Per screen (median) | 6-screen run |
  146. |---|---|---|
  147. | Screenshot, full size | ~1,500 | ~9,000 |
  148. | Raw `idb ui describe-all --json` | ~6,700 (largest: ~58,000) | ~91,000 |
  149. | `screen_mapper.py` summary | ~35 | ~250 |
  150. A single lookup is smaller still: `navigator.py --find-text "Springs"` prints
  151. `Found: Button "Springs" at (201, 1367)`, about 10 tokens.
  152. ### Screenshot Token Optimization
  153. When you do need pixels (visual verification, bug reports, diffs), `app_state_capture.py` and
  154. `test_recorder.py` resize screenshots with `--size` before an agent sees them:
  155. | `--size` | iPhone 17 Pro | Tokens per screenshot |
  156. |---|---|---|
  157. | `full` | 1206×2622 | ~1,500 (up to ~4,000 on models that accept larger images) |
  158. | `half` (default) | 603×1311 | ~1,050 |
  159. | `quarter` | 301×655 | ~260 |
  160. | `thumb` | 120×262 | ~40 |
  161. Token counts are for Claude (width × height ÷ 750, after it shrinks images over about 1.15 MP).
  162. Most providers already shrink or cap large images on their side, so halving a screenshot saves
  163. less than the 75% the pixel count suggests: about 30% here. `quarter` and `thumb` are where the
  164. real savings are, if the agent can still read what it needs at that size.
  165. ### All 31 Scripts
  166. Every script supports `--help` and `--json`. See **SKILL.md** for the complete reference.
  167. #### Build & Development
  168. | Script | What it does | Key flags |
  169. |--------|-------------|-----------|
  170. | `build_and_test.py` | Build Xcode projects, run tests, parse xcresult bundles | `--project`, `--scheme`, `--test`, `--run`, `--no-parallel`, `--get-errors`, `--get-warnings` |
  171. | `log_monitor.py` | Real-time log monitoring with severity filtering | `--app`, `--severity`, `--follow`, `--duration` |
  172. Duo controls require an explicit booted iPhone Duo UDID. Use
  173. `python3 scripts/duo.py --udid <UDID> --pose open`, then read `--state --json` for the active
  174. `display_id`. Pass it with `--display` to `app_state_capture.py` or `test_recorder.py`
  175. (file or inline mode). The bundled private helper compiles with Xcode on first use and verifies
  176. observed state; inner-display coordinate touches remain unverified. See
  177. [backend contracts and live verification](references/duo.md).
  178. #### Device State
  179. | Script | What it does | Key flags |
  180. |--------|-------------|-----------|
  181. | `duo.py` | Duo hinge, orientation and active display readback | `--udid`, `--state`, `--pose`, `--angle`, `--orientation`, `--json` |
  182. | `appearance.py` | Switch dark mode, dynamic type, increase contrast, locale, region | `--theme`, `--text-size`, `--contrast`, `--locale`, `--region`, `--reset` |
  183. | `location.py` | Simulate GPS coordinates and run built-in scenarios | `--lat`, `--lng`, `--city`, `--gpx`, `--list-scenarios`, `--clear` |
  184. | `media.py` | Seed or empty the photo library (`--clear` needs idb 1.7+ and `--yes`) | `--add`, `--clear`, `--yes` |
  185. #### Navigation & Interaction
  186. | Script | What it does | Key flags |
  187. |--------|-------------|-----------|
  188. | `screen_mapper.py` | Analyze current screen, list interactive elements | `--verbose`, `--hints`, `--deep` |
  189. | `navigator.py` | Find and interact with elements semantically | `--find-text`, `--find-type`, `--find-id`, `--tap`, `--expect`, `--enter-text`, `--set-value` |
  190. | `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` |
  191. | `keyboard.py` | Text input, keys, key chords, key sequences and hardware buttons | `--type`, `--key` (+ `--shift/--control/--option/--command`), `--key-sequence`, `--button`, `--clear`, `--dismiss` |
  192. | `app_launcher.py` | Launch, terminate, install, deep link apps | `--launch`, `--terminate`, `--install`, `--open-url`, `--list` |
  193. #### Testing & Analysis
  194. | Script | What it does | Key flags |
  195. |--------|-------------|-----------|
  196. | `accessibility_audit.py` | WCAG compliance checking on current screen | `--verbose`, `--output` |
  197. | `visual_diff.py` | Compare two screenshots for visual changes | `--threshold`, `--output`, `--details` |
  198. | `test_recorder.py` | Automated test documentation with screenshots | `--test-name`, `--output` |
  199. | `app_state_capture.py` | Debugging snapshots (screenshot, hierarchy, logs) | `--app-bundle-id`, `--output`, `--log-lines` |
  200. | `sim_health_check.sh` | Verify environment (Xcode, simctl, IDB, Python) | — |
  201. | `model_inspector.py` | Inspect Core Data / SwiftData models from project files | `--project-path`, `--raw`, `--show-versions` |
  202. | `container.py` | Inspect app sandbox: list, cat, UserDefaults, Core Data, export | `--ls`, `--cat`, `--userdefaults`, `--core-data-path`, `--export` |
  203. | `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`) |
  204. | `localization_audit.py` | Audit `.xcstrings` catalogs for missing keys, unused keys, placeholder mismatches | `--catalog`, `--source`, `--strict` |
  205. #### Permissions & Environment
  206. | Script | What it does | Key flags |
  207. |--------|-------------|-----------|
  208. | `clipboard.py` | Copy text to simulator clipboard for paste testing | `--copy`, `--test-name` |
  209. | `status_bar.py` | Override status bar (time, battery, network) | `--preset`, `--time`, `--battery-level`, `--clear` |
  210. | `push_notification.py` | Send, list and clear simulated push notifications | `--bundle-id`, `--title`, `--body`, `--payload`, `--list`, `--clear` |
  211. | `privacy_manager.py` | Grant, revoke, reset app permissions (15 services) | `--bundle-id`, `--grant`, `--revoke`, `--reset` |
  212. #### Device Lifecycle
  213. | Script | What it does | Key flags |
  214. |--------|-------------|-----------|
  215. | `simctl_boot.py` | Boot simulators with readiness verification | `--name`, `--wait-ready`, `--timeout`, `--all`, `--type` |
  216. | `simctl_shutdown.py` | Gracefully shutdown simulators | `--name`, `--verify`, `--all`, `--type` |
  217. | `simctl_create.py` | Create simulators by device type and OS version | `--device`, `--runtime`, `--list-devices` |
  218. | `simctl_delete.py` | Delete simulators (needs `--yes`) | `--name`, `--yes`, `--all`, `--old` |
  219. | `simctl_erase.py` | Factory reset without deletion (needs `--yes`) | `--name`, `--yes`, `--verify`, `--all`, `--booted` |
  220. ## Configuration
  221. 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.
  222. There's a universal tradeoff to keep in mind:
  223. - **Higher caps / longer timeouts** → fewer false failures, more complete diagnostics, **more tokens** consumed by AI agents and slower failures when something is genuinely broken.
  224. - **Lower caps / shorter timeouts** → faster feedback, tighter token usage, **risk** of silently dropped errors or premature timeouts on legitimately slow operations.
  225. ### Boot & lifecycle timeouts
  226. How long to wait on `xcrun simctl` operations.
  227. | Variable | Default | Tradeoff |
  228. |---|---|---|
  229. | `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). |
  230. | `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. |
  231. | `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. |
  232. | `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. |
  233. | `IOS_SIM_STATE_SUBPROCESS_TIMEOUT` | `15` (s) | Per-subprocess timeout in `app_state_capture.py`. Bump for apps with very large accessibility trees. |
  234. ### Build & test output caps
  235. `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.
  236. | Variable | Default | Tradeoff |
  237. |---|---|---|
  238. | `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. |
  239. | `IOS_SIM_BUILD_VERBOSE_CAP` | `100` | Errors / warnings in `--verbose` mode. Mostly relevant for monorepos or first builds with many fixable warnings. |
  240. | `IOS_SIM_BUILD_JSON_CAP` | `50` | Max errors / failed tests in `--json` output. Raise for CI dashboards that need exhaustive lists. |
  241. | `IOS_SIM_BUILD_LOG_PREVIEW` | `4000` (chars) | Chars of build log included in default output. Higher → more context for failures, more tokens. |
  242. | `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. |
  243. | `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. |
  244. | `IOS_SIM_INTROSPECT_TIMEOUT` | `60` (s) | Timeout for `xcodebuild -list` and `xcrun simctl list` introspection calls. These should normally complete in &lt;1s; 60s catches Xcode-toolchain hangs without disrupting cold-start. |
  245. ### Log monitor output
  246. `log_monitor.py` aggregates `os_log` output; these caps shape both the text summary and the structured JSON.
  247. | Variable | Default | Tradeoff |
  248. |---|---|---|
  249. | `IOS_SIM_LOG_TEXT_SUMMARY` | `15` | Errors / warnings shown in the text summary. The default surfaces enough for most debugging without flooding terminal output. |
  250. | `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. |
  251. | `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. |
  252. | `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. |
  253. | `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. |
  254. | `IOS_SIM_HANG_MIN_MS` | `250` | HangBuster threshold: events below this duration never reach disk. |
  255. | `IOS_SIM_HANG_SESSION_TTL_HOURS` | `24` | HangBuster session prune age. Pruning runs on every `--start`. |
  256. | `IOS_SIM_HANG_DEFAULT_TOP_N` | `3` | Default top-N clusters in `--stop` L1 output. |
  257. | `IOS_SIM_HANG_BUDGET_TOKENS` | _(unset)_ | Default token budget for `--stop` (picks L0/L1/L2 to fit). |
  258. | `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. |
  259. | `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. |
  260. ### UI navigation & screen mapping
  261. These shape what AI agents see when exploring a screen. They're the biggest direct lever on token consumption per navigation step.
  262. | Variable | Default | Tradeoff |
  263. |---|---|---|
  264. | `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. |
  265. | `IOS_SIM_SCREEN_BUTTONS_PREVIEW` | `15` | Button names in `screen_mapper.py` summary. |
  266. | `IOS_SIM_SCREEN_SECTION_ITEMS` | `10` | Items per section in `screen_mapper.py` summary. |
  267. | `IOS_SIM_APPS_PREVIEW` | `30` | Installed apps listed by `app_launcher.py` before truncation. |
  268. | `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. |
  269. | `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. |
  270. ### Accessibility audit
  271. | Variable | Default | Tradeoff |
  272. |---|---|---|
  273. | `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. |
  274. | `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. |
  275. ### Progressive disclosure cache
  276. `ProgressiveCache` stores large outputs (build results, log dumps) keyed by short IDs so the default output stays minimal.
  277. | Variable | Default | Tradeoff |
  278. |---|---|---|
  279. | `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. |
  280. | `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. |
  281. ### Examples
  282. ```bash
  283. # Slow GitHub Actions macOS runner — give boot up to 10 minutes
  284. IOS_SIM_BOOT_TIMEOUT=600 python scripts/simctl_boot.py --wait-ready
  285. # Monorepo with hundreds of warnings — see them all in verbose mode
  286. IOS_SIM_BUILD_VERBOSE_CAP=500 python scripts/build_and_test.py --verbose
  287. # Complex Settings-style screen — return more tappable elements
  288. IOS_SIM_MAX_ELEMENTS=100 python scripts/navigator.py --list
  289. # Snappy app — cut tap-settle delay in half for faster E2E runs
  290. IOS_SIM_TAP_SETTLE_MS=250 python scripts/navigator.py --find-text "Login" --tap
  291. # Long CI pipeline — keep cache entries valid for the whole job
  292. IOS_SIM_CACHE_TTL_HOURS=8 python scripts/build_and_test.py --project MyApp.xcodeproj
  293. ```
  294. You can also export the vars once for the whole session:
  295. ```bash
  296. export IOS_SIM_BOOT_TIMEOUT=600
  297. export IOS_SIM_LOG_TAIL=500
  298. export IOS_SIM_MAX_ELEMENTS=50
  299. # … all subsequent scripts honor them
  300. ```
  301. Parse errors fall back to the documented default with a warning on stderr — no scripts will crash on a malformed env var.
  302. ## Evaluation
  303. Tested using [Claude Code evals](https://docs.claude.com/en/docs/claude-code/evals):
  304. | Condition | Pass Rate |
  305. |-----------|-----------|
  306. | With skill | **100%** (3/3) |
  307. | Without skill | **46%** (~1.4/3) |
  308. ```bash
  309. claude evals run evals/evals.json --skill ios-simulator-skill
  310. ```
  311. ## License
  312. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.