chrome-agent

Web tasks that compile.

A browser doesn't report back. The click lands on a cookie banner, the form drops what you typed, the page navigates away mid-action, and the tool returns success anyway. Everything the agent does next is built on that.

chrome-agent reads the page back after every action and answers which one it was: the change held, something else took the click, or nothing could be observed. One word, in JSON, to branch on.

One 3 MB Rust binary over CDP. No Node, no Playwright, no daemon.

Independent project. Not affiliated with, endorsed by, or sponsored by Google or the Chrome team.

Install

npx skills add sderosiaux/chrome-agent   # skill file + binary, for coding agents
npm install -g chrome-agent              # prebuilt binary
cargo install chrome-agent               # from source

Linux builds are static musl binaries, so they run on any distro without a glibc version to match.

60-second quickstart

# Navigate and read the page as an accessibility tree with stable uids
chrome-agent goto https://example.com --inspect
# uid=n9  heading "Example Domain" level=1
# uid=n12 link "More information..."

# Act by uid, by CSS selector, or by coordinates
chrome-agent click n12 --inspect
chrome-agent click --selector "button.submit"
chrome-agent click --xy 100,200

# Fill and check what the page kept
chrome-agent fill --uid n20 "user@test.com"
chrome-agent assert value --uid n20 --equals "user@test.com"

# Get content, not markup
chrome-agent read
chrome-agent extract --limit 30
chrome-agent text --selector "main" --truncate 500

# Everything is available as JSON
chrome-agent --json eval "document.title"

Chrome stays alive between invocations, so a command costs a connection, not a browser launch. Use --browser <name> to give each parallel agent its own Chrome and its own session state.

Commands

Navigation and session

Reading the page

Acting

Checking

Monitoring and advanced

Global flags

--browser <name>         Named browser profile (default: "default")
--page <name>            Named tab (default: "default")
--connect <auto|url>     Attach to a running Chrome (a value is required)
--proxy-server <url>     Proxy a managed Chrome (http(s), socks4/5; explicit port)
--headed                 Show the browser window (default: headless)
--stealth                Anti-detection CDP patches
--copy-cookies           Use cookies from your real Chrome profile
--chrome-arg <flag>      Extra flag for the Chrome that gets launched (repeatable)
--timeout <seconds>      Command timeout (default: 30)
--max-depth <N>          Limit inspect depth
--verdict <mode>         auto (default) reads the page back; off reports the action only
--budget <chars>         Cap the change report (default 1200; 0 = uncapped)
--on-intercept <mode>    dispatch (default), guard, or refuse
--ignore-https-errors    Accept self-signed certs
--dialog <mode>          JS dialog policy: accept (default), dismiss, or manual
--dialog-text <text>     Text submitted for prompt() dialogs under --dialog accept
--json                   Structured JSON output

Global flags parse on either side of the verb. --timeout and --max-depth are the exceptions: commands that declare their own (wait, download, anything with --inspect) take them after the verb, everywhere else they go before it. --proxy-server and --chrome-arg are launch-only and fixed for the life of a named browser — a later command that omits them inherits them, one that names different values is refused. Close or purge the browser to change them.

Concepts

uids

Element ids come from Chrome's backendNodeId, printed as n82. They stay valid across inspects of the same page, so an agent can inspect once and act several times. A navigation reassigns them all — re-inspect after goto, back, or a click that changes route. goto clears the uid map but keeps the snapshot, so diff reports document_changed instead of erroring. Commands that resolve a uid need one from a stored snapshot: inspect before assert value --uid or download --uid.

Verdicts: did the page comply?

ok:true means the command ran, not that the page complied. Every mutating action carries a verdict, a verdict_reason and a next — one token from a closed set of six, so a caller can branch without parsing prose.

Never repeat an action on unknown: the first one may already have landed.

Pointer actions also report delivery (target_hit, intercepted, off_target, not_settled, js, not_probed) from a hit test at the coordinate about to be dispatched. no_effect is only emitted behind target_hit. --on-intercept decides what happens when something else is in the way:

