Use Chrome Relay to Let Coding Agents Control Your Logged-In Chrome

What Is Chrome Relay?

Chrome Relay lets supported coding agents use your everyday Google Chrome profiles from the command line. Agents can access sites where you are already signed in while working through inactive background tabs, so automation does not take focus away from your current window.

The project works with Claude Code, Codex, Cursor, and Paseo. It connects their browser commands to Chrome through agent-browser. Commands typically complete in about 0.15 seconds, and Chrome does not need a remote-debugging port.

Chrome Relay is opt-in. It does not install its extension automatically, and it runs only on Macs whose owner has completed the setup.

How Chrome Relay Works

agent-browser CLI → local relay → Chrome Relay extension → agent tab

The system has three main components:

• Chrome extension: An unpacked Manifest V3 extension loaded separately into each Chrome profile you want agents to use. It opens agent tabs in an inactive, collapsed Agents tab group and sends DevTools commands through chrome.debugger.
• Local relay: A LaunchAgent listening on 127.0.0.1:9333. It gives each agent a separate DevTools endpoint and restricts the agent to tabs that it opened.
• Command-line tool: The chrome-relay command handles setup, connection URLs, identities, updates, diagnostics, logs, and audit records.

The relay suppresses commands that could raise or focus Chrome. Chrome may still display the message Chrome Relay started debugging this browser while an agent is working.

Requirements

Before installation, make sure you have:

• macOS
• Google Chrome
• Node.js 20 or newer
• agent-browser installed globally

Install agent-browser with npm:

npm i -g agent-browser

Install Chrome Relay

1. Clone and configure the project

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

The setup command creates the local secret, configures the background service, records identities, puts chrome-relay on your PATH, and links the Chrome Relay skill for Claude Code.

2. Load the extension into Chrome

Repeat these steps in every Chrome profile that agents should be able to use:

1. Open chrome://extensions.
2. Enable Developer mode.
3. Select Load unpacked.
4. Choose the repository's extension folder.

Because each Chrome profile loads its own copy of the extension, you can expose only the profiles you explicitly choose.

3. Verify the installation

chrome-relay doctor

Use the diagnostic output to confirm that the relay and extension are configured correctly before asking an agent to browse.

Tell Your Coding Agent About Chrome Relay

Claude Code

The setup process links skill/SKILL.md into ~/.claude/skills/chrome-relay. This makes the skill available across repositories. A repository-level CLAUDE.md only needs a one-line pointer to that skill when an explicit instruction is useful.

Codex, Cursor, and Other Supported Agents

Point the agent's global instructions to the same skill file. For example, add an instruction like this to ~/.codex/AGENTS.md:

For any browser step that needs my logins, follow /path/to/agent-chrome-relay/skill/SKILL.md.

Replace the example path with the absolute path to your cloned repository.

Run Your First Browser Automation

First ask Chrome Relay for an authenticated connection URL, then pass that URL to agent-browser:

agent-browser --cdp "$(chrome-relay url you@company.com)" open https://app.example.com/
agent-browser snapshot -i
agent-browser click @e5
agent-browser close

Replace you@company.com with the relevant configured identity and replace the example site with the page you want to automate.

1. chrome-relay url prints a connection URL containing this Mac's secret.
2. agent-browser open creates an inactive agent-owned tab and opens the requested page.
3. snapshot -i lists interactive controls such as links, buttons, and fields. Each receives a reference such as @e5.
4. click @e5 activates the referenced element using real input emulation in the background tab.
5. close ends the browser session.

Understand Sign-In Behavior

Agents do not type your credentials. If a site redirects through Google and the correct account is already signed in, the extension can select that account and click Continue or Allow. This uses page scripting and can work even when 1Password has placed a frame on the page.

If the flow reaches a password, passkey, two-step verification, or signed-out account screen, automation stops. The agent receives a SIGN-IN NEEDED message and should ask you to complete the sign-in in your own window.

Manage Profile and Site Identities

Identity configuration is stored in ~/.chrome-relay/identities.json. Inspect or manage it with:

chrome-relay identities

The configuration includes Chrome profiles discovered during setup, optional manually configured sites.rules, and sites.learned entries recorded after successful sign-in hops. By default, a site uses the account belonging to the selected Chrome profile.

Security Model

Every agent connection must pass two checks:

1. Local secret: Setup generates a token at ~/.chrome-relay/token with file mode 600. The token is embedded in URLs printed by chrome-relay url.
2. Allowed agent application: The connecting process must be associated with Claude Code, Codex, Cursor, or Paseo. The relay examines processes and the markers these applications set in child processes.

Connections carrying a browser Origin header are rejected even if they have the secret. The extension is also checked using its Chrome-derived extension ID, its chrome-extension:// origin, and the requirement that its connecting process is Chrome.

These controls keep unrelated local tools, web pages, and accidental connections out. They are not a security boundary against malware already running as your user, because such software could read the secret and imitate process markers.

Review the Audit Trail

Chrome Relay records agent activity in daily JSON Lines files under ~/.chrome-relay/audit/YYYY-MM-DD.jsonl. Read the records with:

chrome-relay audit

The audit trail includes connection details, the working folder, session identifiers, visited pages, click positions, special keys, agent scripts, screenshots, uploads, popups, sign-in clicks, and blocked pages. For privacy, typed text is represented only by its character count, and URL query strings are removed.

Advanced Behavior and Tips

Popups and New Tabs

Links using target=_blank and popups open as hidden tabs owned by the same agent. Popup authentication flows can still send messages back to the opener and close themselves. The relay enforces observed message origins and targetOrigin rather than trusting a page's claims.

1Password Pages

Chrome can detach an extension debugger when a page contains another extension's frame, such as the 1Password menu on a login form. Chrome Relay waits and reattaches before continuing agent commands.

Automatic Cleanup

Agent tabs are closed after 30 minutes of inactivity. When the relay restarts, the extension also closes tabs that it previously opened. Cleanup is based on tab IDs, so it does not modify your own tab groups.

Background Input

Focus emulation remains enabled in agent tabs. This allows clicks and typing to reach inactive tabs while your current Chrome tab stays in place.

Update, Diagnose, and Remove Chrome Relay

After pulling repository changes, restart the relay and reload the extension in every configured profile:

git pull
chrome-relay update

View relay logs with:

chrome-relay logs

The log file is stored at ~/.chrome-relay/relay.log. To uninstall the local service and command-line setup, run:

chrome-relay uninstall

Then manually remove the unpacked extension from each Chrome profile.

Development and Testing

To install relay dependencies and run the test suite:

cd relay && npm install && npm test

The tests cover connection authorization, including the secret, allowed applications, the Chrome-only extension connection, and audit behavior. After editing files under extension/, reload the extension with:

chrome-relay update

For custom environments, CHROME_RELAY_HOME overrides the data directory and CHROME_RELAY_PORT overrides the relay port.

Conclusion

Chrome Relay gives supported coding agents controlled access to existing Chrome sessions without requiring a remote-debugging port or taking over your active window. Once the local relay and unpacked extension are configured, you can automate authenticated browser tasks with agent-browser, choose identities per profile or site, inspect detailed privacy-conscious audit records, and rely on automatic cleanup for abandoned sessions.

For source code, updates, and issue reporting, visit the Chrome Relay GitHub repository. The project is available under the MIT License.