Quickstart

The snapshot → ref → act loop, end to end, with real output.

Everything an agent does with Chrome Relay is one loop: look at the page, act on what you saw, look again. This page runs it once, for real.

Open a page in the background

chrome-relay navigate "https://news.ycombinator.com" --new

{ "tabId": 460154464, "windowId": 460153891 }

--new opens a background tab — the user's focus is never stolen. Keep the tabId.

Look at the page

chrome-relay snapshot --tab 460154464 -i

Page: Hacker News
URL: https://news.ycombinator.com/
Tab: 460154464

- link "Hacker News" [ref=e4]
- link "new" [ref=e5]
- link "past" [ref=e7]
- cell "1." [ref=e16]
- cell "MiMo Code Is Now Released and Open-Source (xiaomi.com)" [ref=e18]
  - link "MiMo Code Is Now Released and Open-Source" [ref=e19]
  - link "xiaomi.com" [ref=e20]
...

-i prints only actionable elements. The whole front page is ~14 KB of this. Every [ref=eN] is a handle you can act on.

Act on a ref

chrome-relay click @e5

{ "clicked": true, "x": 250, "y": 20, "ref": "e5", "tabId": 460154464 }

No --tab. No CSS selector. The ref knows which tab it came from — it acts there even if you (the human) are reading a different tab right now.

Fill, type, press

chrome-relay fill @e41 "search term"     # inputs, textareas, selects — atomic write
chrome-relay type "hello" -s @e23        # contenteditable / Lexical / ProseMirror
chrome-relay keys Enter --tab 460154464  # chords: Cmd+K, Shift+ArrowDown, Escape

Look again

After anything that changes the page, re-snapshot:

chrome-relay snapshot --tab 460154464 -i

Refs survive same-page DOM churn (a toast appearing won't kill them — there's a heal step that re-finds moved nodes). They die on navigation, on purpose. If you act on a dead one:

{ "relayError": { "code": "stale_ref",
  "message": "chrome_click_element: @e19 is not a known ref (...). Re-run `chrome-relay snapshot` and use a fresh ref." } }

The fix is always the same: snapshot again. See Refs for the full lifetime rules.

Capture proof

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

Works on background tabs without activating them.

The loop, named

snapshot -i  →  click/fill @ref  →  snapshot -i  →  ...

That's the whole interface. Three more things worth knowing before you go deep: