OpenParable
Skip to content
← Back to skills

Interceptor IOS

Apps & Automation
interceptor-ios

Interceptor 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).

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
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) 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

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

References

FileTopic
references/command-catalog.mdFull 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.