use-agent-browser

use-agent-browser

Overview and Boundaries

agent-browser is a Chrome/CDP-based browser automation CLI (the same-named MCP form is the agent_browser_* tool family), which drives page operations through accessibility snapshots and @eN element references.
This skill specifies execution discipline, failure triage, and evidence standards; the final authority for command details is the content bundled with the CLI itself, so before starting, run agent-browser skills get core(the content ships with the installed version and never goes stale).
Tool priority: agent-browser is the first-class tool for browser acceptance; only when it is truly unavailable should you fall back to Chrome DevTools-type MCP, and keep the failure path in the record.
Boundaries: does not handle batch cleanup of leftover processes (follow the cleanup-agent-team-node-processes skill, if installed); does not handle building a visual regression testing framework (headless pixel comparison schemes have been disproven on animation-heavy pages).

Progressive Loading Map (references)

SKILL.md only retains entry-point discipline; the following reference files are loaded on demand, all located within this skill directory:

File	Content	When to Load
`references/command-cookbook.md`	Command manual: installation self-check, standard workflow, session/profile and MCP toolset selection, Windows takeover and fallback recipes, waiting and debugging recipes, controlled acceptance mock, quick reference table	When unsure how to write commands before executing them, or when you need recipe templates
`references/verification-templates.md`	Acceptance and report templates: visual verification report, eight elements of production acceptance, streaming four states, smoke→matrix→fullscreen cadence, three-layer acceptance chain, verification criteria, evidence supersede, artifact registration, screenshot naming	When you need to produce an acceptance record or write a report
`references/cases-windows-startup.md`	Case collection: exit code 3, detached diagnostics, CDP takeover, headless fallback, Chrome connector, typed MCP timeout, instance availability pre-check	When triaging Windows startup/connection failures
`references/cases-evidence-misjudgment.md`	Case collection: loaded≠visual, screenshot timing, snapshot≠screenshot, READY/200/protection page, console as the first signal, streaming partial success, single-sample extrapolation, archived missing images, URL rewriting, mobile viewport gating	When self-checking evidence strength before drawing an acceptance conclusion
`references/cases-waiting-animation.md`	Case collection: headless CPU bomb, animation freeze ineffective, load unreliable, waiting strategy table, SSR diagnostic chain, WebGL illusion	When the page under test contains animations/SSR/WebGL
`references/cases-shell-tooling.md`	Case collection: PowerShell eval dirty files, @eN quotes,`--` pass-through, set viewport command name, wait syntax timeliness, parameter fixation, hash routing entry form	When shell-layer syntax is in doubt or eval fails
`references/cases-process-governance.md`	Case collection: process topology and prewarm pool, loop batch deadlock, registration red lines, cleanup boundaries, ownership misjudgment, config≠launch, tri-state ownership	When involving process ownership, leftovers, or cleanup decisions

Non-Skippable Discipline

