Codex Edge Browser Bridge

A personal Microsoft Edge extension that gives a local Codex session on-demand access to tabs, bookmarks, and ordinary web-page content. The extension's toolbar switch is the authority: Codex cannot turn access on, and every browser-data tool is unavailable while the switch is off.

[!WARNING] This is an experimental, local-only bridge for a browser profile you control. While ON, Codex can read supported existing tabs and bookmarks. Actions are restricted to tabs the bridge created during that ON session, but those tabs still share the profile's cookies and signed-in state.

What it does

• Lists non-incognito Edge tabs and reads semantic page content while access is on.
• Lists or searches bookmarks without changing them.
• Opens URLs and bookmarks in inactive, agent-owned tabs.
• Clicks, types, scrolls, navigates, reloads, goes back, and closes only agent-owned tabs.
• Keeps existing tabs read-only.
• Returns to off after Edge, the extension service worker, or the native host restarts.

The bridge is on-demand. It does not watch tab changes or copy page content until Codex invokes a tool.

Supported environment

• Ubuntu/Linux with Microsoft Edge Stable 120 or newer.
• Node.js 18 or newer and npm.
• An authenticated Codex CLI with local MCP support.

The installer currently targets Edge Stable's Linux native-messaging directory. Other Edge channels and operating systems need different manifest locations and are not supported yet.

Quick start

git clone https://github.com/rakaar/codex-edge-browser-bridge.git
cd codex-edge-browser-bridge
npm ci
npm run check
npm run install:local

Then complete the one-time Edge setup:

1. Open edge://extensions in the Edge profile you want Codex to use.
2. Turn on Developer mode. If the sidebar is collapsed, open the menu in the upper-left.
3. Select Load unpacked and choose this repository's dist/extension/ directory.
4. Optionally pin Codex Edge Bridge to the toolbar.
5. Restart Codex once and resume the same saved thread so it loads the edge_browser MCP server.
6. Open the extension popup and turn access ON. Approve the first-use permission prompt.

The popup should report Access is on and Native host: Connected. It always starts OFF after an Edge, extension, service-worker, or native-host restart.

Security model

Codex -> stdio MCP server -> user-only Unix socket
      -> Edge native-messaging host -> MV3 extension -> browser APIs

• No TCP listener and no OpenAI API key.
• The Edge native host allowlists the deterministic extension ID jkknljmfkjdieackklpojdgfphdinnkm and verifies the caller origin again at runtime. The manifest's key value is public key material used only to keep that sideloaded ID stable; it is not a private signing key or credential.
• The Unix socket lives under $XDG_RUNTIME_DIR/codex-edge-bridge/ with mode 0600.
• Browser content, bookmark data, URLs, and form values are never written to disk or logs by the bridge.
• Optional tabs, bookmarks, scripting, HTTP, and HTTPS permissions are requested only from the popup's ON gesture.
• OFF disconnects the native host and clears in-memory ownership and element references. Turn off and revoke permissions also removes the optional Edge permissions.
• Password, payment, OTP, file, hidden, read-only, and disabled fields cannot be typed into.
• edge://, extension, file://, data, JavaScript, incognito, and unscriptable PDF-viewer pages are rejected.
• Page content is labeled as untrusted in the MCP server instructions and must never be treated as agent instructions.

The Unix account is the local trust boundary: another process already running as the same user can connect to the socket while the bridge is ON. The bridge also cannot prevent a permitted click in an agent-owned tab from using that Edge profile's existing login state. See SECURITY.md for the complete threat model and review notes.

Turning off stops future reads. It cannot erase browser content already included in a Codex conversation.

Build and verify

npm ci
npm run check

The build outputs:

• dist/extension/ — unpacked Edge extension.
• dist/native-host.cjs — Edge native-messaging host and Unix-socket broker.
• dist/mcp-server.mjs — local stdio MCP server for Codex.

Install locally

npm run install:local

The installer performs only these user-scoped changes:

• Copies the host binaries to ~/.local/lib/codex-edge-bridge/.
• Writes ~/.config/microsoft-edge/NativeMessagingHosts/com.codex.edge_bridge.json.
• Registers the local MCP server as edge_browser with codex mcp add.

The install command is idempotent for files created by this project. It refuses to overwrite an unrelated native-messaging manifest or an unrelated MCP entry named edge_browser.

Updating an installation

git pull --ff-only
npm ci
npm run check
npm run install:local

Then click Reload on the extension card in edge://extensions and turn access ON again. Reloading deliberately resets access to OFF. Restart Codex only when the MCP registration or server bundle changed.

MCP tools

Read-only tools:

• edge_status
• edge_list_tabs
• edge_list_bookmarks
• edge_snapshot

Agent-owned tab tools:

• edge_open_tab
• edge_open_bookmark
• edge_click
• edge_type
• edge_scroll
• edge_navigate
• edge_go_back
• edge_reload
• edge_close_tab

edge_snapshot returns normalized text, headings, links, and ephemeral element references. References expire after navigation or the next snapshot.

Safe browser fixture

Run the local fixture without touching logged-in sites:

npm run fixture

It listens on http://127.0.0.1:43119 and provides safe input, click, scroll, and navigation targets for the real Edge acceptance test.

Project layout

• extension/ — MV3 popup, service worker, content bridge, and tab-ownership policy.
• native/ — Edge native-messaging framing and the user-only Unix-socket broker.
• mcp/ — stdio MCP server and local socket client.
• shared/ — protocol, URL policy, sensitive-field checks, and runtime paths.
• scripts/ — reproducible build, install, uninstall, and fixture commands.
• tests/ — unit and process-level integration tests for policy, framing, the native host, and MCP.

Troubleshooting

• Developer mode is not visible: maximize edge://extensions or open its upper-left sidebar menu.
• Native host is disconnected: run npm run install:local, reload the unpacked extension, and turn it ON again.
• edge_browser tools are missing: restart Codex and resume the same thread; MCP configuration is read when a session starts.
• The extension immediately returns to OFF: open its popup and read the red error. The fail-closed behavior usually means the native host could not start or disconnected.
• A page cannot be read: internal Edge pages, built-in PDF pages, file:// URLs, incognito tabs, and other unscriptable pages are intentionally unsupported.

Uninstall

First turn the extension off. Then run:

npm run uninstall:local

The uninstaller removes only the matching native-host files and edge_browser MCP entry. Remove the unpacked extension separately from edge://extensions.