Chrome Relay
chrome relay
Your agents can check a dashboard, pull a report from a web app, fill in a form in an internal tool or review a staging site, in background tabs you never have to look at. They stop and ask you only when a page needs your password. Chrome Relay is a Chrome extension plus a small macOS service, and it works today with Claude Code, Codex, Cursor and Paseo.
works with Claude CodeCodexCursorPaseo
$ agent-browser --cdp "$(chrome-relay url you@company.com)" open https://app.example.com ✓ Example App https://app.example.com/ 0.6 s $ agent-browser snapshot -i - textbox "Search" [ref=e1] - link "Projects" [ref=e3] - button "New report" [ref=e5] $ agent-browser click @e5 ✓ Done 0.15 s $ agent-browser close ✓ Browser closed
Your agent runs these commands to open a page in a background tab, list its buttons and click one. The tab you are typing in stays in front the whole time.
Why use it
Claude Code, Codex, Cursor and Paseo can all use it today. They drive Chrome the same way, through the open-source agent-browser tool and Chrome’s standard DevTools protocol. You are not tied to one AI company’s browser extension, and switching agents changes nothing. Several agents can work at once, and each one sees only its own tabs.
Agent tabs open inactive, inside a collapsed “Agents” tab group. Your screen, your active tab and the app you are typing in don’t change while the agent works. Commands that would bring Chrome to the front are ignored.
The agent uses the logins already in your Chrome, in the profile you pick by email, so it can work in Google Workspace, GitHub or any web app you are signed in to. It clicks through Google account pickers for accounts that are already signed in, and popups open as its own tabs. It stops to ask you only when a page needs a password, passkey or 2-step code.
Commands go straight to your open Chrome over the DevTools protocol, so there is no browser to start. The agent reads a page as a short text list of its links, buttons and fields, instead of taking screenshots and looking at them.
How it works
Your agent runs agent-browser commands. A small service on your Mac passes them to the Chrome Relay extension, which carries them out in the agent’s own tab.
A small service on your Mac, reachable only from your Mac. It gives each agent its own connection, shows it only the tabs it opened, and ignores commands that would bring Chrome to the front.
You load it in each Chrome profile your agents may use. It opens agent tabs inactive in the collapsed “Agents” group and runs commands in them through Chrome’s chrome.debugger API, without opening a remote-debugging port.
chrome-relay sets everything up, prints the connection URL for a profile, checks your install with doctor and shows the audit log.
Security
The relay checks every connection. Only Claude Code, Codex, Cursor and Paseo running on your Mac, with your Mac’s secret, get through.
Created during setup and readable only by your user account. It is part of the URL that chrome-relay url prints, so keep that URL private.
The connection must come from Claude Code, Codex, Cursor or Paseo. The relay looks up the connecting process and checks for the markers those apps set, in that process or its parents.
On the Chrome side, the relay accepts only the extension from your own download, identified by its chrome-extension:// origin, and only from the Chrome process.
A connection that comes from a web page is refused, even if it has the secret.
Audit log
Run chrome-relay audit to see it. The log records which agent connected, the pages it opened, its clicks, special keys, scripts, screenshots, popups and Google sign-in clicks, in one file per day. Typed text is saved only as a character count, and query strings are removed from URLs.
$ chrome-relay audit 14:02:11 k3f9qa claude you@company.com session start cwd=/Users/you/app 14:02:11 k3f9qa claude you@company.com tab open tab=1832 14:02:12 k3f9qa claude you@company.com page tab=1832 url=https://app.example.com/reports 14:02:13 k3f9qa claude you@company.com click tab=1832 x=412 y=288 14:02:14 k3f9qa claude you@company.com type tab=1832 chars=24 14:02:14 k3f9qa claude you@company.com key tab=1832 key=Enter 14:02:15 k3f9qa claude you@company.com screenshot tab=1832 14:05:40 m81zpe codex admin@company.com google sign-in click tab=1840 site=admin.example.com account=admin@company.com 14:09:02 k3f9qa claude you@company.com session end tabs=1
chars=24 only the length of typed text is saved
?q=… query strings are removed from URLs
Install
It takes about two minutes. You need macOS, Google Chrome, Node.js 20+ and agent-browser.
Easiest
Paste this prompt into Claude Code, Codex or Cursor. The agent checks your Mac and runs setup, then tells you how to load the extension, which is the one step you do yourself. After a test it offers to tell your other agents how to use Chrome Relay.
Set up Chrome Relay on this Mac, so you and my other AI agents can use my signed-in Chrome from the command line, in background tabs. Repo: https://github.com/aindeev/agent-chrome-relay (read its README first). 1. Check the basics: macOS, Google Chrome, Node.js 20+, git and python3. If agent-browser is missing, install it with `npm i -g agent-browser`. Ask me before installing anything else. 2. Clone the repo to ~/agent-chrome-relay (if it's already there, `git pull` instead), then run `bin/chrome-relay setup` from the clone and read its output. 3. Loading the extension is my job, not yours. Tell me the exact path of the clone's `extension` folder, then walk me through it: in each Chrome profile I want agents to use, open chrome://extensions, turn on Developer mode, click Load unpacked and pick that folder. Wait until I say it's done. 4. Run `chrome-relay doctor` and fix whatever it reports until every line is ok. 5. Run `chrome-relay identities`, show me the profiles it found, and ask which email to use by default and which (if any) only for admin work. 6. Smoke test with the default profile: agent-browser --cdp "$(chrome-relay url <email>)" open https://github.com agent-browser get title agent-browser close Then confirm with me that nothing moved on my screen. 7. Make sure all my agents know how to use it. Claude Code already has it: setup linked the chrome-relay skill. For Codex, Cursor or other agents, propose a one-line addition to their global instructions (for example ~/.codex/AGENTS.md) that points to <clone>/skill/SKILL.md for any browser step that needs my logins. Show me the edit before you save it. Rules while you do this: - Never print, log or paste the URL from `chrome-relay url`. It contains this Mac's secret. - Never type my passwords, never pick Google accounts and never complete a sign-in for me. If a page needs a login, stop and ask me. - Never drive my Chrome any other way: no --auto-connect, no --cdp 9222, no --headed, no Playwright attached to it and no AppleScript.
The same prompt is at agent-chrome-relay.aindeev.com/setup-prompt.txt. To set it up by hand instead:
This creates your Mac’s secret, starts the background service, finds your Chrome profiles, adds chrome-relay to your PATH and installs the Claude Code skill. It is safe to run again.
chrome://extensionsDeveloper modeLoad unpackedextension/
Repeat this in every Chrome profile your agents should use, then run chrome-relay doctor to check.
Commands
$ chrome-relay setupone-time setup, safe to run again$ chrome-relay url [email]the connection URL agent-browser uses for a profile$ chrome-relay identitiesyour profiles, their Google accounts and which account each site uses$ chrome-relay statuswhich profiles and agents are connected$ chrome-relay doctorcheck the install and explain how to fix problems$ chrome-relay updateafter git pull, restart the relay and reload the extension$ chrome-relay auditshow recent audit log entries$ chrome-relay logsshow recent relay log lines$ chrome-relay uninstallremove the service, CLI link and skillFAQ
Setup installs a skill for Claude Code, so it knows how to use Chrome Relay everywhere. For Codex, Cursor and other agents, add one line to their global instructions that points to the same skill file. The setup prompt offers to do this for you.
Yes. Chrome shows a “Chrome Relay started debugging this browser” bar while agents work. You won’t get an “Allow remote debugging?” dialog, because Chrome Relay doesn’t open a debugging port.
No. Agents never type your passwords. If a Google account chooser shows an account that is already signed in, the extension picks it. If a page needs a password, passkey or 2-step code, the agent stops and asks you to sign in in your own window.
Not yet. Setup installs a macOS background service, so you need a Mac with Google Chrome.
To update, run git pull in your clone, then chrome-relay update. To remove it, run chrome-relay uninstall and remove the extension from each Chrome profile.
Let your agents use your Chrome Free and open source, for macOS
Get it on GitHub