opencode-chromium
Advanced tools
Provider-neutral Chromium and Firefox browser automation for MCP, OpenCode V2, Codex, and direct JavaScript agents.
Your browser, connected to your coding agent.
Four compact tools. Local action memory. Optional decision assistance.
Install the matching browser extension, then connect all detected supported harnesses and native hosts:
npx -y opencode-chromium@latest setup --all
Setup shows what changed and keeps transactional backups. Preview with --dry-run --json. Quit and reopen desktop harnesses, or reconnect MCP in terminal clients. Firefox and LibreWolf also require launching with remote debugging enabled; see the Firefox launch instructions.
npx -y opencode-chromium@latest setup --targets codex
Both use the shared Codex MCP configuration. A native Codex plugin bundles the MCP server and browser skill; see the Codex guide for marketplace installation.
npx -y opencode-chromium@latest setup --targets claude-code
npx -y opencode-chromium@latest setup --targets claude-desktop
Supported setup targets: Windows and macOS.
npx -y opencode-chromium@latest setup --targets opencode
Uses the native adapter by default and the detected version's configuration format. OpenCode guide.
npx -y opencode-chromium@latest setup --targets dsh
Registers MCP in the Cordis profile patch. Harness guide.
Add this stdio server to your client's MCP configuration:
{
"mcpServers": {
"browser": {
"command": "npx",
"args": ["-y", "opencode-chromium@latest", "mcp"]
}
}
}
npm install opencode-chromium
import { createBrowserAgent } from "opencode-chromium/sdk";
| Browser family | Connection | Setup |
|---|---|---|
| Chrome, Edge, Brave, Chromium | Chromium extension and CDP | Store extension + native host |
| Firefox, LibreWolf | Firefox extension and WebDriver BiDi | Signed add-on + native host + Remote Agent enabled at launch |
Desktop discovery covers Windows, macOS, and Linux. Firefox requires version 140 or later; LibreWolf must expose the matching Remote Agent. Compatible derivatives need individual validation; this does not claim support for every fork. See Firefox capabilities and compatibility for transport differences and verification limits.
Named profiles choose the browser. Agents keep the same four tools: browser_run, browser_observe, browser_session, and browser_finalize. Sessions own their tabs, targets are checked against the live page, and uploads require confirmation by default. Profiles · Security.
Optional capability packs provide snapshot/pixel diffs, bounded frame inspection, experimental WebMCP discovery, detailed network and console inspection, and Chromium performance traces. Agents request these descriptions when needed, so the default tool list stays compact. Sessions can name their tab groups for the task. Examples and limits.
On this small fixture, Jev selected 11/12 targets, Luna text 9/12 and lexical search 7/12. Luna image calls reached the existing 1.5-second deadline and fell back locally. These are component measurements on one synthetic page, not complete browser-agent task success or a ranking against Browser Use. Exact matches skipped paid calls; missing cost reports remain unknown. Results and methodology.
bun run benchmark:accuracy
The default runs locally without paid requests. Add --cloud to compare Jev text, Luna text and Luna image using your configured OpenRouter key in isolated temporary settings. That experiment makes at most 18 requests and can incur charges. It does not change your saved provider choice. Candidate-pool misses, abstentions and timeouts remain in the score.
Firefox-based browsers require the Remote Agent to be enabled at launch. The add-on alone cannot provide the browser-level control used by this plugin: Firefox does not expose Chromium's debugger extension API. The plugin therefore uses WebDriver BiDi for trusted clicks, keyboard input, and native dialogs. Installing the add-on or opening Developer Tools does not enable this connection.
Install the Firefox add-on, run the setup command above, and connect the extension. Copy the Firefox/LibreWolf profile ID from the extension's Profiles section.
Replace PROFILE_ID below with that ID and configure the local connection:
npx -y opencode-chromium@latest firefox configure --profile PROFILE_ID --port 9223
Finish active agent sessions and fully exit the selected browser. Relaunch it with --remote-debugging-port 9223, using the same browser profile that registered the extension. Adding the flag while the browser is already running does not enable the Remote Agent.
Windows — PowerShell (adjust the executable path if installed elsewhere):
& "C:\Program Files\Mozilla Firefox\firefox.exe" --remote-debugging-port 9223
# Or LibreWolf:
& "C:\Program Files\LibreWolf\librewolf.exe" --remote-debugging-port 9223
macOS — Terminal:
/Applications/Firefox.app/Contents/MacOS/firefox --remote-debugging-port 9223
# Or LibreWolf:
/Applications/LibreWolf.app/Contents/MacOS/librewolf --remote-debugging-port 9223
Linux — Terminal:
firefox --remote-debugging-port 9223
# Or LibreWolf:
librewolf --remote-debugging-port 9223
Check that the configured port is reachable, then select the matching named profile in your agent:
npx -y opencode-chromium@latest firefox status --profile PROFILE_ID
The status command checks port reachability; the extension verifies the browser/tab identity when automation attaches. Repeat the launch flag whenever you start the browser for agent use. For multiple profiles, use a separate port per running browser instance and configure each extension profile accordingly.
Keep remote debugging bound to loopback; do not expose its port to your network. Other local programs can access the Remote Agent, so a dedicated automation profile is recommended. To stop remote debugging, fully exit the browser and relaunch without the flag. See Firefox setup and troubleshooting and Mozilla's Remote Agent security documentation.
Overview shows the local connection, selected decision model, and memory status, with setup guidance when disconnected. Profiles lets you name and copy the profile for your agent. Settings holds decision assistance, uploads, memory retention, and advanced controls. Detailed usage, timings, and storage controls expand when you need them, with consistent widths and automatic light and dark themes.
Cloud assistance is off by default. Choose Jev through OpenRouter or TypeSafe, or OpenAI Luna through OpenRouter. Separately opt in to bounded screenshots for visual decisions. Jev's experimental image fallback runs only after an unsure text answer, with persistent request caps. Exact matches stay local; timeouts and abstentions retain local results. Decision assistance, costs and limits · Local action memory.
Extension updates open what’s new once per version in a background tab. Turn this off in the extension’s setup guide.
Published CLI installations set up with setup --all can keep their managed runtime aligned automatically. Updates wait for agent processes to exit, install into a separate versioned directory and leave running sessions alone. Settings → Updates shows progress and the automatic-update switch. Development checkouts and pinned commands stay manual. Existing installations need one run of npx -y opencode-chromium@latest setup --all to enable the new flow. CLI controls: opencode-chromium updates status, updates on, or updates off. Updates target the exact extension version; an npm release that is not available yet is retried after six hours. This updates the managed browser runtime, leaving global package-manager installations and explicit version pins unchanged.
The scheduled chart workflow refreshes these assets. npm download counts are package downloads, not unique users or extension installs.
npx -y opencode-chromium@latest setup --all --dry-run --json
npx -y opencode-chromium@latest setup --targets codex,opencode
npx -y opencode-chromium@latest manage
npx -y opencode-chromium@latest doctor --json
npx -y opencode-chromium@latest status --json
npx -y opencode-chromium@latest uninstall --targets codex
Use --config harness-id=/absolute/path for a custom configuration. Existing aliases, package names, profiles, and runtime data remain supported. Troubleshooting.
bun install --frozen-lockfile --ignore-scripts
bun run build
bun run build:extension
bun run build:extension:firefox
bun run check
bun run check:firefox
Both extensions share WXT/React source. Separate output directories prevent one build replacing the other. Forward version bumps on master trigger npm and store release workflows. Mozilla submissions can remain pending review before publication. Architecture · Firefox publishing.
Questions and ideas: Discussions. Bugs: Issues. MIT license.
FAQs
Provider-neutral Chromium and Firefox browser automation for MCP, OpenCode V2, Codex, and direct JavaScript agents.
The npm package opencode-chromium receives a total of 38 weekly downloads. As such, opencode-chromium popularity was classified as not popular.
We found that opencode-chromium demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Threat Research
/Security News
Socket uncovered secret-stealing workflows that ran in LiteLLM’s GitHub repository 11 days before the supply chain attack on PyPI and Docker.
Security News
Cloudflare introduces tsrs, a Rust port of TypeScript’s compiler promising faster checks and lower memory use, with the TypeScript team’s help.
Security News
The PHP Foundation says Chainguard broke a security embargo ahead of critical RCE patches, as leaks disrupted the coordinated release.