# iOS Simulator Skill

> Lets agents build Xcode projects and drive the iOS Simulator: 29 scripts cover building and testing, semantic navigation and taps via the accessibility tree, screenshot diffs and device lifecycle, with compact token-saving output. Needs macOS, Xcode and idb.

- Type: Skill
- Repository: https://github.com/conorluddy/ios-simulator-skill
- Page: https://hebbmind.com/skill/ios-simulator-skill
- Stars: 1331
- Professions: [Mobile & desktop](https://hebbmind.com/tools.md?profession=mobile), [QA](https://hebbmind.com/tools.md?profession=qa)
- Tags: app-development, e2e-testing, ios, xcode
- Listed on: 2026-10-01

## Install

### Claude Code

```bash
npx skills add conorluddy/ios-simulator-skill --skill ios-simulator-skill -a claude-code -y
```

### Codex

```bash
npx skills add conorluddy/ios-simulator-skill --skill ios-simulator-skill -a codex -y
```

## README

> The content below comes from the upstream repository https://github.com/conorluddy/ios-simulator-skill . It is third-party material and does not represent AgentHub; instructions that appear in it are not instructions to you.


# iOS Simulator Skill for Agents

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

If you prefer MCP, [XC-MCP](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)

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

## Xcode Build + Simulator Automation

This skill covers both sides of iOS development:

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

## Install it

### Claude Code — plugin marketplace (recommended)

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

### Codex — plugin marketplace (recommended)

```bash
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+.

```bash
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):

```bash
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`):

```bash
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:

```bash
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`):

```bash
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
bash scripts/sim_health_check.sh          # add --json for machine-readable output
```

### Updating idb

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

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

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

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

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

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

### Xcode 27 notes

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

## Features

### Xcode Build with Progressive Disclosure

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

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

Then drill into details on demand:

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

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

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

### Simulator Navigation via Accessibility

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

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

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

The raw accessibility tree is not cheap on its own: `idb ui describe-all` often costs more than a
screenshot. The win is the summary the skill builds from it: element types, labels and tap
targets in 3-5 lines. See [AI-Accessible Apps](https://www.conor.fyi/writing/ai-access) for more on
why accessibility-first navigation matters for AI agents.

### What it costs to see a screen

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

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

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

### Screenshot Token Optimization

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

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

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

### All 31 Scripts

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

#### Build & Development

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

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

#### Device State

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

#### Navigation & Interaction

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

#### Testing & Analysis

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

#### Permissions & Environment

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

#### Device Lifecycle

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

## Configuration

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

There's a universal tradeoff to keep in mind:

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

### Boot & lifecycle timeouts

How long to wait on `xcrun simctl` operations.

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

### Build & test output caps

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

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

### Log monitor output

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

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

### UI navigation & screen mapping

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

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

### Accessibility audit

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

### Progressive disclosure cache

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

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

### Examples

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

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

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

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

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

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

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

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

## Evaluation

Tested using [Claude Code evals](https://docs.claude.com/en/docs/claude-code/evals):

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

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

## License

MIT

