Agent Browser Gateway documentation

Get Started

Share one Chrome tab, read it with abg, then stop sharing it.

You need: a Mac with Apple Silicon on macOS 14 or newer, Google Chrome 120 or newer, and Homebrew. For Windows or source builds, see Install.

Quick start

Install the extension from the Chrome Web Store.

Install the Gateway app and the abg CLI:

brew tap arcmanagement/agent-browser-gateway https://github.com/arcmanagement/agent-browser-gateway
brew trust --cask arcmanagement/agent-browser-gateway/agent-browser-gateway
brew install --cask agent-browser-gateway

Start the Gateway and check that the extension is connected:
Terminal window
```
open -a "Agent Browser Gateway"
abg status
```
The menu bar icon appears. In the JSON from abg status, running is true and extensionCount is 1 or more.
Open the page you want to share. Click the ABG extension icon and choose Share this tab with agents. A green ON badge appears on the icon.

List the shared tab:

abg tabs --compact

[
  {
    "accessMode" : "manual",
    "browser" : "chrome",
    "ref" : "t1",
    "tabId" : 418,
    "targetId" : -1,
    "title" : "Example Domain",
    "url" : "https://example.com/"
  }
]

ref is the short name you pass to other commands. tabId and targetId will differ on your machine. A profile key also appears when you set a profile label in the popup. For one line per tab, run abg tabs --format text:

t1  418  manual  [Example Domain]  https://example.com/

Read the page as Markdown:
Terminal window
```
abg read t1 --format markdown
```
The command prints the page content as Markdown. Use the ref from step 5 if it is not t1.
Stop sharing the tab:
Terminal window
```
abg revoke t1
```
The command returns ok: true, and the tab no longer appears in abg tabs --compact.

To let Claude Code or Codex use the tab, install the agent skills with npx skills add arcmanagement/agent-browser-gateway -g and give the agent the tab ref. See Agent skills and MCP.

If it does not work

Every abg error is JSON with an error code and, in most cases, a nextCommand to run next.

gateway_not_running: the Gateway app is not running. Run open -a "Agent Browser Gateway", then abg status.
The shell cannot find abg: the CLI is not on your PATH. Run brew info --cask agent-browser-gateway to confirm the cask is installed, then open a new terminal.
extensionCount is 0, or the popup says Disconnected: the extension cannot reach the Gateway. Make sure the extension is enabled at chrome://extensions and the Gateway app is running, then open the popup again.
abg tabs --compact returns an empty tabs list with permittedTabCount 0, or abg tabs --format text prints No permitted tabs.: nothing is shared. Repeat step 4.
tab_ref_not_found: no shared tab has that ref. Run abg tabs --compact and use the current ref. A tab shared again after a revoke gets a new ref.
no_permitted_tabs or tab_not_permitted: the tab is not shared, or its share ended because it closed, changed origin, or was revoked. Share it again, then run abg tabs --compact.
The popup asks you to allow ABG in incognito: Chrome blocks extensions in incognito windows by default. Turn on Allow in incognito for the extension. See Install.

The agent sees no tabs until you share one.
A share ends when the tab closes, navigates to another origin, or you revoke it from the popup, the shortcut, or abg revoke.
Write commands such as click, fill, paste, navigate, and upload open a local approval window by default. Read-only commands do not prompt, but they still need a shared tab.
Every operation is written to a local audit log. Run abg audit --lines 50 to see recent entries.

Shortcuts act on the current tab only:

| Shortcut | Action | | --- | --- | | Alt+Shift+S (Option+Shift+S on macOS) | Share the tab, or revoke it if it is already shared. | | Alt+Shift+C (Option+Shift+C on macOS) | Copy the numeric tab ID. This does not share the tab. | | Alt+Shift+A (Option+Shift+A on macOS) | Start or stop annotating. Share the tab first if needed, using the existing sharing checks. | | Alt+Shift+M (Option+Shift+M on macOS) | Switch Area/Text while annotating. | | Unassigned | Clear all annotations; press twice within three seconds to confirm. | | Unassigned | Show or hide the annotation toolbar. |

The badge, its tooltip, and the popup show the result. Change the keys at chrome://extensions/shortcuts. The popup and annotation toolbar display the current assignments.

Drag the toolbar by its grip, or focus the grip and use the arrow keys. Its position and collapsed state are remembered. Dismiss a notice with its close button or Escape; ABG stops further Escape propagation and leaves annotation mode unchanged. Page handlers already registered on window capture can run first.

In isolated profiles or sandbox machines, select Matching domains under Tab sharing to share matching existing and new tabs automatically. Add multiple exact domains, wildcard subdomains such as *.example.test, or full-hostname regular expressions. Any matching condition is sufficient, subject to the shared HTTPS and port restrictions. Preview the matching tabs before applying. Leaving the allowed scope revokes automatic access. Rules are saved per connection, and editing them cancels Sandbox auto-resume consent. This mode requests the same optional <all_urls> permission as All tabs; use manual sharing in personal or mixed-use profiles.

Install: Windows status, DMG download, source builds, agent skills, and MCP.
CLI: read, inspect, operate, and annotate shared tabs.
Security: consent, approvals, audit log, and what ABG does not defend against.
FAQ: common questions and fixes.

Quick start

If it does not work

How sharing works

Domain sharing

Next