Installation
Two pieces. The Chrome extension and the CLI. One command wires them together.
Chrome Relay is two artifacts that meet in the middle:
- The extension runs inside Chrome, holds the CDP session, and executes browser actions.
- The CLI is what your agent invokes. It ships with the native messaging host that the extension connects to.
1. Install the extension
From the Chrome Web Store. Works in Chrome and Chromium forks: Edge, Brave, Arc, Vivaldi, Opera.
Permissions it asks for, and why:
| Permission | Used for |
|---|---|
nativeMessaging |
connecting to the local CLI host. This is the only channel out of the extension, and it goes to your own machine |
debugger |
CDP: trusted clicks, snapshots, screenshots, network/console capture |
tabs, tabGroups |
listing and targeting tabs, workspaces |
storage |
ref-map persistence across extension service-worker restarts |
2. Install the CLI
Needs Node.js 18 or newer — the CLI ships as an npm package and works on macOS, Windows, and Linux.
pnpm add -g chrome-relay # or npm i -g chrome-relay
chrome-relay install
install detects every Chromium-family browser on the machine and registers the native messaging host for each. On Windows it also writes the HKCU registry entries Chrome reads, and drops a run-host.cmd wrapper under %USERPROFILE%\.chrome-relay.
Windows note: if chrome-relay isn't recognized right after the global install, restart your terminal so PATH picks up the npm global bin (%APPDATA%\npm), then re-run chrome-relay install.
3. Verify
chrome-relay doctor
Doctor checks the whole chain: wrapper script present, native host starts, extension connects, local bridge reachable. Then:
chrome-relay tabs
If you get your window and tab list as JSON, you're done.
4. Teach your agent (optional but recommended)
If the CLI is installed, print the version-matched playbook:
chrome-relay skills get core
For agents with a skills directory:
npx -y skills add kiluazen/kstack@chrome-relay
The -y auto-confirms npx's "install the skills package?" prompt, so a headless agent doesn't hang on a TTY question. This installs the agent skill. It teaches the snapshot/ref loop, which text tool to pick for which editor, the fallback ladder, and the failure modes. Also available raw at /skill.md.
Troubleshooting
| Symptom | Fix |
|---|---|
extension_not_connected |
Install the extension, re-run chrome-relay install, then restart Chrome |
doctor says no wrapper |
Run chrome-relay install |
| Worked yesterday, dead today | Chrome may have restarted the native host. Retry once, then toggle the extension off/on |
| Commands hang ~15 s then time out | Another process is holding port 12122. Kill it or reboot the bridge by restarting Chrome |
unsupported_tool on snapshot |
Extension is older than the CLI. Update the extension from chrome://extensions |
Updating
chrome-relay update # updates the CLI and prints what changed, as JSON
chrome-relay release-notes --since 0.5.22 # just read the changelog
The changelog is agent-readable on purpose. Your agent can check what changed before relying on a new flag.