Codex Browser Bridge

What @delicious233/codex-browser-bridge does

@delicious233/codex-browser-bridge turns the local ChatGPT desktop app and browser-extension connection into an MCP endpoint. Agents can operate an existing browser profile rather than launching a separate WebDriver-controlled browser or copying profile data. The bridge is intended for work involving real browser state, including logged-in applications, dashboards, documentation pages, and local development servers.

The project is written in Rust and distributed through an npm package, platform binaries, and a Claude Code plugin. It exposes 66 MCP tools across basic, network, and full tool surfaces.

How it works

At startup, the bridge searches for the local transports created by the codex-browser-use service. It discovers live browser-extension instances, then uses the extension's JSON-RPC protocol to perform browser operations. It does not install another extension, merge browser profiles, or copy browser data.

A session controls one extension instance at a time. If exactly one live instance is found, it can be selected automatically. When multiple instances are available, use codex_list_browsers to inspect them and codex_bind_browser with the exact browser ID to select one. Reconnection remains pinned to that instance instead of silently moving to another profile.

On Linux, socket discovery uses CODEX_BRIDGE_SOCKET_DIR, then the standard runtime and temporary locations. A Linux or WSL process must find a socket within its own environment; it does not automatically discover a Windows pipe across the operating-system boundary.

Setup and configuration

For Claude Code, install the plugin with:

claude plugin install codex-browser --marketplace DeliciousBuding/codex-browser-bridge

The plugin retrieves the npm package and matching platform binary through npx on first use. Alternatively, install the package globally:

npm i -g @delicious233/codex-browser-bridge

A release binary can also be downloaded from the project's GitHub releases. The npm and npx route requires Node.js 18 or newer. Operation also requires a supported local extension transport, a supported Chromium browser, and the ChatGPT desktop app/browser-extension service.

Browser selection can be pinned with the --browser-family and --browser-instance options or their corresponding environment variables and TOML settings. The lower-level --pipe option is available as an explicit transport override.

Tools and capabilities

The exposed tools support:

• Opening, closing, switching, and listing browser tabs
• Page navigation, history movement, and load waiting
• Viewport PNG screenshots
• DOM and accessibility-tree inspection, including ARIA role and name searches
• Clicking, typing, and scrolling with selectors, coordinates, or accessibility node IDs
• JavaScript execution in the page context
• File uploads through file input elements
• Alert, confirmation, and prompt dialog handling
• Reading and setting cookies
• Explicitly allowlisted CDP diagnostics
• Connection and environment checks through codex_doctor

Limitations and notes

Chrome and Edge use the same Chromium automation backend but remain separate browser instances with distinct tabs, cookies, extensions, and sign-in state. Brave, Opera, and Vivaldi are expected to use the same Chromium pipeline, while macOS has no published binary or live verification. Published Windows ARM64 and Linux ARM64 builds exist, but their verification scope differs from the fully gated Linux x64 build.

Successful file upload depends on the extension's file-access permission. Rebinding a session that owns tabs requires codex_finalize or an explicit end_previous_turn: true on codex_bind_browser; this performs cleanup before changing instances. The bridge supports legacy MCP lifecycle versions and the stateless MCP 2026-07-28 lifecycle.