Agent Chrome Relay in 2025: Practical Browser Control

Quick Answer: The agent chrome relay is an open-source tool by Alexey Indeev that lets CLI AI agents (like Claude Code, Cursor, and Codex) drive your personal Google Chrome instance in background tabs. Using a local Go daemon and a Manifest V3 extension attached via chrome.debugger, it allows agents to interact with your live web sessions in ~0.15s per command without window focus stealing or manual login hassles.

If you've ever watched Claude Code or Cursor spin up a headless browser only to get stopped dead by Cloudflare bot protection, missing session state, or mandatory 2FA prompts, you know the frustration. Managing headless browser profiles with manually exported JSON cookies breaks down the moment an OAuth token expires. The agent chrome relay changes this setup entirely by letting your terminal assistants piggyback directly on your live, authenticated Chrome browser tabs without stealing focus or popping open intrusive windows.

Here is what practitioners actually need to know to wire AI coding agents into real Chrome profiles safely.

Architecture: Chrome Debugger API vs Remote Debugging Ports

Traditional browser automation relies on starting Google Chrome with the --remote-debugging-port flag. Doing this across your everyday browsing session introduces two massive pain points: Chrome flags your browser with an annoying top banner ("Chrome is being controlled by automated test software"), and web applications detect the open debugging port to flag your session as an automated bot.

Agent Chrome Relay bypasses remote debugging ports entirely. Instead, it operates across three concise components:

1. agent-browser (CLI): The command-line wrapper that formats requests into browser commands (clicks, snapshots, navigation).
2. chrome-relay (Go Daemon): A local binary running as a LaunchAgent on 127.0.0.1:9333. It manages agent sessions, routes Chrome DevTools Protocol (CDP) commands, and strips out commands that attempt to bring the Chrome window to the foreground.
3. Chrome Relay Extension (MV3): An unpacked extension installed in your specific Chrome profiles. It attaches to background agent tabs using Chrome's native chrome.debugger API.

When your agent opens a link, the extension creates an inactive tab inside a collapsed tab group named "Agents". Commands execute asynchronously over WebSockets directly into the DevTools target. Because chrome.debugger is an internal browser API, command latency sits at around 0.15 seconds per command, compared to the 1.5–2.5 second cold-start overhead typical of launching fresh Playwright browser contexts.

There's a subtle failure mode here that trips up early setups. If Chrome suffers from extreme system memory pressure, V8's background tab discarder might discard an idle background agent tab. When an agent attempts to target an evicted tab reference (e.g., ref @e5), the relay throws a Target closed error. To prevent this, ensure your agent workflow issues quick state snapshots using agent-browser snapshot -i rather than assuming long-running tab instances persist across extended code compilation pauses.

Installing and Compiling Agent Chrome Relay on macOS

Unlike pre-built electron utilities, Agent Chrome Relay requires you to build the binary locally on your machine. This isn't an arbitrary friction step; macOS ties local Keychain items and Secure Enclave access to the binary's code signature. If you downloaded a pre-compiled binary, macOS would block it from accessing your local token store without constant authorization popups.

Step-by-Step Build Sequence

First, make sure you have installed Go 1.25+ and the global CLI driver:

brew install go
npm install -g agent-browser
xcode-select --install # Enables Secure Enclave & 1Password Swift bindings

Clone and compile the relay from the repository:

git clone https://github.com/aindeev/agent-chrome-relay
cd agent-chrome-relay
./build

The ./build script compiles the Go core binary alongside native Swift modules (internal/macos) and signs the resulting binary using your local Apple Development certificate or an ad-hoc local signature. Next, run the setup initialization:

./chrome-relay setup

This command creates a local configuration at ~/.chrome-relay/config.json, generates a random authentication token at ~/.chrome-relay/token with restrictive 0600 permissions, installs the background LaunchAgent, and automatically registers the command skill in ~/.claude/skills/chrome-relay for Claude Code integration.

Finally, open chrome://extensions in your desired Chrome profiles, toggle Developer mode, click Load unpacked, and select the extension/ directory inside your cloned repository folder. Run chrome-relay doctor in your terminal to verify that the daemon, CLI, and extension are communicating cleanly.

Security Architecture: Token Authentication and Process Tracking

Giving an LLM agent access to an active browser session signed into your production environments, AWS consoles, and primary email accounts requires strict boundaries. Agent Chrome Relay enforces a multi-layered security verification on every single incoming WebSocket connection.

When an agent attempts to run a browser command, the Go relay performs two non-negotiable checks:

• Secret Verification: The agent connection URL must supply the exact bearer token matching ~/.chrome-relay/token generated during local setup.
• Process Inspection: The relay inspects the calling process PID using system-level ps and lsof calls. It checks parent and child process trees for environment markers specific to approved developer tools (CLAUDECODE, CODEX_*, CURSOR_*, or PASEO_AGENT_ID).

