browserctrl

AI agents drive your real Chrome via MCP — the kubectl for your logged-in browser.

npm i -g browserctrl installs the BrowserCtrl CLI on macOS and Linux. This package is a thin launcher; the native binary ships in a platform-specific sub-package that npm picks automatically based on your host.

Install

npm i -g browserctrl

You'll need:

• Node.js ≥ 20.10 (you have it; you're running npm)
• Chrome ≥ 120 with the BrowserCtrl extension loaded
• macOS (Apple Silicon) or Linux x64 / arm64

Quick start

browserctrl init      # one-shot wizard: state dir + manifests + MCP host config + pair code
browserctrl diagnose  # if something looks off

The wizard auto-detects Claude Desktop, Cursor, Windsurf, Zed, and Claude Code and offers to register browserctrl as an MCP server in each.

How it works

browserctrl declares 3 optional dependencies — one per supported platform:

"optionalDependencies": {
  "browserctrl-darwin-arm64": "0.4.0",
  "browserctrl-linux-x64":    "0.4.0-alpha.23",
  "browserctrl-linux-arm64":  "0.4.0-alpha.23"
}

Linux platforms are dormant on 0.4.0-alpha.23 artifacts; macOS Apple Silicon is the actively maintained target in the 0.4.x line.

Each sub-package declares its own os + cpu in its manifest, so npm only installs the one matching your host — the others are skipped silently. The meta package's bin/browserctrl.js then resolves whichever sub-package landed on disk and spawns its native binary.

Same pattern as esbuild, swc, biome, and prisma.

Troubleshooting

unsupported platform <os>-<arch> — npm i -g browserctrl supports darwin-arm64 (Apple Silicon), linux-x64, and linux-arm64. Intel Mac and Windows users should install from source: git clone + make build.

platform package ... is not installed — your install ran with --no-optional or --ignore-scripts, or hit an offline cache without the platform pkg. Retry: npm rebuild browserctrl or npm install -g browserctrl --include=optional.

Links

• Repository: https://github.com/DeRaowl/browserctrl
• Issues: https://github.com/DeRaowl/browserctrl/issues
• License: MIT OR Apache-2.0