Architecture

ABG connects a browser tab to an agent through three local pieces: the browser extension, the Gateway app, and the abg CLI.

Browser tab + ABG extension
        |
        | WebSocket on 127.0.0.1:8765
        v
Gateway app
  - permission manager
  - plugin host
  - audit log
        |
        | local IPC
        v
abg CLI
        |
        v
AI coding agent

When the agent cannot see a tab

Each piece can be checked from the terminal:

abg status
abg tabs --compact
abg audit --lines 20

abg status fails with gateway_not_running: the Gateway app is not running.
extensionCount is 0: the extension is not connected to the Gateway.
abg tabs --compact lists no tabs: nothing is shared, or the share ended.
abg audit shows what the Gateway did, including revokes.

Extension

The extension is where the user gives consent. In per-tab mode, the agent starts with no visible tabs. When the user shares a tab from the popup, the extension sends that tab’s metadata and command responses to the local Gateway.

The optional all-tabs mode is for isolated profiles and sandbox machines. It requests optional host access only after the user turns it on. Turning it off revokes every all-tabs entry.

Gateway

The Gateway listens on loopback and owns the runtime state:

connected extension instances
shared tabs
operation approval state
loaded plugins
the local audit log
app settings and plugin state

The development app uses a separate port, 8766, and separate state, so development plugins and settings do not change production state.

CLI

abg is the stable interface for agents. Any tool that can run shell commands can inspect and operate a shared tab, and a person can run the same commands to see what the agent sees.

The CLI uses one JSON contract over platform-local IPC: Unix domain sockets on macOS and Linux, and named pipes on Windows. On macOS, when sandbox or path-length limits prevent a usable socket, it falls back to a token-authenticated loopback WebSocket. ABG resolves and cleans up the endpoint, so callers do not need OS-specific transport details.

Plugins

Plugins are local JavaScript modules loaded by the Gateway. They transform browser data, add domain-specific Markdown extraction, or register commands. Tab operations from plugins use the same approval and audit path as CLI operations. See Plugins.

Platforms

Chrome is the first browser target. Firefox uses a browser adapter and a Firefox extension target. The iPhone Safari target uses the paired companion app for DOM inspection and the page actions that Safari Web Extensions support. Desktop Safari and Android are separate platform tracks.

Mobile pairing

Mobile pairing connects a phone to a desktop Gateway owned by the same user. Before any tab or approval surface is available, pairing proves which desktop Gateway the phone trusts.

The pairing commands are:

abg companion offer
abg companion offer --manual
abg companion confirm <pairing-id>
abg companion list
abg companion revoke <device-id>

offer shows a QR code and a manual code. confirm finishes pairing after both devices show the same code. revoke removes the phone and closes its session.

Pairing methods

| Method | When to use it | Status | | --- | --- | --- | | QR code | The desktop can show a short-lived pairing URL and the phone has a camera. The user confirms the same code on both devices. | Shipped. The QR payload expires after five minutes and only starts a scoped pairing token. | | Manual code | The camera is unavailable or screen sharing hides the QR code. | Shipped as a fallback. It uses a short code plus desktop confirmation. | | Tailnet link | The user already runs a private Tailnet and needs pairing across networks. | Shipped as the preferred private remote boundary. It never routes through an ABG-operated relay. | | Private LAN address | No Tailnet address is available on a trusted LAN. | Shipped through the same authenticated pairing listener. ABG does not advertise the Gateway through automatic LAN discovery. |

Desktop consent starts from a browser action on the same machine: the user shares one tab, and the share ends when the tab closes, changes origin, or is revoked. Mobile adds a device and session layer before tab consent:

A paired device gets no tab access by default. Pairing grants the tab_sharing scope, but the user must still share the active Safari tab from the extension popup.
The desktop Gateway owns the pairing list, session lifetime, approval state, and audit log.
Mobile approval forwarding can approve or reject a pending desktop operation. It cannot grant tab visibility by itself.
A mobile session is scoped to one Gateway, one paired device, and explicit approval, status, and tab-sharing capabilities.
Revoking the mobile session removes the device from the pairing list and invalidates its pending approval prompts and pairing tokens.
Revoking an iPhone Safari tab share removes that tab from the desktop Gateway immediately. Closing the tab or changing its origin also revokes it.

The iPhone Safari target supports tab listing, DOM reads, getters, predicates, semantic find, snapshots, tables, clipped and full-page screenshots, text and area annotations, explicit cross-origin frame grants, site-scoped cookie inspection, encrypted file upload, native Reading List insertion, tab activation, waits, editable validation, storage inspection, approved eval, and DOM-level page actions. Actions need approval in the paired iPhone app unless the user turns on Trusted automation in the Safari extension popup. A shared tab stays scoped to its approved origin and reconnects to the same Mac-side ref after Safari suspends it.

Network boundaries

The local-only desktop workflow is the default and the highest-trust mode. The Gateway listens on loopback for CLI and extension traffic, and ABG works with all non-loopback networking blocked.

Tailnet is the preferred private remote boundary. The user or organization controls the Tailnet, device enrollment, DNS, and firewall policy. ABG starts the remote-pairing listener only while an offer or active grant exists. Pairing requires device confirmation, and later connections require an active scoped session token.

A private LAN address is the fallback when no Tailnet address is available. ABG does not use automatic LAN discovery. It would advertise the Gateway on untrusted networks, make lookalike Gateways easier to phish with, and confuse setups with several Gateways.

Extension 1.3.6 also offers an optional Cloud path, separate from local/private pairing. Web login registers the browser, and client authorization scopes access to shared tabs. The selected service can process shared metadata and requested results; this path is not local-only. See the Cloud guide for endpoints, credentials, and consent.

Limits

Safari has no Chrome DevTools Protocol equivalent for console and network capture, HAR, PDF, emulation, download metadata, native low-level input, or tab recording. These commands return unsupported_on_safari with a platform-specific reason.
Mac clipboard payloads are unavailable. File uploads encrypt bytes on the Mac and send only the file name, MIME type, digest, and ciphertext to the paired Safari extension. The Mac path is not sent.
Sandbox all-tabs access is Chrome only.
Android and embedded WebView support are separate platform tracks.

Security: consent boundaries and the audit log.
CLI: commands for each piece.