Codex Browser Bridge

English | 简体中文

A local Chromium extension, a persistent browser daemon and an MCP adapter that let Codex (or any MCP client) inspect and operate the browser tabs you explicitly allow. Arc, Chrome, multiple browser profiles and multiple Codex sessions can stay connected at the same time.

This is an independent implementation. It does not copy or impersonate OpenAI's proprietary browser extension.

Features

• Multi-browser, multi-profile – connect Arc, Chrome and several profiles at once; every profile gets a stable browser ID.

• Multi-session – one daemon owns the browser port; each Codex session starts a lightweight MCP adapter, so sessions never fight over the port.

• DOM snapshots with stable refs – compact accessibility-oriented snapshots return eN references you can click, type into, hover, etc.

• Page actions – navigate, click (by ref, CSS selector or exact visible text), type, keypress, scroll, hover, select, wait, screenshot.

• Secure by default – loopback-only, token-authenticated, host allowlist, password redaction, action kill switch.

Related MCP server: Local Browser MCP

Architecture

Arc / Chrome profiles (extension)
        │  WebSocket  ws://127.0.0.1:17373  (pairing token)
        ▼
Persistent daemon  (launchd on macOS, or `npm run daemon`)
        │  authenticated local RPC
        ▼
MCP adapter (session A)   MCP adapter (session B)   ...
        │ stdio
        ▼
Codex / Claude Code / any MCP client

Security model

• Listens on 127.0.0.1 only; non-loopback hosts are rejected at startup.

• A random 256-bit pairing token (generated on first run, stored with 0600 permissions) authenticates every connection.

• Only tabs whose host is in the extension's allowlist are visible. The allowlist is empty by default – you must add hosts yourself.

• No cookie, local-storage, history or password APIs are exposed. Password values are returned as [REDACTED], and typing into password fields is refused.

• Page actions can be switched off in the extension options while read-only inspection keeps working.

• MCP tool annotations distinguish read-only tools from actions, so the host can ask for confirmation before consequential actions.

Requirements

• Node.js 20+ and npm

• Arc, Google Chrome or another Chromium-based browser

• macOS for the bundled launchd installer (on other platforms run the daemon with npm run daemon)

Installation

1. Build and start the daemon

git clone https://github.com/tingfengyinyue/codex-browser-bridge.git
cd codex-browser-bridge
npm install
npm run check                 # build + tests
./scripts/install-daemon.sh   # macOS: install and start the launchd daemon
./scripts/show-pairing-token.sh

On Linux / Windows, keep the daemon running in a terminal instead:

npm run build
npm run daemon

The first start creates the pairing token in ~/.config/arc-browser-bridge/config.json. Never commit or share this token.

2. Load the browser extension

Repeat for every Arc / Chrome profile you want Codex to control:

1. Open arc://extensions or chrome://extensions.

2. Turn on Developer mode.

3. Click Load unpacked and select the extension/ folder of this repository.

4. Open the extension options page and fill in:

   • Connection name – a unique, human-readable name, e.g. Chrome-Work.

   • Bridge endpoint – keep ws://127.0.0.1:17373.

   • Pairing token – paste the output of ./scripts/show-pairing-token.sh.

   • Allowed hosts – one host per line, wildcards allowed, e.g. github.com, *.example.com. Keep this list as short as possible.

   • Allow click, type, navigation… – uncheck for read-only mode.

5. Click Save and connect and approve the host permission prompt. The popup should show Connected.

3. Register the MCP server

Codex CLI

codex mcp add arc-browser -- node /absolute/path/to/codex-browser-bridge/dist/index.js

or in ~/.codex/config.toml:

[mcp_servers.arc-browser]
command = "node"
args = ["/absolute/path/to/codex-browser-bridge/dist/index.js"]

The repository also ships a Codex plugin manifest (.codex-plugin/plugin.json, .mcp.json) and a skill (skills/arc-browser/SKILL.md) with operating rules for the agent.

Claude Code (works with any MCP client)

claude mcp add arc-browser -- node /absolute/path/to/codex-browser-bridge/dist/index.js

Usage

Start a new Codex session and ask, for example:

• "Inspect my active browser tab and summarize the page."

• "Find the Query button on the current tab without changing anything."

• "Open the dashboard page and read the numbers in the first panel."

Typical tool flow:

1. arc_browser_status – check that a browser is connected.

2. arc_browser_list_connections / arc_browser_select_connection – pick a profile when several are online (or pass browser_id to any tool).

3. arc_browser_list_tabs – find the target tab.

4. arc_browser_snapshot – read the page and get eN references.

5. arc_browser_click / arc_browser_type / … – act, then take a fresh snapshot.

MCP tools

Clicking React menu items by visible text

Snapshots include up to 200 extra candidates for visible elements whose computed cursor is pointer, so menus built from div/span still get eN references. If an item is visible in page_text but has no reference, click it by exact text:

{ "text": "Settings", "scope": ".side-menu", "occurrence": 1 }

scope is a CSS selector or a snapshot reference. Whitespace is normalized, and duplicate matches are refused unless scope or a 1-based occurrence disambiguates them. Text clicks still obey the action switch and the host allowlist.

Configuration

Daemon logs (macOS): ~/Library/Logs/CodexBrowserBridge/.

Uninstall

./scripts/uninstall-daemon.sh

Then remove the extension from chrome://extensions / arc://extensions, and optionally delete ~/.config/arc-browser-bridge/.

Troubleshooting

Development

npm run check                          # tsc build + vitest
node scripts/validate-extension.mjs    # static extension security checks
npm run smoke-daemon                   # daemon smoke test

See docs/acceptance-matrix.md for the capability matrix and docs/manual-acceptance.md for the live acceptance checklist.

License

MIT