Installation

Two pieces. The Chrome extension and the CLI. One command wires them together.

Chrome Relay is two artifacts that meet in the middle:

  1. The extension runs inside Chrome, holds the CDP session, and executes browser actions.
  2. 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. Install it once in every browser profile you want your agent to reach.

The primary supported browsers are:

The installer also writes native-host manifests for detected Chrome Canary, Chromium, Edge, Vivaldi, Arc, and Opera installations. Those are compatibility targets; manifest detection does not by itself mean they have received the same end-to-end testing as Chrome, Dia, and Brave.

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
chrome-relay --version
chrome-relay profile list

Doctor checks the whole chain: wrapper script, per-browser manifests, connected extension instances, local hosts, versions, and upload file access. Multi-browser/profile routing requires CLI and extension 0.8.0 or newer. If chrome-relay --version stays below 0.8 after installing the latest package, find the stale executable first (which -a chrome-relay on macOS/Linux; where chrome-relay on Windows).

profile list is the authoritative answer to “which running browsers and profiles can my agent reach right now?” Then:

chrome-relay tabs

If you get your window and tab list as JSON, you're done.

Multiple browsers and profiles

One CLI serves every supported browser/profile where the extension is installed. Each extension instance has a stable generated ID; Chrome does not expose profile names, so you can attach your own labels:

chrome-relay profile list
chrome-relay profile label work                       # one instance connected
chrome-relay --profile 3f2a profile label personal    # several: select by ID prefix
chrome-relay --profile work tabs

With one connected instance, every command routes there and no flag is needed. With several, an unscoped command returns profile_ambiguous as a picker containing each label, browser, ID prefix, and exact --profile retry. Chrome Relay never guesses. Snapshot refs are profile-qualified (@3f2a:e12), so actions on a ref route themselves after the first snapshot.

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
profile_ambiguous Pick one of the exact --profile choices in the error and rerun the command
Browser missing from profile list Install the extension in that exact browser/profile, then rerun chrome-relay install
profile is an unknown command Your PATH is resolving a pre-0.8 CLI; locate and remove the stale executable
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.