aindeev/agent-chrome-relay/skill

Chrome Relay

Chrome Relay lets Claude Code, Codex, Cursor and Paseo agents drive background tabs in the person's everyday Chrome, with their real logins. Your tabs open inactive in a collapsed "Agents" tab group, you only see and control tabs you opened, and nothing on their screen moves. Tens of milliseconds per command.

export CHROME_RELAY_SESSION=<your-agent-name>                   # one session per agent
chrome-relay identities                                         # which profile (email) to use for what
chrome-relay open https://example.internal/ --profile you@company.com   # the first open starts your session
chrome-relay snapshot                # the page's controls, each with a ref like @e5 (text, cheap)
chrome-relay fill @e3 "text"; chrome-relay click @e5; chrome-relay wait "text:Saved"
chrome-relay get text main; chrome-relay screenshot shot.png
chrome-relay close --all             # ALWAYS when done: closes your tabs

For anything more than a click or two, use chrome-relay do "<goal>" --data ... --until ... (below).

A target is a ref from your last snapshot (@e5), a control's whole label ("Save", or button:Save when two kinds share it), or a CSS selector (#save, css:main button). A label matching two controls is refused, never guessed: use the ref it suggests. Every action first checks the control is still there, enabled, on screen and not covered, and says what changed. Refs don't carry over to a new page: snapshot again after it changes. chrome-relay help lists the rest: select, check/uncheck, type, press Enter, hover, dblclick, drag, upload, scroll, back, reload, get value|html|attr|count|url|title, is visible|enabled|checked, eval, pdf, console, errors, cookies, dialog accept|dismiss, tabs, tab <id>, downloads, save, cdp <Domain.method>.

Rules:

• Only Claude Code, Codex, Cursor, Paseo and pi processes are accepted. Agents that set no session id of their

own (Cursor) must set CHROME_RELAY_SESSION.