Connections carrying a web page Origin header are explicitly rejected, even if they somehow supply the token string. This stops cross-site scripting (XSS) payloads on arbitrary websites from attempting to query 127.0.0.1:9333 to drive your browser.

Furthermore, the extension's target origin is pinned. Chrome assigns a deterministic local ID to unpacked extensions based on their absolute disk path. During setup, the relay registers this unique extension ID (chrome-extension://<id>). If a rogue browser extension attempts to impersonate the relay protocol, the Go daemon denies the WebSocket handshake.

Here is where popular security advice gets it wrong: many developers assume local socket applications are completely insulated simply because they bind to 127.0.0.1. In reality, local socket binding without process lineage checking leaves you wide open to local port scanning attack vectors. The relay's process-ancestry check provides a meaningful defense layer that standard local HTTP dev servers neglect.

That said, there is a real catch here: process marker checking is not a security sandbox against intentional local malware running under your user context. Malicious scripts running as your OS user can still inspect process trees or read local token files. The model is built to isolate legitimate AI coding assistants from untrusted web pages, not to defend against an already compromised workstation.

Authentication Flows: Handling Google OAuth and 1Password Passkeys

Most developer guides advocate for setting up automated credential-injection scripts that pass plain-text passwords directly into browser input fields. This approach is fundamentally flawed. Exposing passwords to an agent's context window creates severe log leakage risks and routinely triggers account security locks due to unexpected login heuristics.

Agent Chrome Relay handles authentication using a hybrid approach divided into two clear paths: automated OAuth hops and opt-in password vault delegation.

Automated Google Sign-in Hops

When a web service bounces through a Google OAuth sequence and your Chrome profile is already signed into that account, the extension handles the interaction directly. It programmatically clicks the active user card and approves the Continue/Allow prompt via DOM-level injection. The agent never sees your Google password or session tokens.

If the site encounters an explicit password prompt, a 2FA challenge, or a signed-out state, the extension halts execution immediately. It returns a standardized response to the terminal CLI:

SIGN-IN NEEDED: Please complete sign-in in your Chrome window.

At this point, the process halts until you manually complete the login in your primary Chrome interface, keeping full control over high-risk credentials in human hands.

Opt-in 1Password and Secure Enclave Passkeys

If you want your agent to handle login challenges autonomously, you can selectively enable native 1Password integration:

chrome-relay vault setup
chrome-relay passkeys on

When enabled, the Go relay communicates directly with the local 1Password CLI daemon to retrieve two-factor TOTP keys and stored passwords. For passkeys, it routes WebAuthn requests straight through macOS Secure Enclave using Touch ID authentication.

To prevent your fingerprint scanner from requesting physical touches every 5 seconds during a multi-site batch script, configure a limited reuse window:

chrome-relay passkeys reuse 120

This command instructs the relay to store a signed hardware assertion in memory for 120 seconds. During this window, the agent can complete sub-domain WebAuthn challenges without triggering repetitive Touch ID hardware prompts.

Agent Chrome Relay vs Headless Playwright vs Remote CDP

The following matrix outlines the key performance and security differences between mainstream agent browser control approaches:

Notice how traditional headless browsers penalize execution speed and authentication state. Operating inside an already warm, fully authenticated browser instance eliminates cookie management code from your agent prompts entirely.

Frequently Asked Questions

What is agent chrome relay and how does it work?

Agent Chrome Relay is a developer tool that bridges terminal AI agents like Claude Code or Cursor to your local Google Chrome profiles. It uses a Go background service and an unpacked Manifest V3 extension to execute browser actions via chrome.debugger inside hidden tab groups without popping up visible windows or stealing system focus.

How to fix agent chrome relay context errors without restarting Chrome?

If your agent reports context lost or detached debugger errors, open your terminal and run ./build && chrome-relay update. This rebuilds the local binary, restarts the local LaunchAgent daemon, and reloads the MV3 extension across all active Chrome profiles without dropping your logged-in website sessions.

Why does agent chrome relay require building from source on macOS?

Building from source allows macOS to tie local Keychain records and Secure Enclave hardware access directly to your local code-signing identity. Pre-compiled binaries downloaded from external sources cannot share your local system certificate footprint, which causes macOS security prompts to repeatedly block automated background actions.

Can agent chrome relay bypass Cloudflare and CAPTCHAs automatically?

Because the relay executes actions inside your actual, everyday Google Chrome profile, it automatically inherits your normal browser fingerprint, TLS signatures, and active cookie state. While it does not automatically solve visual CAPTCHAs, its authentic profile environment avoids triggering bot detection checks that normally block headless Playwright instances.

Take Action on Your Local Setup

Integrating the agent chrome relay into your daily workflow removes the friction of maintaining brittle session state for AI coding agents. Compile the relay locally this week, attach it to a secondary Chrome profile, and test it against a simple internal dashboard task.

If you want to optimize your developer workflow further, check out our guide on setting up custom Claude Code skills or read our deep dive into securing local developer tools on macOS.