Chrome Relay

Setup

1. Chrome extension
2. CLI:
   sh

   pnpm add -g chrome-relay
   chrome-relay install
   chrome-relay doctor

chrome-relay --version

Tool surface

tabs

tabId

navigate <url>

--new

--active

--tab <id>

read --tab <id> -i

ax --tab <id>

read

backendDOMNodeId

click <selector> --tab <id>

Input.dispatchMouseEvent

pointerType: "mouse"

click --x N --y N --tab <id>

click-ax --node <backendDOMNodeId> --tab <id>

ax

hover [selector | --x --y] --tab <id>

:hover

fill <selector> <value> --tab <id>

<input>

<textarea>

<select>

type <text> --tab <id> [-s <selector>]

Input.insertText

keys <chord> --tab <id>

Enter

Tab

Escape

Cmd+K

Shift+ArrowDown

js <code> --tab <id>

Runtime.evaluate

return

await

screenshot --tab <id> -o <path>

--full

--max-edge N

screencast --tab <id> -o <path>

network --tab <id>

network read --request-id <id>

console --tab <id>

console.log/warn/error

viewport

workspace

group

switch <tabId>

close <tabIds...>

self-reload

release-notes --since <ver>

update

call <tool> [json]

Picking the right text tool

<input>

<textarea>

<select>

fill

[contenteditable]

role="textbox"

type

keys

type

keys ArrowDown

keys Enter

js

Workflow

1. Find the tab —

   chrome-relay tabs

2. Open the page —

   chrome-relay navigate "https://example.com" --new

   (background by default)
3. Read structure — pipe to a file, don't dump 100KB into context:
   sh

   chrome-relay read --tab 1234 -i > /tmp/page.json
   jq '.elements[] | select(.text | test("Compose"; "i"))' /tmp/page.json

   For dense apps (LinkedIn, Notion), prefer

   ax

   — way smaller payload.
4. Act on the selectors:
   sh

   chrome-relay click "<selector>" --tab 1234
   chrome-relay fill "<selector>" "value" --tab 1234
   chrome-relay type "tweet body" --tab 1234 -s "[data-testid=tweetTextarea_0]"
   chrome-relay keys "Enter" --tab 1234

5. Drop to

   js

   when the DOM doesn't expose what you need:
   sh

   chrome-relay js --tab 1234 "return document.title"
   chrome-relay js --tab 1234 "const r = await fetch('/api/me'); return await r.json()"

6. Capture proof —

   chrome-relay screenshot --tab 1234 -o /tmp/evidence.png

Top gotchas

1. type

   appends — it inserts at the caret. If the input had a value (autosaved draft, default text), clear it first via

   js

   or

   keys

   (Cmd+A then Backspace).
2. Coords go stale fast — read

   getBoundingClientRect

   , scroll/reflow, then click → you hit the wrong element. For autocomplete popups especially, use keyboard nav, not coord clicks.
3. Click "succeeded" but nothing happened — first diagnostic:

   document.elementFromPoint(x, y)

   . If it returns a wrapper or form background, your coords are wrong. If it returns the right element but state didn't change, you're likely on chrome-relay <0.5.20 — upgrade.

Operational guidance

• Don't give up early. A failing click is information, not a stop signal. Attach a document-level listener with

  capture:true

  and watch what fires:
  sh

  chrome-relay js --tab 1234 "
    ['pointerdown','mousedown','click'].forEach(t =>
      document.addEventListener(t, e => console.log(t, e.target.tagName, e.target.className), {capture:true})
    );
    return 'listening'
  "
  # do the action, then:
  chrome-relay console --tab 1234

• Don't echo secrets. When extracting tokens / API keys via

  js

  , write the result directly to a file. Never

  echo $TOKEN

  or interpolate into shell strings — it ends up in scrollback, logs, and tool transcripts.
• Capture before irreversible actions (form submit, send message, account change). Save the screenshot path.

Guardrails

• Pipe

  read -i

  to a file and grep/jq it. Don't paste the full element map into chat.
• If a flag is unclear,

  chrome-relay <command> --help

  is authoritative — these docs lag.