Skip to content

usage.md

Latest commit

 

History

History
91 lines (69 loc) · 3.64 KB

usage.md

File metadata and controls

91 lines (69 loc) · 3.64 KB
Raw

User guide

All commands use scripts/cdp.mjs. A target is the unique target ID prefix printed by list.

Commands

Command Purpose
list List open pages and their target prefixes
open [url] Open a new tab in Agent Chrome
snap <target> Print a compact accessibility-tree snapshot
html <target> [selector] Print full-page or selected-element HTML
eval <target> <expression> Evaluate JavaScript in the page
nav <target> <url> Navigate and wait for the page to load
shot <target> [file] Capture the current viewport
click <target> <selector> Click an element with a CSS selector
clickxy <target> <x> <y> Click using CSS-pixel coordinates
type <target> <text> Insert text at the current focus
net <target> Show resource timing entries
loadall <target> <selector> [ms] Repeatedly click a load-more control
evalraw <target> <method> [json] Send a raw CDP method
stop [target] Stop one or all per-tab daemons; the browser remains running

Example:

scripts/cdp.mjs list
scripts/cdp.mjs snap 1A2B3C4D
scripts/cdp.mjs eval 1A2B3C4D 'document.title'
scripts/cdp.mjs shot 1A2B3C4D page.png

Use enough target characters to identify exactly one page. The CLI rejects ambiguous prefixes.

Persistent profile behavior

On the first managed command, Agent Chrome selects the last-used regular Chrome profile and creates one local copy. It excludes volatile caches, browsing history, saved-password databases, and autofill databases. Cookies, site storage, IndexedDB, extensions, and profile preferences remain available.

The copy is independent after initialization:

  • New Agent Chrome logins remain in Agent Chrome.
  • Changes in regular Chrome are not synced into Agent Chrome.
  • Changes in Agent Chrome are not synced back into regular Chrome.
  • Closing the browser does not reset or recopy the profile.

If the profile marker is missing but the persistent profile is valid, Agent Chrome adopts that profile instead of overwriting it. If existing data cannot be recognized safely, startup stops with an error and leaves the data untouched.

Screenshots and coordinates

Screenshots are saved at native resolution. CDP input commands use CSS pixels:

CSS pixels = screenshot image pixels / device pixel ratio

The shot command prints the current device pixel ratio and a conversion hint.

Sandboxed agents

An agent sandbox must permit loopback TCP access to 127.0.0.1. An EPERM error mentioning 127.0.0.1 is a sandbox permission denial, not a Chrome configuration error. Approve the narrow scripts/cdp.mjs command when your agent requests permission.

Security

CDP can read and modify everything available to the Agent Chrome profile. The skill instructions require explicit user approval before an agent inspects, debugs, or interacts with browser pages. Direct CLI use is outside that agent approval layer.

Agent Chrome binds its debugging endpoint to 127.0.0.1, but starts Chrome with --remote-allow-origins=* for CDP client compatibility. Any untrusted local process may attempt to attach to the fixed debugging port. Use Agent Chrome only on a trusted single-user machine, avoid especially sensitive accounts, and stop the dedicated browser when it is not needed.

The per-tab daemon discovery files contain random authentication tokens and are created with user-only permissions. These tokens protect daemon IPC; they do not restrict direct access to Chrome's debugging port.

Agent Chrome does not upload browser data. Pages opened in Chrome and any scripts you deliberately evaluate can, of course, communicate with their own network services.