codex-browser-bridge

Let Claude Code and other MCP agents control your existing Chrome browser through Codex Desktop's browser bridge.

codex-browser-bridge is a small Go binary that exposes Codex Desktop's Chrome browser bridge as an MCP server.

It connects to the local Codex browser named pipe, speaks the same length-prefixed JSON-RPC protocol, and provides browser-control tools to Claude Code or any MCP-compatible agent.

Why

Codex Desktop can talk to its Chrome extension through a privileged native pipe. Other agents, such as Claude Code, cannot directly access that internal bridge.

This project reuses the local browser bridge that already exists on your machine and wraps it as an MCP server.

That means an agent can:

inspect your current browser tabs
claim an existing tab
open and close tabs
navigate pages
capture screenshots
read DOM / accessibility snapshots
click, type, scroll, and evaluate JavaScript

Useful when an agent needs to work with pages that require a real browser session, such as dashboards, logged-in web apps, local development servers, or documentation sites.

Status

Experimental.

The current version is designed for local Windows environments where Codex Desktop and the Codex Chrome Extension are already installed and running.

Features

MCP server over stdio
Single Go binary
No browser profile copying
Uses your existing Chrome session
Auto-discovers codex-browser-use-* named pipes
Talks to Codex Desktop's extension host through JSON-RPC
Uses Chrome DevTools Protocol commands for page control
Includes an interactive CLI mode for debugging

Requirements

Windows
Chrome
Codex Desktop running
Codex Chrome Extension installed and enabled
Go 1.23+ if building from source

The bridge connects to local named pipes created by Codex Desktop. If no pipe is found, start Codex Desktop first and make sure the extension is active.

Installation

Option 1: Install with npm

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

Option 2: Install with Go

go install github.com/DeliciousBuding/codex-browser-bridge/cmd/bridge@latest

Make sure your Go binary path is available in PATH.

Option 3: Download a release

Download the latest binary from:

https://github.com/DeliciousBuding/codex-browser-bridge/releases

Then place codex-browser-bridge.exe somewhere in your PATH.

Option 4: Build from source

git clone https://github.com/DeliciousBuding/codex-browser-bridge.git
cd codex-browser-bridge
make build

The binary will be generated at:

bin/codex-browser-bridge

Quick Start with Claude Code

Add the MCP server to your Claude Code settings.

{
  "mcpServers": {
    "codex-browser": {
      "command": "codex-browser-bridge",
      "args": ["-mode", "mcp"],
      "transport": "stdio"
    }
  }
}

If you built from source, use the absolute path instead:

{
  "mcpServers": {
    "codex-browser": {
      "command": "D:/path/to/codex-browser-bridge/bin/codex-browser-bridge.exe",
      "args": ["-mode", "mcp"],
      "transport": "stdio"
    }
  }
}

Restart Claude Code after editing the settings file.

Then ask the agent things like:

List my open browser tabs.

Open https://example.com in a new tab and take a screenshot.

Claim my current documentation tab and summarize what is visible.

CLI Usage

The binary has three modes.

MCP mode

Default mode. Used by Claude Code or other MCP clients.

codex-browser-bridge -mode mcp

Discover mode

Lists active Codex browser named pipes.

codex-browser-bridge -mode discover

Example output:

