Give Codex a real browser. After installing BrowserClaw and this plugin, Codex reaches for BrowserClaw whenever it needs to open a site, log in, click through a flow, scrape a page, or capture visual evidence.
BrowserClaw is BrowserOS's Chromium-based browser for agents. This plugin is the bridge that lets the Codex desktop app drive it.
BrowserClaw runs on your machine and exposes a local MCP endpoint (the port is dynamic; http://127.0.0.1:9200/mcp by default). When Codex spawns this plugin, a small Node launcher discovers the live BrowserClaw URL, then hands off to mcp-remote, which bridges Codex's stdio to BrowserClaw's HTTP MCP endpoint. The plugin has no tools of its own; everything Codex sees comes from BrowserClaw.
Codex <-> launcher (discovers URL) -> mcp-remote (stdio <-> HTTP) <-> BrowserClaw
- BrowserClaw from https://browseros.com/agents (a Chromium-based browser). Open it once after installing so it initialises its local state.
- Codex desktop app from https://developers.openai.com/codex/app.
- Node.js 18 or newer on your PATH. This is required. Codex does not bundle a Node runtime for third-party plugins, so this plugin cannot run without your system Node. It uses
npx(which ships with Node) to fetch and runmcp-remoteon first use. Verify withnode --versionandnpx --version; if either is missing, install Node from https://nodejs.org first.
OpenAI's curated plugin directory does not accept third-party submissions yet, so you install this plugin by pointing Codex at this repo as a marketplace. Two one-time steps:
# 1. Register this repo as a plugin marketplace
codex plugin marketplace add browseros-ai/browserclaw-codex-app
# 2. Install the plugin from it (<plugin>@<marketplace>, both named "browserclaw")
codex plugin add browserclaw@browserclawThen start a new Codex thread so it picks up the plugin's skill and tools.
To pin a specific published version, add a Git ref:
codex plugin marketplace add browseros-ai/browserclaw-codex-app --ref v0.2.0Prefer the UI? In the Codex CLI or desktop app, run /plugins, choose Add Marketplace, enter browseros-ai/browserclaw-codex-app, then install BrowserClaw from the list. Start a new thread afterward.
Open BrowserClaw, then in the Codex desktop app start a new chat and ask:
Open browseros.com in a new tab and tell me the page title.
Codex should call BrowserClaw's navigate and read tools (surfaced as mcp__browserclaw__navigate and mcp__browserclaw__read) and answer.
Most users do not need to configure anything. The launcher discovers the live BrowserClaw MCP URL from ~/.browserclaw/runtime.json (with the manifest and server log as fallbacks), then the default port.
If BrowserClaw runs on a non-default port, add a loopback override to ~/.codex/config.toml:
[plugins."browserclaw@browserclaw".mcp_servers.browserclaw.env]
BROWSERCLAW_URL_OVERRIDE = "http://127.0.0.1:9300"The override must be a loopback address (127.0.0.1, [::1], or localhost); a non-loopback URL is rejected so a misconfigured value cannot forward Codex's traffic to a public host.
Restart the Codex desktop app and the override takes effect on the next plugin spawn. (The Codex desktop app's Settings UI does not surface per-plugin env vars; config.toml is the documented path.)
Refresh the marketplace snapshot, reinstall, and start a new thread:
codex plugin marketplace upgrade browserclaw
codex plugin add browserclaw@browserclawCodex says "BrowserClaw is not running".
Open the BrowserClaw app. The MCP server starts with the app. If you closed BrowserClaw, reopen it and ask Codex again.
Plugin installed but Codex is not using BrowserClaw for browsing tasks.
Tell Codex explicitly: "Use BrowserClaw to do X." The bundled skill nudges this routing, but explicit prompting is the most reliable way to verify the wiring.
Plugin fails to start, or a connection error.
When it cannot reach BrowserClaw, the launcher prints guidance (visible in Codex's plugin logs) and exits, so open BrowserClaw before starting your Codex session. Confirm it is installed and has been launched at least once (ls ~/.browserclaw/runtime.json should succeed), then restart the Codex desktop app.
First run is slow, or fails offline.
On first use, npx downloads mcp-remote. That needs network access once; afterwards it is cached. If BrowserClaw browsing hangs on the very first call, give it a moment or run npx mcp-remote@0.1.38 --help once to warm the cache.
The plugin runs its source directly: no build step, no bundler, no committed artifact. .mcp.json points Codex at plugins/browserclaw/server/launch.js, which uses only Node built-ins plus mcp-remote (fetched at runtime via npx). Edit server/*.js and it takes effect on the next plugin spawn.
Unit tests cover the discovery logic (loopback guard and the on-disk source readers) and the launcher's message + argument construction. They import the pure modules directly, so no running BrowserClaw and no network are needed:
cd plugins/browserclaw
npm testCI (.github/workflows/test.yml) runs them on every PR that touches server/ or test/.
The smoke harness spawns server/launch.js and asserts its discovery-to-exit behaviour for the unreachable and non-loopback override cases (no BrowserClaw or mcp-remote fetch needed):
npm run smokeFor the happy path, open BrowserClaw and run the bridge directly:
npx mcp-remote@0.1.38 http://127.0.0.1:9200/mcp --allow-httpTo test a local clone end-to-end against the Codex desktop app, wire it in as a personal marketplace:
mkdir -p ~/.agents/plugins
cat > ~/.agents/plugins/marketplace.json <<'EOF'
{
"name": "browserclaw-local",
"interface": { "displayName": "BrowserClaw (local)" },
"plugins": [{
"name": "browserclaw",
"source": { "source": "local", "path": "/absolute/path/to/browserclaw-codex-app/plugins/browserclaw" },
"policy": { "installation": "AVAILABLE", "authentication": "ON_USE" },
"category": "Developer Tools"
}]
}
EOFRestart the Codex desktop app. BrowserClaw shows up under your local marketplace; install from there.
.
├── .agents/plugins/
│ └── marketplace.json # makes this repo install-able as a Codex marketplace
├── README.md
├── REVIEWER.md # clean-machine-to-working-test walkthrough for reviewers
├── LICENSE
├── .github/workflows/
│ ├── test.yml # runs the unit tests
│ └── release.yml # cuts a GitHub Release on a version tag
└── plugins/
└── browserclaw/
├── .codex-plugin/
│ └── plugin.json # Codex plugin manifest
├── .mcp.json # stdio MCP server entry: node ./server/launch.js
├── skills/
│ └── browserclaw/ # SKILL.md: teaches Codex to reach for BrowserClaw
├── server/
│ ├── launch.js # entry: discover BrowserClaw, hand off to mcp-remote
│ ├── discovery.js # resolve the live BrowserClaw base URL
│ └── on-disk-discovery.js
├── test/ # unit tests for discovery + launcher
├── scripts/
│ └── smoke.js # dev-machine launcher smoke harness
├── assets/ # icon + logo
└── package.json
Pre-release. Public release will track the first tagged version. Submission to OpenAI's official Codex plugin directory will follow once self-serve publishing opens up.
MIT. See LICENSE.