Give your agent your browser, Mac, and iPhone.
Browser automation, computer use, and iPhone automation for AI agents.
Get started · Browser · macOS · iPhone · Record & replay · Docs
Interceptor connects an AI agent or script to your signed-in browser, native Mac apps, 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.
| Work you can build with Interceptor | Tools available |
|---|---|
| Research in your existing browser session | Page text, tables, links, browser search, multiple contexts, and a source-ledger research workflow. |
| 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. |
| Complete a native Mac task while you keep working | Accessibility controls, background input, Apple Events, and capture of covered windows. |
| Operate an app on a real iPhone and inspect its state | Element trees, taps, text entry, screenshots, process telemetry, and WebKit inspection. |
| Turn a demonstrated workflow into reusable commands | Browser and Mac recording, event timelines, and replay-plan export. |
Use it from any agent that can run shell commands, or through its built-in Model Context Protocol (MCP) server. Interceptor does not require a model API key; your chosen agent or model may have its own subscription or API costs.
- Your existing browser session. Work with the profiles, cookies, and logins you already use. The default browser path uses an extension rather than launching a separate automated browser.
- Look beyond pixels. Read DOM and accessibility structure, inspect network activity, and use specialized interfaces for rich editors, Electron apps, native runtimes, and iPhone services.
- Background automation. Browser and native Mac operations default to background execution so you can keep working. Explicit activation brings a target forward when needed. Behavior and exceptions.
- Keep the evidence. Return text or JSON, save artifacts, record workflows, and verify task state before marking a browser task complete.
- Use one command vocabulary.
open,read,act, andinspectcombine common steps; detailed verbs and agent skills cover deeper work.
Download an installer from Releases. Start with Browser for web tasks, or Full for native Mac and iPhone work.
| Host / package | What it enables |
|---|---|
macOS: Interceptor-Browser-<version>.pkg |
CLI, daemon, and browser extension files. |
macOS: Interceptor-Full-<version>.pkg |
Browser package plus the native Mac bridge and iPhone tooling. The bridge requires macOS 15+. |
macOS: Interceptor-Safari-<version>.pkg |
Safari extension add-on, installed after either core package. |
Windows 11 24H2+: Interceptor-Browser-<version>-windows-{x64,arm64}.exe |
Browser automation. Windows installation guide. |
Linux: Interceptor-Browser-<version>-linux-{x64,arm64}.tar.gz |
Browser automation and install scripts. |
The macOS release binaries target Apple silicon. Windows and Linux support browser automation; native desktop control and iPhone setup require a Mac.
- Install the Browser or Full
.pkgfrom Releases. - In Chrome or Brave, install the Interceptor extension. The local runtime and browser extension are both required.
- For Safari, also install the Safari
.pkg, open/Applications/InterceptorSafari.apponce, then enable Interceptor and website access in Safari → Settings → Extensions. Safari requires your approval. - With Full, grant the permissions needed by your task to
interceptor-bridge. Runinterceptor macos trust --walkthroughfor 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.
On Windows, run the architecture-matched installer, 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 also covers unpacked extensions, silent installation, updates, and removal.
On Linux, extract the architecture-matched archive and run this from its directory:
bash scripts/install.sh --browser-only --brave
# For Chrome, use --chrome instead of --brave.
./dist/interceptor open "https://example.com"Follow the installer's extension-loading instructions. The archive includes compiled binaries, so a separate Bun installation is not needed for this release path.
With the extension enabled and browser open:
interceptor open "https://example.com" --group first-task
interceptor read --group first-task
interceptor group close first-taskopen 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.
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.
For a shell-capable agent, adopt the browser, macOS, iOS, and research skills into detected agent runtimes. Mac and Windows installers bundle them; Linux archive users can run adoption from a source checkout containing .agents/skills/:
interceptor skills adoptFor an MCP client, register Interceptor and restart the client. The installer detects Claude Code, Codex, Gemini CLI, Cursor, and Claude Desktop:
interceptor mcp install
interceptor mcp statusThe 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.
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.
- 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.
- 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.
- 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.
- Files and exports: upload local files to inputs, drop zones, and supported file pickers. Save page-produced
Blob, buffer, orblob:URL bytes directly to disk withsave, including native exports from supported web apps. - Capture and browser data: screenshots, OCR, canvas inspection, cookies, storage, history, bookmarks, downloads, and session management.
- 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.
interceptor open "https://example.com" --group browser-task
interceptor find "Learn more" --group browser-task
interceptor inspect --group browser-task
interceptor group close browser-taskTo 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.
Browser command reference · Rich-editor workflows · Export capture
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.
interceptor macos trust
interceptor macos tree --app "Finder"
interceptor macos windows --app "Finder"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.
| Area | Capabilities |
|---|---|
| App control | Accessibility trees, text and values, clicks, typing, keyboard input, scrolling, dragging, menus, app lifecycle, and window placement. |
| Capture and perception | Covered/minimized-window screenshots, screen streaming, OCR and vision, system/microphone audio, speech recognition, sound classification, and language analysis. |
| Files and system work | Spotlight search, file reads/writes/watchers, clipboard, URL fetching, OS logs, AppleScript/JXA, JavaScriptCore scripts, and Apple Events. |
| Documents | PDF text, forms, annotations, merge/split operations, data detection, translation, and thumbnails. |
| Personal apps | Calendar, reminders, contacts, photos, location, music, maps, sharing, and notifications through the corresponding system frameworks and permissions. |
| Visual tools | HTML and SpriteKit overlays, window-anchored HUDs, capture streams, and virtual displays. |
| 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. |
Mac command reference · Background behavior · System and media tools · Documents · Personal data · Overlays · VMs
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.
Setup requires an owned, unlocked iPhone in Developer Mode, pairing with your Mac, a Full installation, and Xcode signed into an Apple Developer team. Connect by USB for initial pairing. Wi-Fi operation is available once paired, with network reachability between the phone and Mac.
interceptor ios discover
interceptor ios setup
interceptor ios treesetup 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.
| Area | Capabilities |
|---|---|
| App interaction | Ref-tagged element trees, find/inspect, taps, text, scrolling, dragging, hardware buttons, screenshots, and app launch/activate/terminate. |
| On-device scripts | ios eval runs JavaScript inside the runner, combining UI reads, decisions, and actions in one request. |
| Developer telemetry | Process lists, CPU/memory and GPU sampling, app launch with arguments, and location simulation through supported device services. |
| Web content | ios web inspects exposed Safari and WKWebView targets: page structure, JavaScript, console, and network activity. |
| Device inspection | Logs, diagnostics, crash reports, profiles, and supported media or app-container file access. Availability depends on iOS, pairing, and service permissions. |
Use --on <alias> to select a phone when several are configured. For setup, exact verbs, service limits, and connection recovery, see the iPhone guide and command reference.
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:
# Start with an open Interceptor-managed browser tab.
interceptor monitor start --instruction "Search the catalog and compare two items"
# Perform the workflow.
interceptor monitor stop
# Use the session ID returned above:
interceptor monitor export <session-id> --planNative 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.
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.
Browser recording · Mac recording · Durable task state
These interfaces add access beyond ordinary UI controls. Each has its own setup and support boundaries.
| Interface | What it adds | Guide |
|---|---|---|
| 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 |
| 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 |
| 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 |
| Extensions | Add operator-supplied bridge domains, commands, runtime agents, and skills. Inspect installed extensions with interceptor extensions list. |
Extension authoring |
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.
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 for its access, passive page buffers, and storage behavior.
- 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.
- 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. - 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.
- Focus: default browser and Mac actions preserve your working context. Browser
--osinput requires a focused target; browser pixel-screenshot fallback may briefly borrow focus. Use--no-fallbackwhen that is unacceptable.
Permission guide · Credential delivery · MCP controls
Start with the browser guide, Mac guide, or iPhone guide. For implementation details, read Architecture; for agent operating rules, read AGENTS.md.
interceptor help # Capability overview for your installation
interceptor help <command> # One command's usage and options
interceptor help --all # Full command reference
interceptor manifest # Machine-readable command contracts
interceptor diagnose # Runtime and extension diagnosticsOn a Full Mac installation, interceptor update checks for an update and interceptor update status reports progress. Browser-only users can run a newer installer; interceptor upgrade --full adds native capabilities. Windows updates use the newer signed installer. Linux updates use the matching release archive.
If no browser context connects, check that both the runtime and extension are installed and enabled. interceptor diagnose distinguishes store and unpacked versions. 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.
macOS package removal: sudo bash "/Library/Application Support/Interceptor/uninstall.sh". Add --bridge-only to remove native Mac support while retaining Browser.
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.
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:
git clone https://github.com/Hacker-Valley-Media/Interceptor.git
cd Interceptor
bun install
bun run build
bash scripts/install.sh --browser-only --brave
# On macOS, use --full instead of --browser-only for native capabilities.
./dist/interceptor open "https://example.com"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.
For code changes, run the checks appropriate to the affected surface:
bun run typecheck
bun test
bun run buildReport a bug with the version, OS/browser or device, command, expected result, and relevant redacted output. Contributions to code, reproducible workflows, and documentation are welcome.
Interceptor is licensed under Elastic License 2.0. See commercial terms.
Created by Ron Eddings. Thanks to Pedram Amini for early feedback and Maestro, Daniel Miessler for the name and PAI, Klaus Agnoletti for Edge/Vivaldi installer support, and Alex Tabisz for Linux support.