Read core first, then act. On first use or after an upgrade, first agent-browser skills get core; when the task goes beyond ordinary web pages (Electron apps, Slack, exploratory testing), as needed agent-browser skills get electron|slack|dogfood。
Use URLs as-is. For user-provided URLs, stripping suffixes, encoding, rewriting, or "optimizing" on your own is prohibited; after an exact URL fails, record the HTTP status and routing evidence, then propose an evidence-constrained alternative path.
Self-check first after installation. agent-browser install(On Linux, append --with-deps）；agent-browser doctor to proceed to acceptance;agent-browser upgrade to handle version drift.
Evidence goes to the temporary directory. Screenshots are written by default to the system temporary directory and named with a task prefix and source (dev / preview / production), not into the repository; when versioned evidence is truly needed, copy it into the corresponding evidence directory after user confirmation and explain it separately.
If the same method fails ≥2 times, switch to a fundamentally different approach, advance along the startup failure triage chain, and do not retry repeatedly in place.
Do not package partial evidence as complete success. Report streaming responses, login, cancellation, and other chains item by item according to status; HTTP 200, READY, and load statistics must not substitute for a complete-chain conclusion.

Standard workflow

agent-browser open <URL>
agent-browser wait --load networkidle
agent-browser get title                # 防 404：读标题确认页面真实加载
agent-browser snapshot -i              # 交互快照，取 @eN 元素引用
agent-browser click @e1                # 或 fill @e2 "text"、select、press
agent-browser wait 1000                # 固定等待用裸毫秒参数，不是 --time
agent-browser screenshot <task-prefix>-<step>.png
agent-browser eval "简单表达式"
agent-browser close                    # 任务结束必须收口

After each navigation: wait → read the title → then operate; do not perform consecutive blind operations.
Visual determination must scroll the target element into the viewport before taking a screenshot and actually viewing it;naturalWidth, and resource load counts only prove loading status.
For command details and recipe templates, see references/command-cookbook.md。

Sessions, profiles, and login state

Named session:--session <name>; restore state:--session <name> --restore; stable session ID:agent-browser session id --scope worktree --prefix <app>。
Reuse user Chrome profile:--profile <name>(involves user data; obtain authorization first).
Chrome connector mode (user's local Chrome + extension + Native Messaging): when Chrome is not running, the connector returns "Browser is not available"—wait for the user to open Chrome or explicitly authorize startup; do not start the user's browser without permission.

Windows-specific rules

Automatic startup failure (exit code 3 / no DevToolsActivePort): append --args "--no-sandbox" to the session and retry once.
Preferred takeover path (local Chrome visual acceptance): explicitly launch local Chrome (separate temporary profile + --remote-debugging-port=<port>), then agent-browser --cdp <port> take over. This can prove the browser source, does not touch the user's daily profile, and allows a visible window; the cost is that this Chrome process and profile must be registered and cleaned up.
headless fallback: manually chrome --headless=new --remote-debugging-port=<port> + agent-browser connect <port>. Animation-heavy pages (GSAP / Three.js / ECharts looping animations) must not use headless—JS-driven animations are not frozen by reducedMotion , and headless mode running at the highest frame rate will max out the CPU.
Command name: setting the viewport is set viewport <w> <h>(with a space, not set-viewport); acceptance uses a unified desktop viewport, and responsive hidden containers (hidden md:flex , etc.) simply do not render in narrow viewports.
PowerShell eval discipline: do not stuff complex scripts such as ||, arrow functions, or object literals into the command-line string (they will be split incorrectly and generate 0-byte dirty files). Instead use: simple expressions, fine-grained commands such asget count / get attr , or the stdin / base64 parameter-passing entry points provided by the CLI; after execution, run git status to recheck and precisely delete the temporary files generated this time.@e15 References of the form
Startup parameter passthrough: when passing parameters to the dev server under test, confirm -- Is it correctly forwarded by the package manager (there has been an incident where pnpm --filter <pkg> dev -- --port 3100 passed the literal -- to Nuxt), and incorrect startup parameters will directly contaminate the browser acceptance conclusion.

For case-by-case details see references/cases-windows-startup.md and references/cases-shell-tooling.md。

startup failure triage (separated diagnosis)

First distinguish two types of states：doctor Launch test failure, daemon EOF, typed MCP open unresponsive only proves that the create/takeover path is abnormal, not that existing sessions are unavailable.
Minimal probe to verify existing sessions：get url, element count,scrollintoview、screenshot—if the probe passes, continue using the existing session to complete the task.
Degradation chain(execute in order, record evidence for each failed step): append --no-sandbox → CDP takeover (--cdp <port>) → manual headless=new + connect → switch to a Chrome DevTools class MCP and retain the agent-browser failure path.
daemon EOF handling: first doctor / close / restart the session; a subcommand occasionally succeeding after EOF does not count as a reliable process and must not be recorded as the standard path.
typed MCP unresponsive for a long time(a 300-second timeout has been empirically observed): after recording the failure path, immediately switch evidence sources and do not wait again.

Waiting and stability strategy

Scenario	Strategy
Ordinary page navigation	`wait --load networkidle` + read title
Explicit element appears	`wait_for_selector`; use fixed intervals with `wait 1000`
Animation / large-screen pages	first `set viewport 1920 1080`, then wait for loading to disappear and the entrance animation to finish naturally (first screen on the order of 8s); use `eval` polling the DOM numeric sequence to judge stability, do not guess based on screenshot timing
JS-driven animation	Prohibit `progress(1)`, manually overriding style to force a reset (it will be overwritten again on the next tick); after waiting for natural completion, `pause()` / stop frames
SSR page eval	Client variables can only be obtained after hydration is complete; when "no errors and no hydration" use `!!document.querySelector('#__nuxt').__vue_app__` to determine mounting, dynamic `import(entrySrc + '?v=diag')` to capture the real module error

Snapshots and screenshots complement each other in determination:opacity: 0 DOM that is visually hidden, such as , will still enter the accessibility snapshot; use snapshots for structural determination and screenshots for visual determination, and when the two are inconsistent, record them separately.
WebGL canvas: under headless it may be black or read transparent pixels, which is an environment limitation; screenshot pixel sampling is stronger than readPixels。

For complete diagnostic cases of animation and SSR see references/cases-waiting-animation.md。

Screenshot and acceptance evidence specification

Minimal visual evidence = target element scrolled into viewport + screenshot + the executor actually viewing the screenshot. Full-page thumbnails and load statistics can only serve as auxiliary evidence.
Eight elements of production acceptance records: browser executable, CDP port/session type, exact URL, screenshot path, deployment ID, commit SHA, load statistics, visual conclusion. If one item is missing, complete it before drawing a conclusion.
Streaming/long-task four states: request sent / intermediate output rendered / cancellation successful / fully completed—report each item according to evidence, and do not package the previous item as the next one.
Evidence recency: After the new acceptance is complete, mark the old evidence as superseded in the artifact, to avoid outdated evidence misleading subsequent execution.
console is the first signal: For visual symptoms, check console first; "silent degradation" such as ECharts only gives console hints (e.g., series not registered), which cannot be seen from screenshot pixels.

For templates see references/verification-templates.md; for misjudgment cases see references/cases-evidence-misjudgment.md。

Network and debugging

Request list, console, page errors: prefer the CLI's network / console / errors subcommands;errors --clear clear and then re-verify.
When console capture is unreliable or import chain localization is needed: playwright-core connectOverCDP connects directly to CDP, listens on Network.requestWillBeSent to get initiator.url to locate the real importer, avoiding fixing the wrong dependency.
API verification records method, URL, status, and key response fields; only capture requests triggered in this round. For destructive APIs, data-writing APIs, and login-state operations, first confirm the target environment and scope of impact.

Process and residual cleanup

At task end execute agent-browser close; before finishing, re-check: debug port, browser PID, temporary profile directory, temporary screenshots.
Launch one independent Chromium per instance:batch launching in a loop is prohibited, to avoid frequently launching GUI-type processes during the user's development hours.
Chrome instances taken over on this machine must be registered with --remote-debugging-port、user-data-dir, PID, and shutdown policy; only instances that you started or are authorized to close may be closed.
Auditing and cleaning up suspected residual processes follows the cleanup-agent-team-node-processes skill (if installed); resident MCP services are not cleanup targets.

For the basis of ownership determination and typical cases see references/cases-process-governance.md。

Common error comparison table

Incorrect practice	Correction method
Rewriting the user-provided URL before visiting	Open as-is; after failure, propose alternative paths based on evidence
Using only `naturalWidth` to determine visual pass	scrollintoview + viewport screenshot + actual viewing
Concluding the page has a problem just because doctor fails	Separate diagnosis: minimal probe to verify the existing session
Retrying the same launch command more than 5 times	After ≥2 failures, switch to the fallback chain
Assembling complex inline eval in PowerShell	Simple commands or stdin / base64; re-check with git status afterward
Drawing conclusions from screenshots without fixing the viewport or waiting for animations	First set viewport, then execute according to the wait strategy table
Running pixel comparison in headless mode for animated large screens	Force a visible browser; smoke first, then matrix
Treating Vercel READY / preview domain protection pages as application evidence	Use the production domain + actual browser operation as evidence
Not closing at task end and not re-checking ports	close + re-check port/PID/profile/temporary screenshots
Writing screenshots directly into the repository	Default to a temporary directory; versioning requires user confirmation

Completion self-check list

Executed according to the version-matching content of agent-browser skills get core .
Every navigation has a wait + title confirmation, with no blind operations.
Visual conclusions have a viewport screenshot of the target element, and have been actually viewed.
Startup failure followed the triage chain, and each step was recorded.
The production acceptance record has all eight required elements.
The session has been closed, and the port/PID/profile/temporary screenshots have been rechecked.
The record distinguishes facts, inferences, and unverified items.

Related files

This skill is a pure documentation skill with no accompanying scripts. The reference layer is the references/ directory (command manual, acceptance template, five sets of practical case collections); for loading timing, see the "Progressive Loading Map". For command syntax, the output of agent-browser skills get core is the final authority; for residual process governance, see the cleanup-agent-team-node-processes skill (if installed).