interceptor-ios

name	interceptor-ios
description	Drive any installed app on an owned, unlocked, Developer-Mode iPhone via interceptor ios *: ref-tagged element trees, deterministic coordinate taps (click), reliable text entry (type/keys), scroll, drag, hardware buttons (press), screenshots, installed-app listing, and app launch/activate/terminate. The phone runs an on-device XCUITest runner (InterceptorRunner) that dials into the daemon over WiFi — no cable once paired, no WebDriverAgent. Address a phone with --on <name> or ios:<udid>; phones auto-connect on the first verb. Use for iPhone app automation. Not for the iOS Simulator UI of a Mac app, and not for content inside a browser tab (use interceptor-browser) or a macOS app (use interceptor-macos).
metadata	{"short-description":"Drive apps on a real iPhone via the interceptor CLI; device dials in over WiFi"}

Interceptor iOS

Agent-operator skill for the iOS surface of Interceptor. Use the interceptor ios * CLI to drive any installed app on an owned, unlocked, Developer-Mode iPhone: ref-tagged accessibility trees, deterministic coordinate taps, reliable text entry, scroll/drag, hardware buttons, screenshots, and app lifecycle.

The phone runs Interceptor's own on-device XCUITest runner (InterceptorRunner — not WebDriverAgent). The runner dials into the daemon over a WebSocket, exactly like the browser extension; the daemon drives it from there. Once the phone is paired over WiFi, no cable is needed. For content inside a browser tab load interceptor-browser; for a macOS app load interceptor-macos.

This installed skill is self-contained. Source checkouts also have AGENTS.md, but packaged users may only have the skill directory below /Library/Application Support/Interceptor/skills.

Fast Path

interceptor ios devices                        # 1. Phones with the agent installed (+ aliases)
interceptor ios status                          # 2. Per-phone connection state
interceptor ios tree --on phone                 # 3. Auto-connects, returns the ref-tagged element tree
interceptor ios find --label "Slack" --on phone # 4. Locate an element by label/role
interceptor ios click e29 --on phone            # 5. Deterministic coordinate tap at the ref's frame center
interceptor ios type e243 "hello" --on phone    # 6. Focus the field, then type
interceptor ios screenshot --on phone           # 7. Capture the screen (VLM-budget resized)

Omit --on <name> when only one phone is set up — it's used by default. Set an alias once with interceptor ios name <udid> phone, then always use --on phone.

Treat eN refs as short-lived. The UI changes between calls; re-read with interceptor ios tree before acting. Refs carry frames and resolve to coordinates, so a tap is deterministic even if the underlying element handle went stale.

The Model

• The device dials in. A verb on a not-yet-connected phone auto-launches the runner; it connects back over WiFi and the verb runs. There is no manual "enable" step.
• Unlocked + foreground matters. A locked phone refuses app launches. If launches stall, the phone is likely locked — unlock it. The runner drops on idle and re-dials per verb, so between calls the phone may return to the Home screen; chain a launch and its follow-up verbs closely.
• UI only. Interceptor drives the touchscreen and buttons. It cannot pass Face ID / passcode / Apple Pay or unlock the phone.
• Setup is one-time. interceptor ios setup (Xcode signed in) or interceptor ios login (no-Xcode, the user's own Apple ID) installs + signs the runner. A background timer renews the runner signature before the free-tier certificate expires.

Workflows

Workflow	When to invoke
workflows/drive-iphone-app.md	Open an app and complete a task on a real iPhone: launch → tree → find → click/type → verify

References

File	Topic
references/command-catalog.md	Full interceptor ios command surface — setup, drive verbs, flags, addressing

When To Switch Surfaces

• Target is content inside a browser tab (DOM, network, SPA state) → load interceptor-browser.
• Target is a native macOS app (or the browser chrome / OS dialogs on the Mac) → load interceptor-macos.
• Target is an app on the physical iPhone → this skill.

Do Not Default To Troubleshooting

• User wants an iPhone task completed → run interceptor ios * commands.
• User wants Interceptor's iOS support fixed, installed, or explained → that's a separate task; ask before diving into repo state.
• Inside the Interceptor repo, use this skill for live device validation, not as the primary source of repo-development instructions.