• If a connect fails, run chrome-relay doctor and fix what it reports yourself (it says how: `chrome-relay

update, restarting the service, ...). If chrome-relay` isn't installed, set it up by following https://agent-chrome-relay.aindeev.com/setup-prompt.txt; only loading the extension is the person's to do.

• Finish the job; don't hand it back. The person installed Chrome Relay so you carry their task through

to the end without them, fast. Signing in is part of the task, and they have authorized you to do it with everything below. Asking them is the last resort, not the default. On a sign-in page or a SIGN-IN NEEDED error, go down this list and use the first that works:

1. Already signed in: Google account choosers and Continue/Allow are clicked for you.
2. 1Password (chrome-relay vault): fill the username, password and 2-step code from the item for the site

(below). A code split over several one-character boxes: fill the first box, and the relay types one character per box.

1. A code or link sent by email or text message ("we sent a code to a•••@..."): read it yourself, from the

person's mail in a tab of yours (Gmail) or a mail tool you have, and type the code (or open the link) in your tab. The person has authorized this: don't ask them to copy it over, and don't refuse.

1. "Remember this device" / "Trust this browser" / "Don't ask again": tick it, so next time skips the code.
2. Signed in with a password or a code? If 1Password is set up and the site offers passkeys, give the account

a Chrome Relay passkey right away, in the same tab (see "Giving an account a Chrome Relay passkey"), so your next sign-in is one approval, with no password, code or email. Mention it in your reply. Only when none of these works (no item in the vault, a passkey only 1Password holds, an account they never shared) ask the person, saying exactly what you need ("add Wagepoint to the vault", "approve in 1Password"), and carry on with everything else meanwhile. Before asking, try every other way in the page offers ("Try another way", "Use your password instead", "Send a code by email"): the person is bothered only when you're out of options.

• Passwords only as 1Password references (op://...), never as text you type: a password in your command

would end up in your transcript. Pick the account that matches the person's request.

• Popups and "open in new tab" links open as new hidden tabs that belong to you (chrome-relay tabs, then

chrome-relay tab <id>). Never replace window.open or stub popups yourself: the relay already routes them, and a stub breaks the page. A page's alerts are accepted; a confirm or prompt is dismissed unless you said beforehand chrome-relay dialog accept [text].

• Everything you do is in the audit trail (chrome-relay audit). Typed text is stored only as its length.
• Never use remote debugging (--remote-debugging-port, --cdp 9222, --auto-connect), Playwright attached to

their Chrome, computer use or AppleScript against Chrome: those take over their screen.

• agent-browser still works through the relay if you prefer it: `agent-browser --cdp "$(chrome-relay url

you@company.com)" open <url> on the first command (the URL carries this Mac's secret: never print it into logs, PRs, chats or files), then plain agent-browser ...`. Don't mix the two in one task.

Downloading files (statements, invoices, exports)

Files a page hands over come to you, never to Chrome's Downloads: a download link, a PDF, an export the page's script builds, and a popup that turns into a file (a bank's blank popup that gets a signed link from its API). Click with --download and say where they go:

chrome-relay click "March statement" --download --into ~/dev/finance/wealthsimple   # waits for it (--timeout 30)
chrome-relay downloads [--into <dir>] [--wait 30]   # every file this session got; --into moves them there
chrome-relay open https://example.com/report.pdf --into .                            # an address that is a file
chrome-relay save - --into <dir> < links.txt   # addresses loaded with the tab's cookies, one "<url> [name]" a line

• Every action lists the files it brought (↓ saved …). Without --into they wait in the session's folder,

which is deleted when the session ends: move them before close --all.

• Many documents: click each one with --download, or collect their links in the page (eval) and pipe them

into save -. Don't build login tokens from cookies or fetch files with a script outside the browser, and don't write signed links to files: they're secrets until they expire (save never prints their query).

• ↓ blocked …: the page started a file on its own, not within a minute of your own click: click what makes it.

No file came? chrome-relay tabs shows a popup still open; chrome-relay errors says what the page threw.

Whole goals in one command: chrome-relay do

Once the page is open, hand Chrome Relay the goal instead of clicking step by step. It fills what you name, replays what worked on this site before, asks a fast decision model for the rest, and checks every action. It usually takes a few seconds where step-by-step takes minutes.

chrome-relay do "Invite the new teammate as an admin" \
  --data "Email=ada@example.com" --data "Role=Admin" --until "text:Invitation sent"

• Give every value you know as `--data <field label>=<value>`, keyed by the label the page shows ("Email",

"Project name"); it never invents values. Credentials only as op:// references (--data "Password=op://<vault>/<item>/password"), never in the goal text. The person's approval quotes the goal as your reason; add --why "<one short sentence>" when the goal alone doesn't say why you need the account.

• Always give `--until`: what the page shows when it's done (text:..., url:..., title:...,

no-text:..., selector:...). Only then is "done" verified, and only then is the run saved as a flow that repeats it without a model next time.

• Exit 0 = done (the output lists every step). Exit 2 = handed back: it says why, what it did, the page

it's on and the elements it was choosing between. Continue from there yourself (chrome-relay snapshot, then click or fill); don't rerun the same do hoping for a different result. It hands back on purpose before clicking a consequential button the goal doesn't name (delete, send, pay, deploy, ...): if the person asked for exactly that, rerun with --allow <verb>; never --allow '*' on your own.

• One goal per run, in the tab you used last (--tab <id> for another), or a new page with `--url <url>

[--profile <email>]. Same CHROME_RELAY_SESSION` as the commands that opened it.

• chrome-relay decider says what it decides with (Jev, Haiku through Claude Code, or none). Setting a key is the

person's job; never run decider jev yourself.

Signing in with 1Password

If the person has set it up, you sign in with logins from the 1Password vaults they allowed, without ever seeing a secret. See what's there (vaults, titles, websites, usernames, and whether each has a password, one-time code or passkey; never values):

chrome-relay vault

Fill a field with a secret reference instead of a value. The relay types the real value into the page:

why="Check why last night's deploy workflow failed"
chrome-relay fill @e2 "op://Shared with Chrome Relay/GitHub/username" --why "$why"
chrome-relay fill @e3 "op://Shared with Chrome Relay/GitHub/password" --why "$why" # password fields only
chrome-relay click @e4
chrome-relay fill @e7 "op://Shared with Chrome Relay/GitHub/otp" --why "$why" # the current 2-step code (TOTP), computed when typed