opencode-chromium

Provider-neutral Chromium automation for MCP clients, OpenCode V2, Codex, and direct JavaScript agents.

Community and roadmap

The roadmap is shaped by users — open a proposal, upvote with reactions, and follow announcements on GitHub Discussions:

• Feature requests — start a proposal (the template keeps it structured): describe the problem and the workflow it should unlock; others vote with 👍/❤️ reactions. The maintainers triage voted proposals into upcoming work and tag them with their status (planned, in progress, released). Open a proposal →
• Announcements — releases, roadmap status, and maintainer notes. Follow announcements →
• Protocol — feature requests concern what this repository publishes (runtime, extension, native host, skills); bug reports and security findings belong in GitHub Issues instead.

What it provides

• Four compact default tools: browser_run, browser_observe, browser_session, and browser_finalize.
• The complete multi-operation browser engine behind explicit compatibility and capability modes.
• Context-lean evidence: observation summaries omit empty fields, duplicate text, and verbose html/styles (available only through detail: "debug"), and inline responses stay within the 4,096-character budget with oversized output spilled to artifact resources.
• Native hover, JavaScript dialog handling with approval gating, and png/jpeg/webp screenshots with quality control. Screenshot captures reach OpenCode and MCP clients as real images for direct visual inspection: fullPage: false grabs the visible viewport, fullPage: true captures the entire scrollable page (dimension-capped, with automatic jpeg compression for oversized captures).
• Non-intrusive background automation: clicks, typing, and navigation never activate the tab or bring its window forward, so you can keep working while the tool drives a background tab.
• Server-level origin policy (allowed/blocked origin globs) and file-root restrictions for uploads.
• Persistent session emulation (viewport, network, CPU, geolocation, color scheme, user agent, headers, init scripts) with automatic reset on finalize.
• Network request drill-down by requestId with artifact-backed body spillover, and source-mapped console stack traces.
• Performance diagnostics: browser_observe mode diagnostic records CDP traces and computes LCP, CLS, long tasks, TBT, and more in the native host; raw traces are artifact-first and CrUX/field data stays off.
• Action Memory (opt-in): a local, vector-searchable record of what worked and what failed, so later sessions reuse confirmed routes — searched by meaning, self-correcting via chain lineage, with maintenance controls and a dashboard in the extension. See docs/action-memory.md.
• Snowflake-default page search with explicit lexical/auto alternatives and Qwen deep retrieval without loading models in the extension.
• Profile-aware sessions, tab ownership, stale-target recovery, bounded read retries, conditional settling, approvals, and artifact resources.
• MCP stdio and loopback/ authenticated HTTP transports with protocol-clean stdout.
• A native OpenCode V2 adapter and shared OpenAI, Anthropic, Gemini, and MCP schema adapters.

Quick start (npm)

Install the published package once, then connect any supported client. The package ships the CLI (opencode-chromium), the MCP server bin (opencode-chromium-mcp), the browser extension, and the native host installer:

npx -y opencode-chromium-mcp

1. Install the package

npm install -g opencode-chromium

2. Load the browser extension

Install opencode-chromium from the Chrome Web Store. The unpacked flow below remains available for development and local testing.

Open chrome://extensions, enable Developer mode, and load the unpacked extension/ folder from the installed package:

npm root -g
# load "<that path>\opencode-chromium\extension" as an unpacked extension

The extension ID is derived from the load path, so keep the folder where it is. Note the ID shown in chrome://extensions.

3. Install the native messaging host

node "$(npm root -g)/opencode-chromium/scripts/install-native-host.js" --extension-id <extension-id> --browsers chrome

4. Connect a client

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["opencode-chromium"]
}

codex mcp add opencode-browser-plugin -- npx -y opencode-chromium-mcp

{
  "mcpServers": {
    "opencode-browser-plugin": {
      "command": "npx",
      "args": ["-y", "opencode-chromium-mcp"]
    }
  }
}

Choose only the setup for your client; you do not need all of them.

5. Verify

opencode-chromium doctor --json
opencode-chromium verify

