Interceptor IOS
Apps & Automationinterceptor-iosInterceptor IOS is an Agent Skill for apps & automation published in the Hacker-Valley-Media/Interceptor repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
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).
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/Hacker-Valley-Media/Interceptor/blob/HEAD/.agents/skills/interceptor-ios/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/interceptor-ios, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
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) orinterceptor 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.