Skip to content
Back to search

Interceptor

Browser automation and computer use for AI agents. One CLI and MCP server for your signed-in browser, native macOS apps, and real iPhones.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/Hacker-Valley-Media/Interceptor with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/Hacker-Valley-Media/Interceptor'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/hacker-valley-media--interceptor/badge.svg)](/listings/hacker-valley-media--interceptor)

HTML

<a href="/listings/hacker-valley-media--interceptor"><img src="/api/listings/hacker-valley-media--interceptor/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

1. Install the Browser or Full `.pkg` from Releases. 2. In Chrome or Brave, install the [Interceptor extension](https://chromewebstore.google.com/detail/interceptor/gomcpnagjjlhehnkoobkjgnkbleiooed). The local runtime and browser extension are both required. 3. For Safari, also install the Safari `.pkg`, open `/Applications/InterceptorSafari.app` once, then enable Interceptor and website access in **Safari → Settings → Extensions**. Safari requires your approval. 4. With Full, grant the permissions needed by your task to `interceptor-bridge`. Run `interceptor macos trust --walkthrough` for guidance. Accessibility enables native UI control; screen, microphone, and app-automation access are needed for their respective features.

For an unpacked Chrome/Brave extension, enable Developer Mode on the browser's extensions page and load `/Library/Application Support/Interceptor/extension/`. Keep one copy per profile. Store and unpacked installations share an extension ID; store updates arrive after store review.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 418 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <p align="center">
  2. <img src="docs/assets/interceptor-logo-square.png" alt="Interceptor logo" width="140">
  3. </p>
  4. <h1 align="center">Interceptor</h1>
  5. <p align="center">
  6. <strong>Give your agent your browser, Mac, and iPhone.</strong>
  7. </p>
  8. <p align="center">
  9. Browser automation, computer use, and iPhone automation for AI agents.
  10. </p>
  11. <p align="center">
  12. Works with Claude Code, Codex, Cursor, Gemini CLI, Claude Desktop, OpenClaw, OpenCode, and any agent that can run a shell command.
  13. </p>
  14. <p align="center">
  15. <a href="#get-started"><strong>Get started</strong></a> ·
  16. <a href="#how-it-compares">How it compares</a> ·
  17. <a href="#browser-automation">Browser</a> ·
  18. <a href="#macos-automation">macOS</a> ·
  19. <a href="#windows">Windows</a> ·
  20. <a href="#linux">Linux</a> ·
  21. <a href="#iphone-and-ios-automation">iPhone</a> ·
  22. <a href="#record-and-reuse-workflows">Record &amp; replay</a> ·
  23. <a href="#documentation">Docs</a> ·
  24. <a href="https://github.com/Hacker-Valley-Media/Interceptor/discussions">Discussions</a>
  25. </p>
  26. <p align="center">
  27. <a href="https://github.com/Hacker-Valley-Media/Interceptor/releases/latest"><img src="https://img.shields.io/github/v/release/Hacker-Valley-Media/Interceptor?label=release" alt="Latest release"></a>
  28. <a href="https://chromewebstore.google.com/detail/interceptor/gomcpnagjjlhehnkoobkjgnkbleiooed"><img src="https://img.shields.io/badge/Chrome%20Web%20Store-Add%20to%20Chrome-4285F4?logo=googlechrome&logoColor=white" alt="Chrome Web Store"></a>
  29. <a href="https://github.com/Hacker-Valley-Media/Interceptor/releases"><img src="https://img.shields.io/github/downloads/Hacker-Valley-Media/Interceptor/total?label=downloads" alt="Total downloads"></a>
  30. <a href="https://github.com/Hacker-Valley-Media/Interceptor"><img src="https://img.shields.io/github/stars/Hacker-Valley-Media/Interceptor?style=flat&label=stars" alt="GitHub stars"></a>
  31. <a href="LICENSE"><img src="https://img.shields.io/badge/license-Elastic%202.0-blue" alt="Elastic License 2.0"></a>
  32. </p>
  33. Interceptor reads GitHub stats, fills a Numbers sheet, and builds an on-screen overlay.
  34. https://github.com/user-attachments/assets/b8af57d1-8a22-4955-8b2b-f43f09d52286
  35. *30-second edited demo. The terminal is staged from real Interceptor output.*
  36. Interceptor connects an AI agent or script to your signed-in browser, native apps on macOS, Windows, and Linux, and a physical iPhone. It combines structured UI reads and actions with access to page traffic, rich editors, app internals, and device state. The agent can inspect what happened after an action and use that evidence for its next step.
  37. | Work you can build with Interceptor | Tools available |
  38. |---|---|
  39. | Research in your existing browser session | Page text, tables, links, browser search, multiple contexts, and a source-ledger research workflow. |
  40. | Edit a document, slide, or design and save the result | Rich-editor scenes, canvas input, file uploads, and direct capture of page-produced export bytes. |
  41. | Complete a native desktop task while you keep working | Accessibility controls, background input, and capture of covered windows on macOS, Windows, and Linux; Apple Events on the Mac. |
  42. | Operate an app on a real iPhone and inspect its state | Element trees, taps, text entry, screenshots, process telemetry, and WebKit inspection. |
  43. | Turn a demonstrated workflow into reusable commands | Browser and Mac recording, event timelines, and replay-plan export. |
  44. Use it from any agent that can run shell commands, or through its built-in [Model Context Protocol (MCP) server](docs/mcp.md). Interceptor does not require a model API key; your chosen agent or model may have its own subscription or API costs.
  45. ## What Interceptor adds
  46. Many tools now let an agent use your signed-in Chrome, and several work on a Mac in the background. Interceptor does both, and adds what the tools in [How it compares](#how-it-compares) don't:
  47. - **Safari and Chromium in one CLI.** Chrome, Brave, Edge, and Safari pages, with the same commands, in the profiles you already use.
  48. - **Your own iPhone.** Drive the apps on a physical iPhone, not a simulator, over USB, Wi-Fi, or Tailscale away from home, including on cellular.
  49. - **Page traffic without a debugger.** Read fetch, XHR, SSE, WebSocket, Beacon, and BroadcastChannel traffic through standard page APIs. The browser shows no debugging banner and needs no remote-debugging switch.
  50. - **Real editors, not screenshots.** Read and change Google Docs, Slides, Sheets, and Canva through their scene graphs, and save the files they export.
  51. - **Admin work without showing the password.** Vault secrets go by name into a web login, `sudo`, the macOS administrator prompt, or the iPhone passcode. The model never sees the value.
  52. - **One tool across browser, Mac, Windows, Linux, and iPhone,** with any agent and any model. Work runs in the background so you keep using your computer. [Behavior and exceptions](.agents/skills/interceptor-macos/references/background-first.md).
  53. ## Get started
  54. ### Install with one command
  55. macOS (Apple silicon) and Linux:
  56. ```bash
  57. curl -fsSL https://raw.githubusercontent.com/Hacker-Valley-Media/Interceptor/main/scripts/get-interceptor.sh | bash
  58. ```
  59. Windows (PowerShell):
  60. ```powershell
  61. irm https://raw.githubusercontent.com/Hacker-Valley-Media/Interceptor/main/scripts/get-interceptor.ps1 | iex
  62. ```
  63. It asks two questions. Press Enter for both to get everything:
  64. 1. **Full or Browser only?** Full (the default) is your browser plus desktop apps, and the iPhone on a Mac. Browser only is web pages.
  65. 2. **Register the MCP server?** Yes is the default. It lists the AI apps it found that don't have the server yet (Claude Code, Codex, Cursor, Gemini CLI, Claude Desktop) and turns every tool on.
  66. It downloads the latest release from `updates.hackervalley.media`, checks its SHA-256 and the Hacker Valley Media signature, and installs it with no Installer wizard. Nothing installs if a check fails. It adds Interceptor's skills to every AI agent on your computer. A Mac asks for your password once. Run it again any time to update: it keeps your edition and leaves an existing MCP setup alone.
  67. Options go after `bash -s --`, for example `curl -fsSL … | bash -s -- --browser --no-mcp`:
  68. | Option | Does |
  69. |---|---|
  70. | `--full`, `--browser` | Pick the edition instead of being asked. Full is the default. |
  71. | `--mcp`, `--no-mcp` | Register the MCP server in every AI app it finds, or skip it, instead of being asked (`--mcp=claude,codex` for some). |
  72. | `--safari` | macOS: also install the Safari extension package. |
  73. | `--no-skills` | Skip adding the skills. |
  74. On Windows, pass the same as parameters: `& ([scriptblock]::Create((irm <url>))) -Browser -NoMcp`.
  75. "Every tool on" means the agent can also run the actions that are off by default, such as quitting apps, writing files, and running scripts in a page (`INTERCEPTOR_MCP_ALLOW=all,raw`). The agent still marks each of those calls as confirmed. For reading and clicking only, run `interceptor mcp install` afterward.
  76. The last step is the browser extension. On a Mac, the Interceptor window opens by itself and walks you through it. On Windows, the Chrome Web Store page opens.
  77. Want your AI agent to do it? Ask it to run the same command. With no terminal to answer, it takes the defaults: Full and the MCP server with every tool on. A Mac then opens the verified package in Installer for you to type your password.
  78. **Prefer to run each step yourself?** On a Mac, the same install with Apple's own tools:
  79. ```bash
  80. curl -fLo /tmp/Interceptor.pkg https://updates.hackervalley.media/latest/Interceptor-Full.pkg
  81. spctl -a -vv -t install /tmp/Interceptor.pkg && sudo installer -pkg /tmp/Interceptor.pkg -target /
  82. interceptor skills adopt
  83. ```
  84. `spctl` is Apple's Gatekeeper check. It prints `Notarized Developer ID` and `HACKER VALLEY MEDIA, LLC (TPWBZD35WW)`, and if the package is not signed and notarized, `installer` never runs. For the Browser edition, use `Interceptor-Browser.pkg`. Add `interceptor mcp install --allow all,raw` to register the MCP server with every tool on.
  85. ### Download an installer
  86. Each link below always gets the newest release. Start with Browser for web tasks, or Full for native apps and the iPhone. Every version is on [Releases](https://github.com/Hacker-Valley-Media/Interceptor/releases), and [SHA256SUMS-ALL](https://github.com/Hacker-Valley-Media/Interceptor/releases/latest/download/SHA256SUMS-ALL) lists each file's SHA-256. The macOS packages are built for Apple silicon. On an Intel Mac, build from source (see [Development and contributions](#development-and-contributions)).
  87. | Package | Download | What it enables |
  88. |---|---|---|
  89. | macOS Browser | [Interceptor-Browser.pkg](https://updates.hackervalley.media/latest/Interceptor-Browser.pkg) | CLI, daemon, and browser extension files. |
  90. | macOS Full | [Interceptor-Full.pkg](https://updates.hackervalley.media/latest/Interceptor-Full.pkg) | Browser package plus the native Mac bridge and iPhone tooling. The bridge requires macOS 15+. |
  91. | macOS Safari add-on | [Interceptor-Safari.pkg](https://updates.hackervalley.media/latest/Interceptor-Safari.pkg) | Safari extension, installed after either core package. |
  92. | Windows Browser | [x64](https://updates.hackervalley.media/latest/Interceptor-Browser-windows-x64.exe) · [ARM64](https://updates.hackervalley.media/latest/Interceptor-Browser-windows-arm64.exe) | Browser automation on Windows 10 22H2+ or Windows 11 (x64); Windows 11 24H2+ (ARM64). [Windows guide](docs/windows-install.md). |
  93. | Windows Full | [x64](https://updates.hackervalley.media/latest/Interceptor-Full-windows-x64.exe) · [ARM64](https://updates.hackervalley.media/latest/Interceptor-Full-windows-arm64.exe) | Browser automation plus [native app control](#windows) with `interceptor desktop`. Windows 10 22H2 x64 or Windows 11 24H2+ (x64/ARM64). |
  94. | Linux Browser | [x64](https://updates.hackervalley.media/latest/Interceptor-Browser-linux-x64.tar.gz) · [ARM64](https://updates.hackervalley.media/latest/Interceptor-Browser-linux-arm64.tar.gz) | Browser automation and install scripts. |
  95. | Linux Full | [x64](https://updates.hackervalley.media/latest/Interceptor-Full-linux-x64.tar.gz) · [ARM64](https://updates.hackervalley.media/latest/Interceptor-Full-linux-arm64.tar.gz) | Browser automation plus [native app control](#linux) with `interceptor desktop`. |
  96. The macOS release binaries target Apple silicon. On Windows and Linux, the Full packages add native app control through `interceptor desktop`; run `interceptor desktop capabilities` to see what works on that computer. iPhone setup requires a Mac.
  97. ### macOS installation
  98. 1. Install the [Browser](https://updates.hackervalley.media/latest/Interceptor-Browser.pkg) or [Full](https://updates.hackervalley.media/latest/Interceptor-Full.pkg) `.pkg`. On a first install, the Interceptor window opens: it checks whether the extension is already in your browser, and if not, walks you through adding it from the Chrome Web Store, as an unpacked extension (with a step-by-step guide in the browser), or for Safari. Open it again any time with `interceptor diagnose extension --welcome`.
  99. 2. In Chrome or Brave, install the [Interceptor extension](https://chromewebstore.google.com/detail/interceptor/gomcpnagjjlhehnkoobkjgnkbleiooed) if the window did not already do it. The local runtime and browser extension are both required.
  100. 3. For Safari, also install the [Safari `.pkg`](https://updates.hackervalley.media/latest/Interceptor-Safari.pkg), open `/Applications/InterceptorSafari.app` once, then enable Interceptor and website access in **Safari → Settings → Extensions**. Safari requires your approval.
  101. 4. With Full, grant the permissions needed by your task to `interceptor-bridge`. Run `interceptor macos trust --walkthrough` for guidance. Accessibility enables native UI control; screen, microphone, and app-automation access are needed for their respective features.
  102. For an unpacked Chrome/Brave extension, enable Developer Mode on the browser's extensions page and load `/Library/Application Support/Interceptor/extension/`. Keep one copy per profile. Store and unpacked installations share an extension ID; store updates arrive after store review.
  103. ### Windows and Linux
  104. On **Windows**, run the [installer](#download-an-installer) for your PC (x64 or ARM64), install the browser extension, then open a new terminal. Chrome, Brave, and Edge can use the Chrome Web Store listing; Edge requires allowing extensions from other stores. The [Windows guide](docs/windows-install.md) also covers unpacked extensions, silent installation, updates, and removal.
  105. On **Linux**, extract the [archive](#download-an-installer) for your machine (x64 or ARM64) and run this from its directory:
  106. ```bash
  107. bash scripts/install.sh --browser-only --brave
  108. # For Chrome, use --chrome instead of --brave.
  109. ./dist/interceptor open "https://example.com"
  110. ```
  111. Follow the installer's extension-loading instructions. The archive includes compiled binaries, so a separate Bun installation is not needed for this release path.
  112. For native app control on Linux, the [one-command install](#install-with-one-command) checks the signed checksum list for you. To do it by hand, download the Full archive with [SHA256SUMS](https://github.com/Hacker-Valley-Media/Interceptor/releases/latest/download/SHA256SUMS), [SHA256SUMS.cms](https://github.com/Hacker-Valley-Media/Interceptor/releases/latest/download/SHA256SUMS.cms), [verify-release-manifest.sh](https://github.com/Hacker-Valley-Media/Interceptor/releases/latest/download/verify-release-manifest.sh) and [linux-release-apple-root.pem](https://github.com/Hacker-Valley-Media/Interceptor/releases/latest/download/linux-release-apple-root.pem), run `bash verify-release-manifest.sh <folder>` (it checks every archive the list names, so put all four Linux archives in the folder), then run `bash scripts/install.sh --full` from your graphical session. On Windows, run the Full installer instead of the Browser one. The [desktop guide](docs/desktop-bridge.md) lists what each OS supports and the optional Linux packages that light up OCR, face detection, and personal data.
  113. ### Your first browser task
  114. With the extension enabled and browser open:
  115. ```bash
  116. interceptor open "https://example.com" --group first-task
  117. interceptor read --group first-task
  118. interceptor group close first-task
  119. ```
  120. `open` starts the daemon when needed, opens a managed tab in the background, and returns the page's tree and text. You should see **Example Domain**. `read` inspects it again; `group close` cleans up that task's tabs.
  121. If several browser contexts are connected, run `interceptor contexts` and add `--context <id>` to your browser commands. Safari's ID is `safari`. `interceptor status` reports local health but does not start the daemon by itself.
  122. ### Connect your agent
  123. For a shell-capable agent, adopt the bundled skills into detected agent runtimes. The Mac and Windows installers and the Linux archives each bundle the skills for their operating system:
  124. ```bash
  125. interceptor skills adopt
  126. ```
  127. For an MCP client, register Interceptor and restart the client. The installer detects Claude Code, Codex, Gemini CLI, Cursor, and Claude Desktop:
  128. ```bash
  129. interceptor mcp install
  130. interceptor mcp status
  131. ```
  132. The MCP server exposes browser, macOS, iOS, read, local, and raw tools, plus discovery resources. Its permissions are configured by the operator. See the [MCP guide](docs/mcp.md).
  133. <a id="browser"></a>
  134. ## Browser automation
  135. **Read and operate the web apps you are already signed into.** Chrome, Brave, and Safari use Interceptor's extension. Browser-specific limits are described in the [browser guide](.agents/skills/interceptor-browser/SKILL.md).
  136. - **Pages and forms:** read text, HTML, tables, links, frames, and accessibility-style element references. Click, type, select, drag, scroll, and navigate. Native dropdown selection validates exact values or unique labels and rejects invalid options.
  137. - **Rich editors and canvases:** inspect supported scene graphs, select objects, navigate slides, and enter text in canvas-rendered editors. Workflows cover Google Docs, Slides, Sheets, Canva, and WebGL viewers; support depends on the app and operation.
  138. - **Network and application state:** inspect fetch/XHR, SSE, WebSocket, Beacon, and BroadcastChannel traffic; examine headers, rewrite matching requests, and export captured traffic. Passive inspection uses standard page APIs without attaching a debugger.
  139. - **Files and exports:** upload local files to inputs, drop zones, and supported file pickers. Save page-produced `Blob`, buffer, or `blob:` URL bytes directly to disk with `save`, including native exports from supported web apps.
  140. - **Capture and browser data:** screenshots, OCR, canvas inspection, cookies, storage, history, bookmarks, downloads, and session management.
  141. - **Multiple tasks:** select a browser profile with `--context`, a tab with `--tab`, and a task's managed tabs with `--group`. Use a distinct group for each concurrent worker.
  142. - **Tab cleanup:** when no command has touched a managed tab group for 10 minutes, Interceptor closes its idle tabs. It keeps the tab you are looking at, audible tabs, tabs with unsaved form input, and a window's last tab, so the group itself can remain. The extension popup changes the idle time and can delete the whole idle group instead (off by default). Administrators can set both through managed browser policy. `interceptor sessions restore <id>` reopens a closed page in the background.
  143. ```bash
  144. interceptor open "https://example.com" --group browser-task
  145. interceptor find "Learn more" --group browser-task
  146. interceptor inspect --group browser-task
  147. interceptor group close browser-task
  148. ```
  149. To interact, use the current reference returned by `read` or `find`: `interceptor act <ref>` clicks it; `interceptor act <ref> "text"` enters text. Re-read after navigation or a stale-reference error, and check the resulting state after an action.
  150. [Browser command reference](.agents/skills/interceptor-browser/references/command-catalog.md) · [Rich-editor workflows](.agents/skills/interceptor-browser/workflows/rich-editor-workflows.md) · [Export capture](.agents/skills/interceptor-browser/references/blob-export-capture.md)
  151. <a id="macos"></a>
  152. ## macOS automation
  153. **Desktop automation for native Mac apps, windows, menus, and dialogs, including supported background workflows.** The Full package provides a Swift bridge with Accessibility, capture, input, and Apple framework integrations.
  154. ```bash
  155. interceptor macos trust
  156. interceptor macos tree --app "Finder"
  157. interceptor macos windows --app "Finder"
  158. ```
  159. These commands inspect Finder without activating it. Use returned element references with `macos act`, `click`, or `type`; use `macos open "Finder" --activate` when you want to bring it forward.
  160. | Area | Capabilities |
  161. |---|---|
  162. | App control | Accessibility trees, text and values, clicks, typing, keyboard input, scrolling, dragging, menus, app lifecycle, and window placement. |
  163. | Capture and perception | Covered/minimized-window screenshots, screen streaming, OCR and vision over a window or a saved image file (including an iPhone screenshot), system/microphone audio, speech recognition, sound classification, and language analysis. |
  164. | Files and system work | Spotlight search, file reads/writes/watchers, clipboard, URL fetching, OS logs, AppleScript/JXA, JavaScriptCore scripts, and Apple Events. |
  165. | Documents | PDF text, forms, annotations, merge/split operations, data detection, translation, and thumbnails. |
  166. | Personal apps | Calendar, reminders, contacts, photos, location, music, maps, sharing, and notifications through the corresponding system frameworks and permissions. |
  167. | Visual tools | HTML and SpriteKit overlays, window-anchored HUDs, capture streams, and virtual displays. |
  168. | Local compute | Apple Intelligence on supported macOS 26+ systems, OCI containers, and Linux/macOS VM lifecycle and guest tools. See the guides for runtime, model, and guest prerequisites. |
  169. [Mac command reference](.agents/skills/interceptor-macos/references/command-catalog.md) · [Background behavior](.agents/skills/interceptor-macos/references/background-first.md) · [System and media tools](.agents/skills/interceptor-macos/references/advanced-domains.md) · [Documents](docs/native/document.md) · [Personal data](docs/native/personal-data.md) · [Overlays](docs/native/overlays.md) · [VMs](.agents/skills/interceptor-macos/workflows/vm-lifecycle.md)
  170. ## Windows and Linux automation
  171. **Drive native apps on Windows and Linux with the same commands as on the Mac.** The Full package adds `interceptor desktop`, which takes the same verbs, flags and JSON replies as `interceptor macos`. Input goes to the target window in the background, without bringing it forward or moving your cursor. Not every operation exists on every system, so check first: `capabilities` says whether each one works on this computer, and why not when it doesn't.
  172. ```bash
  173. interceptor desktop capabilities
  174. interceptor desktop windows --app "Notepad"
  175. interceptor desktop tree --app "Notepad"
  176. ```
  177. | Area | Capabilities |
  178. |---|---|
  179. | App control | Accessibility trees, element search, values and text. Clicks, typing, keys, scrolling, dragging, menus and actions sent to a background window. List, open, resize, and move apps and windows. |
  180. | Capture and perception | Screenshots, screen capture and streaming with recording, OCR, face, hand and body detection, image classification, speech recognition, and sound classification. |
  181. | Local AI | Prompts, translation, entity and sentiment analysis, and data detection with Gemma 4 E2B, downloaded once on first use (2.8 GB) and run on your computer by the bundled llama.cpp server. |
  182. | Files and system work | Files, thumbnails, clipboard, URL fetching, PDF, logs, JavaScript scripts, monitor and replay, and overlays. |
  183. | Personal data | Contacts, calendar, reminders, notifications, and sharing. |
  184. | Secrets and updates | Vault secrets typed by name into apps, plus `sudo` on Linux. Updates ask first, like Sparkle on a Mac: you see the release notes and click **Install Update**. |
  185. ### Windows
  186. Browser-only supports Windows 10 22H2+ and Windows 11 on x64; ARM64 requires Windows 11 24H2+. Full supports Windows 10 22H2 x64 or Windows 11 24H2+ (x64/ARM64); it does not support Windows 11 builds 22000–26099. The Full installer is signed by Hacker Valley Media LLC and installs for your user only, with no administrator prompt. Desktop commands run in your signed-in desktop session; one started over SSH is refused. OCR, face detection and speech recognition use the engines Windows ships. The signed Full install/upgrade/uninstall lifecycle has not yet been tested on Windows 10. [Windows guide](docs/windows-install.md)
  187. ### Linux
  188. Tested on Arch Linux ARM64 with Hyprland on Wayland. Run commands from your own graphical session; a plain SSH shell is refused. OCR, face detection, language detection, and contacts and calendar each need one optional distribution package, and `capabilities` names the package when it is missing. [Package list](docs/desktop-bridge.md)
  189. [Desktop guide](docs/desktop-bridge.md) · [Desktop skill](.agents/skills/interceptor-desktop/SKILL.md)
  190. <a id="iphone"></a>
  191. ## iPhone and iOS automation
  192. **Drive apps on a physical iPhone and inspect more than its screen.** Interceptor's own on-device XCUITest runner handles UI work; additional interfaces expose developer and device services.
  193. Setup requires an owned, unlocked iPhone in Developer Mode, pairing with your Mac, a Full installation, and Xcode signed into an Apple ID (a free personal team works; its signing lasts 7 days and Interceptor renews it). Connect by USB for initial pairing. Wi-Fi operation is available once paired, with network reachability between the phone and Mac. Away from your Mac, including on cellular, open InterceptorRunner on the phone and it connects back over Tailscale.
  194. ```bash
  195. interceptor ios discover
  196. interceptor ios setup
  197. interceptor ios tree
  198. ```
  199. `setup` builds, signs, installs, and launches the runner. Complete any on-device XCTest authorization prompt yourself, grant Local Network access when needed, and keep the phone unlocked and awake during automation. This operates the phone's foreground UI. It does not provide the desktop's background-use guarantee.
  200. | Area | Capabilities |
  201. |---|---|
  202. | App interaction | Ref-tagged element trees, find/inspect, taps, text, scrolling, dragging, long presses, multi-finger gestures, hardware buttons, screenshots, a continuous frame stream over Wi-Fi, and app launch/activate/terminate. Taps, drags, swipes, and gestures also take screen coordinates, for games and canvas apps with no element tree. |
  203. | On-device scripts | `ios eval` runs JavaScript inside the runner, combining UI reads, decisions, and actions in one request. |
  204. | Developer telemetry | Process lists, CPU/memory and GPU sampling, app launch with arguments, and location simulation through supported device services. |
  205. | Web content | `ios web` inspects exposed Safari and WKWebView targets: page structure, JavaScript, console, and network activity. |
  206. | Device inspection | Logs, diagnostics, crash reports, profiles, and supported media or app-container file access. Availability depends on iOS, pairing, and service permissions. |
  207. Use `--on <alias>` to select a phone when several are configured. For setup, exact verbs, service limits, and connection recovery, see the [iPhone guide](.agents/skills/interceptor-ios/SKILL.md) and [command reference](.agents/skills/interceptor-ios/references/command-catalog.md).
  208. ## Record and reuse workflows
  209. Teach a browser workflow by doing it once while Interceptor records clicks, inputs, navigation, DOM changes, and correlated traffic. Export the session as a timeline or a replay plan:
  210. ```bash
  211. # Start with an open Interceptor-managed browser tab.
  212. interceptor monitor start --instruction "Search the catalog and compare two items"
  213. # Perform the workflow.
  214. interceptor monitor stop
  215. # Use the session ID returned above:
  216. interceptor monitor export <session-id> --plan
  217. ```
  218. Native Mac recording uses `interceptor macos monitor` and the same `export <session-id> --plan` pattern. Review a generated plan, supply any missing inputs, and check the result when replaying it.
  219. For longer browser jobs, `monitor task` stores checkpoints, target context, lessons, and verification checks. Resume a task across agent sessions; `task complete` runs its checks and marks it complete only when they all return `true`.
  220. [Browser recording](.agents/skills/interceptor-browser/workflows/record-and-replay.md) · [Mac recording](.agents/skills/interceptor-macos/workflows/record-and-replay-mac-flow.md) · [Durable task state](.agents/skills/interceptor-browser/workflows/task-state.md)
  221. ## How it compares
  222. As of 2026-10-22, from each project's own documentation (sources below the table). Corrections are welcome in [Discussions](https://github.com/Hacker-Valley-Media/Interceptor/discussions).
  223. | Tool | Browsers it drives | How it reaches the page | Desktop apps | Physical iPhone | Works with |
  224. |---|---|---|---|---|---|
  225. | **Interceptor** | Chrome, Brave, Edge, Safari, in your own profiles | Its extension; Chrome's debugger only when you ask for it | macOS, Windows, Linux | Yes, installed apps | Any agent that runs commands, or MCP |
  226. | Playwright MCP, `--extension` mode | Chrome, Edge (its own launched Chromium, Firefox, or WebKit otherwise) | An extension that uses Chrome's `debugger` permission | No | No | Any MCP client |
  227. | Chrome DevTools MCP, `--autoConnect` | Chrome 144+ | Chrome DevTools Protocol; you turn on remote debugging and click Allow | No | No | Any MCP client |
  228. | agent-browser | Chrome and Chromium (your profile with `--profile` or `--auto-connect`); Safari on iOS through Appium | Chrome DevTools Protocol; WebDriver for Safari | Electron apps, through CDP | Safari only, over USB with WebDriverAgent | Any agent that runs commands |
  229. | Claude in Chrome | Chrome, Edge, and other Chromium browsers | An extension that declares Chrome's `debugger` permission | Separate product: Claude Desktop computer use | No (Claude's iOS pane drives simulators only) | Claude, with a direct Anthropic plan |
  230. | Cua Driver | Chrome and Edge windows, Electron apps; Safari and Firefox are not supported | Chrome DevTools Protocol | macOS, Windows, Linux | No | Any agent that runs commands, or MCP |
  231. | Tencent BrowserSkill | Chrome, Edge | An extension that drives pages through `chrome.debugger` | No | No | Any agent that runs commands |
  232. Sources: [Playwright MCP README](https://github.com/microsoft/playwright-mcp) (`--extension`: "Edge/Chrome only") and [extension manifest](https://github.com/microsoft/playwright/blob/main/packages/extension/manifest.json); [Chrome auto-connect guide](https://developer.chrome.com/docs/devtools/agents/use-cases/auto-connect); [agent-browser README](https://github.com/vercel-labs/agent-browser) (iOS and real-device sections); [Claude Code Chrome docs](https://code.claude.com/docs/en/chrome), [iOS Simulator docs](https://code.claude.com/docs/en/desktop-ios-simulator), [Claude Desktop docs](https://code.claude.com/docs/en/desktop), and the [Claude extension](https://chromewebstore.google.com/detail/claude/fcoeoabgfenejglbffodgkkbkcdhcgfn) package manifest (version 1.0.102); [Cua Driver docs](https://cua.ai/docs/cua-driver) and [browser guide](https://cua.ai/docs/cua-driver/guides/browsers); [BrowserSkill README](https://github.com/Tencent/BrowserSkill) and [extension config](https://github.com/Tencent/BrowserSkill/blob/main/apps/extension/wxt.config.ts).
  233. **When to use something else**
  234. - **Headless runs in CI, or many browsers in the cloud:** use Playwright or a cloud browser service. Interceptor drives a desktop browser on your own computer.
  235. - **Chrome only, and one assistant already covers the task:** Claude in Chrome or your assistant's own browser extension may be enough.
  236. - **Testing your own iOS app in the Simulator:** Xcode's simulator tooling or Claude's iOS Simulator pane fits better. Interceptor is for a physical iPhone.
  237. - **Android phones:** Interceptor does not drive Android; [mobile-mcp](https://github.com/mobile-next/mobile-mcp) does.
  238. - **Disposable virtual machines or sandboxes for agents:** see [Cua](https://github.com/trycua/cua).
  239. ## Go deeper
  240. These interfaces add access beyond ordinary UI controls. Each has its own setup and support boundaries.
  241. | Interface | What it adds | Guide |
  242. |---|---|---|
  243. | Electron / Chromium apps | Read DOM, execute JavaScript, inspect traffic, and capture an app's web contents with `macos cdp` or `macos cdp app`. Some attachment paths require an app relaunch. | [App control](.agents/skills/interceptor-macos/references/cdp-app.md) |
  244. | Native runtime | Inspect live objects and layers, call selectors, change rendered text, and observe calls with `macos runtime`. Requires a compatible target and an agent dylib; advanced extensions are separate from the core package. | [Runtime setup and commands](.agents/skills/interceptor-macos/references/native-agent.md) |
  245. | Research | A browser-based investigation workflow with query planning, saved sources, corroboration, and an evidence ledger. Start with `interceptor research` or the research skill. | [Research skill](.agents/skills/interceptor-research/SKILL.md) |
  246. | Extensions | Add operator-supplied bridge domains, commands, runtime agents, and skills. Inspect installed extensions with `interceptor extensions list`. | [Extension authoring](docs/extensions/authoring.md) |
  247. The default browser path and passive capture do not require CDP. Electron control uses CDP where appropriate, and optional browser debugger commands are available separately.
  248. ## Permissions and data
  249. Interceptor runs locally and hands results to the agent or script you choose. That agent may send content to its model provider. Interceptor's browser extension has no publisher analytics; see the [privacy policy](docs/privacy.md) for its access, passive page buffers, and storage behavior.
  250. - **Real access:** commands act in your accounts and apps. Browser commands normally target managed tabs, but the extension's permissions and local capture hooks are broader than that task boundary.
  251. - **Credentials by name:** the macOS keychain-backed vault can deliver a secret to an allowed target with `--secret`; supported Chromium saved logins can also be filled by host. Standard browser reads mask password and credential-marked fields. This is not blanket redaction of screenshots, scene reads, eval, or network data.
  252. - **MCP permissions:** reads and UI mutations are enabled by default. Destructive and arbitrary-code execution tiers require operator opt-in and confirmation. These gates belong to MCP; the direct CLI follows its own command contracts.
  253. - **Focus:** default browser and Mac actions preserve your working context. Browser `--os` input requires a focused target; browser pixel-screenshot fallback may briefly borrow focus. Use `--no-fallback` when that is unacceptable.
  254. [Permission guide](.agents/skills/interceptor-macos/references/permissions.md) · [Credential delivery](.agents/skills/interceptor-macos/references/accessibility-and-input.md) · [MCP controls](docs/mcp.md)
  255. ## Documentation
  256. Start with the [browser guide](.agents/skills/interceptor-browser/SKILL.md), [Mac guide](.agents/skills/interceptor-macos/SKILL.md), or [iPhone guide](.agents/skills/interceptor-ios/SKILL.md). For implementation details, read [Architecture](ARCHITECTURE.md); for agent operating rules, read [AGENTS.md](AGENTS.md).
  257. ```bash
  258. interceptor help # Capability overview for your installation
  259. interceptor help <command> # One command's usage and options
  260. interceptor help --all # Full command reference
  261. interceptor manifest # Machine-readable command contracts
  262. interceptor diagnose # Runtime and extension diagnostics
  263. ```
  264. ### Updates and troubleshooting
  265. On a Full Mac installation, `interceptor update` checks for an update and `interceptor update status` reports progress. Windows and Linux Full installs update the way Sparkle updates a Mac: once a day the native provider checks the signed feed on `updates.hackervalley.media`, and a newer release opens Interceptor's update window with its release notes and **Skip This Version**, **Remind Me Later**, and **Install Update**. Nothing downloads or installs until you click. The installer is checked against the signed feed (plus its Authenticode signature on Windows), then **Install and Relaunch** installs it. `interceptor update` checks now and opens the window when there is an update; `interceptor update status` shows what happened. Set `INTERCEPTOR_AUTO_UPDATE=off` in the provider's login environment to stop the daily checks. Browser-only users can run a newer installer; `interceptor upgrade --full` adds Mac native capabilities.
  266. If no browser context connects, check that both the runtime and extension are installed and enabled. `interceptor diagnose` distinguishes store and unpacked versions. If Interceptor disappears every time the browser restarts, run `interceptor diagnose extension`. It finds a profile that loaded the unpacked copy before 1.0.1 (an entry for the old extension ID blocks the folder), a load from `scripts/install.sh` that lasts one session, and two copies running at once. `--fix` repairs the first by restarting Brave, Vivaldi or Chromium on macOS; everything else gets exact steps. Installs and updates run the same check and ask before touching a browser. On macOS 27, an app needs your permission to read Chrome, Brave and Edge settings, so the check runs inside the bridge: in System Settings > Privacy & Security > Files & Folders, turn on each browser under `interceptor-bridge`, or give `interceptor-bridge` Full Disk Access. On a Mac that had Interceptor before 1.0.1, the installer asks and checks as soon as access is on. `interceptor reload --context <id>` reloads an unpacked extension; a store copy remains subject to store publication. For missing native permissions, use `interceptor macos trust --walkthrough`.
  267. macOS package removal: `sudo bash "/Library/Application Support/Interceptor/uninstall.sh"`. Add `--bridge-only` to remove native Mac support while retaining Browser.
  268. ## Development and contributions
  269. The CLI, daemon, and browser extension use TypeScript and Bun. The native Mac bridge and iPhone runner use Swift. A local daemon routes commands to the selected browser, bridge, app runtime, or device.
  270. For a source install, use Bun and an installed Chrome or Brave browser. The default build on macOS also builds the native bridge and requires macOS 15+ and a Swift 6.2 toolchain. Source builds work on Apple silicon and Intel Macs. The `interceptor macos vm` commands require Apple silicon.
  271. ```bash
  272. git clone https://github.com/Hacker-Valley-Media/Interceptor.git
  273. cd Interceptor
  274. bun install
  275. bun run build
  276. bash scripts/install.sh --browser-only --brave
  277. # On macOS, use --full instead of --browser-only for native capabilities.
  278. ./dist/interceptor open "https://example.com"
  279. ```
  280. Enable Developer Mode in the selected browser profile before loading an unpacked extension. Branded Chrome requires manually loading `extension/dist/` from its extensions page. The installer can relaunch Brave and asks before closing a running instance. Windows source installs use `scripts/install.ps1`; see the [Windows guide](docs/windows-install.md).
  281. For code changes, run the checks appropriate to the affected surface:
  282. ```bash
  283. bun run typecheck
  284. bun test
  285. bun run build
  286. ```
  287. [Report a bug](https://github.com/Hacker-Valley-Media/Interceptor/issues) with the version, OS/browser or device, command, expected result, and relevant redacted output. Contributions to code, reproducible workflows, and documentation are welcome.
  288. ## License and credits
  289. Interceptor is licensed under [Elastic License 2.0](LICENSE). See [commercial terms](COMMERCIAL.md).
  290. **If Interceptor saves you time, a star on this repo helps other people find it.**
  291. Created by [Ron Eddings](https://github.com/ronaldeddings/). Thanks to [Pedram Amini](https://github.com/pedramamini/) for early feedback and [Maestro](https://runmaestro.ai), [Daniel Miessler](https://github.com/danielmiessler/) for the name and [PAI](https://github.com/danielmiessler/PAI), [Klaus Agnoletti](https://github.com/klausagnoletti/) for Edge/Vivaldi installer support, and [Alex Tabisz](https://github.com/atabisz/) for Linux support.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.