All four tools (browser_run, browser_observe, browser_session, browser_finalize) are then available in every connected client. Do not enable both the native OpenCode adapter and the MCP server in one client session unless duplicate tools are intentional.

Profiles and action memory

Open the extension’s Profiles tab, choose a connected profile, and click Copy agent selector. Paste that selector into your first browser request. Renaming the current profile is optional.

The Overview defaults to this profile. Choose all profiles, select several profiles, or view older unassigned history. Actions are shared locally across profiles; selecting two profiles counts a shared action once while keeping their execution totals separate. Storage controls apply to the shared database.

Enable action memory in Settings. Page search works with the default settings; model downloads and search tuning are under Advanced search settings. A dash means no result yet, and an unavailable message means the host could not supply statistics.

The installed extension version appears in its header. Package and store versions can differ while a release is under review; a successful upload does not mean store approval.

On connection, the extension compares its version with the local native host and connected CLI/MCP clients. A toolbar badge and compact notice flag differences or unreported versions. Expand How to update for instructions, or choose Remind me in a week; instructions remain in Settings, and a different version combination prompts again. Checks stay local and do not install updates automatically. If local tools are newer, the notice explains that the store extension may still be awaiting approval.

Requirements

• Node.js 20 or newer for the npm package and SDK.
• Bun 1.1 or newer when building from source or running the repository scripts.
• A Chromium-family browser with the unpacked extension/ loaded.
• The native messaging host installed for the extension ID.

Install and build

bun install --frozen-lockfile
bun run build
bun run build:extension
bun test
bun run check

The package is released under the npm name opencode-chromium. The stable runtime and MCP server identity remains opencode-browser-plugin for client compatibility; the current release version is defined in package.json.

MCP

Run the four-tool server over stdio:

bun run mcp

Or use the packaged binary:

opencode-chromium-mcp

Loopback Streamable HTTP is available with:

bun run mcp:http

Non-loopback HTTP requires a bearer token in AGENT_BROWSER_AUTH_TOKEN (or the variable selected with --auth-token-env). The default server name is opencode-browser-plugin. Origin and file-root safety configuration is server-level: pass --allowed-origin / --blocked-origin globs, or set AGENT_BROWSER_ALLOWED_ORIGINS, AGENT_BROWSER_BLOCKED_ORIGINS, and AGENT_BROWSER_ALLOWED_FILE_ROOTS (see docs/mcp.md).

OpenCode V2

The package root exports the native adapter using OpenCode 1.18.x's official { id, server() } path-plugin module shape, alongside the V2 setup contract:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["opencode-chromium"]
}

For a local build, point the client at dist/adapters/opencode/index.js or use the opencode-chromium install --client opencode command. The adapter registers exactly four tools, sets codemode: false, and returns a cleanup function for reloads.

The same browser runtime is available through MCP compatibility mode; do not enable both surfaces in one client session unless duplicate tools are intentional.

Codex

Register the MCP server from the npm package:

codex mcp add opencode-browser-plugin -- npx -y opencode-chromium-mcp
codex mcp list

From a local checkout, register dist/adapters/mcp/server.js with Bun:

codex mcp add opencode-browser-plugin -- bun C:\absolute\path\to\dist\adapters\mcp\server.js

The bundled skill is skills/opencode-browser-plugin/SKILL.md. It follows the open Agent Skills standard and covers connector-first routing, profile selection, action batching, Snowflake-default search, approval tokens, artifacts, and finalization. It ships with agents/openai.yaml for the ChatGPT/Codex desktop Skills picker and MCP dependency metadata.

Install it for every skills-compatible client at once:

opencode-chromium install --client skills
opencode-chromium install --client skills --dry-run
opencode-chromium uninstall --client skills

This copies the skill to ~/.codex/skills/, ~/.claude/skills/, and ~/.agents/skills/ (under opencode-browser-plugin/), and registers an enabled [[skills.config]] entry in ~/.codex/config.toml while removing any stale opencode-browser-adapter entry.

Native host and extension