Two blind spots: the read-back window is a fixed 60 ms (reported as observed_after_ms, so a validator firing at 400 ms is outside it — use wait then assert value), and canvas, WebGL and CSS-only effects are invisible to the accessibility tree.

landed and serving: where you ended up, and what answered

goto reports landed{requested,final,redirected,http_status,serving}. A fragment-only or trailing-slash change is not a redirect. http_status is the final hop's status, read from the Navigation Timing API so --stealth is untouched.

serving never changes ok or the exit code. Branch on serving, not on ok:

Exit codes

0 success · 1 error, including a bad flag · 2 a claim this tool made did not hold · 130 Ctrl+C. 2 is an assertion, or a macro guard — the two things this tool promises about a page — so CI can tell "the page is wrong" from "the tool broke".

chrome-agent fill --selector "#coupon" "SAVE10"
chrome-agent assert value --selector "#coupon" --equals "SAVE10"
chrome-agent assert state --selector "#terms" --checked
chrome-agent assert exists --selector ".result" --min 1

assert is a read: no change report, no verdict, and it never clicks. --matches is a Rust regex (\d/\w/\s are ASCII-only, no \p{...}; (?i) works). Inside batch and pipe an assertion has no exit code of its own — it is ok:false with an assertion object, and a batch that stopped on it exits 1, not 2.

Pipe and batch mode

One process, one connection, one JSON line per response, and uids stay stable across the whole sequence — which is the reason to reach for it. The speed-up is real and small: pipe removes about 12 ms of per-command overhead, worth 1.5x on a stream of reads (nine commands, 352 ms → 228 ms) and 1.1x on a stream of fills and clicks (2029 ms → 1908 ms), where the settle window and the tree re-read pipe does not touch are most of the cost. Measured on 2026-08-30, M4 Max, Chrome 152, median of 9 runs; reproduce with ./scripts/measure-pipe.sh, record in docs/design/pipe-latency.md.

echo '{"cmd":"goto","url":"https://example.com","inspect":true}
{"cmd":"click","uid":"n12","inspect":true}
{"cmd":"read"}' | chrome-agent pipe

batch takes a JSON array on stdin instead and is otherwise the same dispatcher, and answers with one response object rather than one line per command. Pass --json to get that object as JSON; without it the CLI prints one text line per entry.

The CLI batch process exits 1 when --stop-on-error cut the run short — never 2, which stays reserved for a claim that did not hold: the process is reporting that the batch stopped, not saying anything about the page. Without --stop-on-error it ran every command it was given and exits 0 even when one of them failed: read ok, on the batch and on each result.

Iframes

frame binds eval and inspect to an iframe. The binding lives on the connection, so it only survives inside one pipe or batch process:

printf '%s\n' \
  '{"cmd":"frame","target":"#payment-iframe"}' \
  '{"cmd":"inspect"}' \
  '{"cmd":"fill","uid":"n42","value":"4242424242424242"}' \
  '{"cmd":"frame","target":"main"}' | chrome-agent pipe

Name the iframe precisely (iframe[src*="checkout"]); a bare iframe matches the first one in DOM order, often an empty ad slot. frame does not scope --selector targeting — inspect after the switch and act by uid, which resolves across frames. The isolated world sees the frame's DOM but not its main-world JS variables.

--stealth vs --connect

--stealth applies 7 CDP-level patches (Page.addScriptToEvaluateOnNewDocument), not Chrome flags: navigator.webdriver, chrome.runtime, the Permissions API, the WebGL renderer, the User-Agent, an input coordinate leak, and never calling Runtime.enable.

Heavy protection fingerprints the Chromium binary itself, so the only route is a real installed Chrome. --copy-cookies copies the cookie database from your Chrome profile; both instances use the same Keychain, so encrypted cookies work, and your real Chrome is not affected.

google-chrome --remote-debugging-port=9222 &
chrome-agent --connect http://127.0.0.1:9222 goto https://www.leboncoin.fr --inspect
chrome-agent --stealth --copy-cookies goto x.com/home --inspect
chrome-agent --copy-cookies goto github.com/notifications --inspect

