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

- Skill name: `interceptor-ios`
- Category: [Apps & Automation](https://www.openparable.com/skill/apps-automation/1)
- Source: https://github.com/Hacker-Valley-Media/Interceptor/blob/HEAD/.agents/skills/interceptor-ios/SKILL.md
- Repository: Hacker-Valley-Media/Interceptor (307 GitHub stars when collected)

## SKILL.md

# 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

```bash
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`](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`](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.

---

Source: https://www.openparable.com/skill/apps-automation/interceptor-ios (OpenParable). Cite the canonical URL above.