Load extension/ as an unpacked extension, then install the host:

bun run build:extension
bun run install:native-host -- --extension-id <extension-id> --browsers chrome
bun run check:native-host -- --json

The extension source lives in extension-src/: WXT owns the entrypoints, entrypoints/popup/App.tsx is the shared UI root, and static files live under public/. Use bun run extension:dev for development, bun run typecheck:extension for TypeScript checks, and bun run build:extension for the Chrome Web Store-ready package.

Use AGENT_BROWSER_* environment variables for new configuration. The older OPENCODE_BROWSER_* names remain lower-priority aliases through the 1.x compatibility window.

CLI

opencode-chromium doctor --json
opencode-chromium verify
opencode-chromium install --client opencode --dry-run
opencode-chromium install --client opencode-mcp --dry-run
opencode-chromium install --client codex --dry-run
opencode-chromium install --client skills --dry-run
opencode-chromium uninstall --client codex --dry-run
opencode-chromium uninstall --client skills --dry-run

Install and uninstall back up the named configuration before changing it, touch only the canonical entry, support dry runs, and report changed files.

Context and capabilities

The default tool schemas stay small. Request advanced descriptions through:

{"mode":"capabilities","pack":"downloads"}

Execute advanced work through browser_run without adding top-level tools:

{
  "steps": [{
    "action": "capability",
    "capability": "downloads.events",
    "input": {}
  }]
}

For deep request/response debugging, request the lazy network pack only when needed:

{"mode":"capabilities","pack":"network"}

Then execute network.inspect in browser_run with the target tabId. It follows the tab's CDP request/response lifecycle, supports URL/method/type/status/requestId filters, and returns redacted headers only when includeHeaders is requested. Bodies remain disabled unless explicitly requested and approved; bodyDelivery: "artifact" spills opted-in bodies to the artifact store instead of inline previews. browser_observe mode inspect with target.requestId returns a single request's lifecycle detail.

Large results and screenshots are artifact-first. Screenshot captures are additionally delivered inline as images to OpenCode (tool attachments) and MCP clients (image content), so the model sees the page; MCP clients can also retrieve the original bytes through browser://sessions/<session-id>/artifacts/<artifact-id>, and OpenCode can request the same URI with browser_observe mode artifact.

Repository layout

src/core/                 shared runtime, schemas, safety, artifacts, versions
src/browser/              profile-aware IPC client, policies, and operation engine
src/adapters/mcp/         universal MCP server and transports
src/adapters/opencode/    native OpenCode V2 adapter
src/adapters/sdk/         provider schema adapters and direct agent API
src/cli/                  install, configure, uninstall, doctor, verify
extension/                Manifest V3 browser integration
native-host/              native messaging host and semantic workers
skills/                   provider-neutral browser skill
tests/                    unit, contract, browser, and adapter regression tests
docs/                     architecture, compatibility, security, and migration guides

Verification and release

bun run build
bun run check:schemas
bun run check:package
bun run check:mcp
bun run test:contracts
bun run test:opencode
bun run pack
bun run test:tarball
bun run check:release

The release check rejects stale V1 paths, personal state, duplicate legacy package surfaces, schema growth beyond budget, and tarballs missing the built adapters.

Contributors run the verification suite locally before review. GitHub Actions reserves the complete release gate for a forward SemVer change to package.json on master; that workflow validates the matching extension manifest, publishes npm through Trusted Publishing, submits the extension to the Chrome Web Store, and creates the matching GitHub tag and generated release notes. GitHub's native secret scanning and push protection guard remote pushes without consuming Actions minutes. No npm token is stored in the repository or workflow, and maintainers do not create release tags manually.

Security

Browser content is untrusted. Consequential actions require short-lived immutable approval tokens; writes are never automatically repeated after uncertain execution. Artifacts are session scoped, expire, reject traversal, and are not written to logs. MCP protocol data stays on stdout and diagnostics stay on stderr.

See docs/architecture.md, docs/security.md, docs/compatibility.md, and docs/migration-1.0.md.

License

MIT