Macros

A macro is a path that already worked once, kept under a name with the postconditions observed on that success. macro run checks every step's guards and stops at the first that does not hold. There is no repair and no retry.

chrome-agent macro record cancel --from-recording session.jsonl
chrome-agent macro run cancel --var email=ada@example.com

Guards are delivery: target_hit, the verdict word, value.verbatim, and a url_matches built from the path — never the change counters, a uid, or a duration. A step aimed by uid is recorded by role and accessible name, or refused. Secret fields become declared parameters, never file content.

A guard that was checked and did not hold exits 2, the same code as a failed assertion: it is the same kind of claim. The report carries stopped_by: "guard" along with which guard, what it expected and what was there. A run that stopped for any other reason — the step itself failed, the page could not be read, the macro file is missing — exits 1, with stopped_by: "error".

Files on disk

Screenshots, PDFs and downloads land under ~/.chrome-agent/tmp (or your --out path) with 0600 permissions, and the path is printed on stdout. Binary bytes never reach stdout.

chrome-agent download https://app.com/reports/2024.csv --out ./2024.csv
chrome-agent download --selector "#export" --out ./export.csv
chrome-agent pdf --filename invoice.pdf --background
chrome-agent screenshot --uid n42

Read downloaded, not ok. A click that was delivered and produced no file answers ok:true with downloaded:false: a click is not undoable, and an error there invites a second real one. --timeout bounds the whole window; --max-bytes cancels a transfer that goes past it.

Device emulation

chrome-agent --page mobile emulate device --label "checkout phone" \
  --width 412 --height 915 --dpr 2.625 --mobile --touch
chrome-agent --page mobile emulate status
chrome-agent --page mobile emulate reset

Metrics belong to one named page and are reapplied on each connection, because Chrome drops every override when the CDP session that set it detaches. Under --touch, click and check dispatch touch taps; dblclick, hover and drag stay mouse. Values are explicit: device preset catalogs live in the DevTools frontend, not in CDP.

WebMCP

Pages can register tools on document.modelContext (W3C WICG WebMCP). The protocol defines no outputSchema, so webmcp call reports what the tool declared next to what the page measurably did, using the same verdict machinery as any other action.

chrome-agent webmcp list
chrome-agent inspect
chrome-agent webmcp call add_to_cart --args '{"item":"Espresso Blend"}'

Most installed Chrome builds have no native WebMCP. Test against the real API with --chrome-arg --enable-features=WebMCP,WebMCPTesting, or against a page shipping a polyfill. Under a frame binding the response carries frame_scoped: true: a tool registered by the frame's own main-world script is invisible from the isolated world.

Troubleshooting

Comparison

extract finds repeating records structurally with MDR/DEPTA-style heuristics (sibling similarity, content heterogeneity, text-to-link ratio) instead of asking a model to read the DOM. On the Hacker News front page it hands over 30 stories as records in 1,571 tokens against 5,652 for the accessibility tree and 8,727 for raw HTML (scripts/measure.sh). The gap depends on the page: on a blog archive that is nothing but a list, the two are close.

When not to use it

• You need a test framework — use Playwright.
• You need an MCP server — there is none here.
• You need a browser fleet, a proxy pool or CAPTCHA solving — Browserbase, Steel, Browserless.
• You need Firefox or Safari — this speaks CDP, so Chrome only.
• You want a supported product — this is one person's project.

Using it from an agent

npx skills add sderosiaux/chrome-agent installs a SKILL.md. Otherwise chrome-agent --help embeds a full LLM usage guide, and every error carries a hint naming the next action. Claude Code permissions: {"permissions": {"allow": ["Bash(chrome-agent *)"]}}.

chrome-agent (3 MB Rust binary, ~28.2K lines of Rust in src/)
    | CDP over WebSocket
    v
Chrome (headless by default, no Node.js, no runtime)

Design records live in docs/design/README.md.

License

MIT