[
  {
    "Name": "codex-browser-use-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "UUID": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  }
]

Interactive CLI mode

Useful for debugging the bridge without an MCP client.

codex-browser-bridge -mode cli

Connect to a specific pipe:

codex-browser-bridge -mode cli -pipe "codex-browser-use-<uuid>"

Available CLI commands:

tabs
create
close <tab_id>
user-tabs
claim <tab_id>
nav <tab_id> <url>
snapshot <tab_id>
screenshot <tab_id>
info
ping
try <method> [json_params]
quit

MCP Tools

Tab management

Tool	Description
`codex_list_tabs`	List tabs managed by the current bridge session
`codex_create_tab`	Create a new browser tab
`codex_close_tab`	Close a browser tab
`codex_user_tabs`	List open tabs across browser windows
`codex_claim_tab`	Claim an existing user tab for automation

Navigation

Tool	Description
`codex_navigate`	Navigate a tab to a URL
`codex_navigate_back`	Navigate a tab back one entry in its history
`codex_navigate_forward`	Navigate a tab forward one entry in its history
`codex_reload`	Reload a tab
`codex_wait_for_load`	Poll `document.readyState` until `complete`

Page inspection

Tool	Description
`codex_screenshot`	Capture a screenshot (returns MCP image). `fullPage` parameter is reserved for future implementation — currently always captures the viewport.
`codex_dom_snapshot`	Get an accessibility tree snapshot
`codex_dom_get_visible`	Get a simplified visible DOM tree (human-readable; use codex_dom_snapshot for node IDs usable with codex_dom_click)
`codex_evaluate`	Evaluate JavaScript in the page context
`codex_get_info`	Get backend information from the extension

Interaction

Tool	Description
`codex_click`	Click an element by CSS selector
`codex_fill`	Fill an input by CSS selector
`codex_dom_click`	Click a DOM node by accessibility node ID from codex_dom_snapshot
`codex_cua_click`	Click by screen coordinates
`codex_cua_type`	Type text at the current focus
`codex_cua_keypress`	Press keyboard keys
`codex_cua_scroll`	Scroll by coordinates

Session

Tool	Description
`codex_name_session`	Assign a human-readable name to the browser session
`codex_finalize`	Finalize the session and clean up tabs

Architecture

MCP Client
  Claude Code / other agent
        │
        │ stdio JSON-RPC
        ▼
codex-browser-bridge
  Go binary
        │
        │ length-prefixed JSON-RPC frames
        ▼
Windows Named Pipe
  \\.\pipe\codex-browser-use-*
        │
        ▼
Codex Desktop extension host
        │
        ▼
Codex Chrome Extension
        │
        ▼
Chrome tabs

How It Works

The bridge searches for local named pipes matching codex-browser-use-*.
It connects to the selected pipe through go-winio.
Every request is encoded as a 4-byte little-endian length prefix followed by a JSON-RPC payload.
Browser operations are sent to the Codex extension host.
Page-level operations use Chrome DevTools Protocol commands such as Page.navigate, Page.captureScreenshot, Runtime.evaluate, and Input.dispatchMouseEvent.
The MCP layer exposes these operations as codex_* tools.

Security Notes

This tool gives an agent access to your active browser session.

Use it with the same caution you would apply to browser automation tools:

do not expose the bridge to a network port
do not run it for untrusted MCP clients
review agent actions before allowing sensitive operations
avoid using it on pages containing passwords, payment details, private tokens, or production admin consoles
remember that claimed tabs may already be logged in

The project is intended for local development and controlled automation.

Troubleshooting

No pipe found

No codex-browser-use pipes found. Is Codex Desktop running?

Check:

Codex Desktop is running
Chrome is running
Codex Chrome Extension is installed and enabled
the extension has been initialized by Codex Desktop

Claude Code does not show the tools

Check:

the binary is in PATH
the MCP server config points to the correct executable
Claude Code was restarted after editing settings
codex-browser-bridge -mode discover works in a terminal

CDP command fails

Some browser operations require the bridge to attach to the tab before sending CDP commands. If a tab was opened outside the bridge, list user tabs first, then claim the target tab.

Development

git clone https://github.com/DeliciousBuding/codex-browser-bridge.git
cd codex-browser-bridge

make test
make build

Common commands:

make build         # build binary
make test          # go vet ./... && go test ./...
make clean         # remove build output

Roadmap

Possible next steps:

richer error messages for common pipe / extension failures
non-Windows fallback or explicit platform guards
better screenshot output handling for MCP clients
typed tool result schemas
optional allowlist / confirmation layer for sensitive domains
examples for Claude Code, Cursor, Codex CLI, and other MCP clients

License

MIT License.

Disclaimer

This is an independent third-party project. It is not affiliated with, endorsed by, or connected to OpenAI, Codex Desktop, Anthropic, Claude Code, Google, or Chrome.

Acknowledgments

Thanks to LINUX DO for the community support and feedback.

Name		Name	Last commit message	Last commit date
Latest commit History 68 Commits
.github		.github
assets		assets
cmd/bridge		cmd/bridge
internal		internal
npm		npm
.gitattributes		.gitattributes
.gitignore		.gitignore
.golangci.yml		.golangci.yml
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
README.zh-CN.md		README.zh-CN.md
ROADMAP.md		ROADMAP.md
SECURITY.md		SECURITY.md
go.mod		go.mod
go.sum		go.sum

Folders and files

Latest commit

History

Repository files navigation

codex-browser-bridge

Why

Status

Features

Requirements

Installation

Option 1: Install with npm

Option 2: Install with Go

Option 3: Download a release

Option 4: Build from source

Quick Start with Claude Code

CLI Usage

MCP mode

Discover mode

Interactive CLI mode

MCP Tools

Tab management

Navigation

Page inspection

Interaction

Session

Architecture

How It Works

Security Notes

Troubleshooting

No pipe found

Claude Code does not show the tools

CDP command fails

Development

Roadmap

License

Disclaimer

Acknowledgments

About

Resources

License

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 4

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Packages