Teaching agents to tap buttons by meaning, not coordinates

What it does

A bundle of 27 Python/shell scripts that give Claude Code (or any agent willing to shell out) a tight, token-frugal interface to iOS development: building and testing Xcode projects, driving the simulator, and inspecting app state. It wraps xcodebuild, xcrun simctl, and idb rather than replacing them — competent glue, but glue with real engineering underneath.

The interesting bit

The core idea is progressive disclosure: a build returns one summary line plus an xcresult ID, and the agent only pulls full errors, warnings, or logs when it actually needs them. Navigation goes through the accessibility tree instead of pixel coordinates — finding “Login” by label survives a UI change and costs ~10 tokens instead of the 1,600–6,300 a screenshot burns.

Key highlights

• Build output compressed to a single line by default; details fetched on demand via xcresult ID
• Semantic UI navigation via accessibility APIs (navigator.py, screen_mapper.py)
• Deep debugging tooling: hang_watcher.py (HangBuster) for os_log hang events, container.py for app sandbox inspection, localization_audit.py for .xcstrings catalogs
• Full simulator lifecycle: boot with readiness verification, create, erase, delete — with safety confirmations
• Every limit (timeouts, output caps, polling) tunable via IOS_SIM_* env vars, with documented tradeoffs

Caveats

• macOS-only by nature, and IDB is optional — interactive features need it installed separately
• Defaults are tuned for local Apple Silicon; the README itself warns you’ll need to raise timeouts on slow CI runners (GitHub-hosted macOS can need 4–6 min just to boot)
• The token-savings numbers are the author’s own measurements, not independently verified

Verdict

If you’re letting an agent anywhere near an iOS codebase, this is exactly the kind of intermediary layer you want — it’s essentially an economy measure for context windows. Android and web devs can walk on by.