Accessibility refs instead of guessed selectors
An interactive snapshot returns controls with refs such as @e1. Choose the control by its role and name, then use the returned ref rather than inventing a CSS selector from a screenshot.
agent-browser
agent-browser gives coding agents a terminal interface to Chrome or Chromium. Compact snapshots attach refs to controls, so an agent can locate a button, act on the current page, and check the resulting state across successive commands.
Check one interface path
A filter-count check tests whether snapshots and element references remain usable after a state change. It gives a concrete baseline for later multi-step browser work.
Test URL, initial filter state, target filter value, expected count, and configured CLI session.
Copy the request into a new Floatboat conversation and provide the required material.
Download FloatboatYour request for Floatboat
Preview and copy the request. It is not sent automatically from this page.
Reference: agent-browser https://github.com/vercel-labs/agent-browser Read the original documentation and check the current environment and dependencies. Propose any new installation or tool connection before proceeding. My task: Use agent-browser on my local test URL. Read the current core instructions, take a snapshot, exercise the filter I specify, and compare visible results with the expected count. Re-snapshot after changes. Expected deliverable: An action sequence with snapshots, observed state, and a reproducible discrepancy if any. Include failed steps and unresolved questions when evidence is insufficient.
About agent-browser
agent-browser is a Vercel Labs CLI for coding agents. The host chooses what to do; the CLI executes browser operations over CDP. A typical loop opens a page, reads an accessibility snapshot with compact @eN refs, acts on a current ref, and observes the changed state. It does not supply a second model that plans the task independently.
The official agent-browser Skill is a discovery stub. It directs the host to agent-browser skills get core so detailed instructions come from the installed CLI rather than a copied file that may describe another release. Specialized guides cover exploratory QA, Electron applications, and other environments; they are not all prerequisites for an ordinary website task.
The project also documents MCP and local or hosted browser integrations. Choose the provider and session deliberately when account state matters. In Floatboat, the terminal path corresponds to the one documented for Cursor and Codex, after CLI and browser setup. Apache-2.0 covers the CLI source; hosted providers, model processing, and any service allowance remain separate.
Locate Controls, Preserve State, Refresh Refs
Snapshots describe the current document, while the selected browser session carries state between commands. Treat those as different lifetimes: the session can continue even when an element ref must be replaced after navigation or a page update.
Instructions served by the installed CLI
The core guide and its references match the local release. Load only the specialized guide needed for the task, such as dogfood for exploratory QA or electron for a desktop application.
State across shell calls
A page can remain open across observations and actions. The active profile or provider determines account state; keeping a session alive does not make an earlier element ref valid after a rerender.
Use agent-browser Beside Repository Work
The CLI is useful when a coding host needs small browser steps with explicit evidence. New UI checks, account reports, stale-ref diagnosis, and exploratory QA produce different handoffs; choose the relevant guide before increasing the investigation’s scope.
Check a newly built screen
Provide a development URL, a control label, and the state expected after one action, such as an expanded details panel. Use the snapshot ref to perform the action and read the changed page. Add a screenshot if the assertion concerns layout; an accessible label alone does not establish alignment or responsive behavior.
Read a signed-in dashboard
Choose an approved account session and specify the date range and three report fields. Read those values with the current CLI guidance and return the source page, selected range, and missing sections. If the session has expired, report the login state instead of treating an empty page as a zero-valued report.
Diagnose a stale ref
When a click fails after a filter refresh or navigation, take another interactive snapshot and locate the control again. Compare the new role, name, and state before retrying. The useful result is the failing transition and a corrected sequence, rather than a list of repeated commands against the old ref.
Prepare an exploratory QA handoff
Load the installed dogfood guide for a bounded test area, such as account settings in a staging application. Investigate distinct paths and retain reproduction steps, expected versus observed behavior, and visual evidence where useful. Separate a reproducible defect from an unconfirmed suspicion so a developer can prioritize the report.
Prepare the CLI and Test Target
Use the installed version’s guide for commands and browser setup. The walkthrough assumes a shell-capable host and a non-sensitive test page; existing login or cloud providers are optional choices that require their own session configuration.
CLI and browser runtime
The official Skill documents npm i -g agent-browser followed by agent-browser install. Prepare required system dependencies for the platform, or choose a documented provider instead of assuming the binary alone supplies every browser environment.
Version-matched core guide
Run agent-browser skills get core before browser commands. Its references explain current wait, session, authentication, and output options; use skills list to discover additional guides when needed.
A checkable UI assertion
Supply the URL, exact target label, expected post-action state, and any approved account or test data. A visual assertion also needs an agreed viewport and screenshot evidence.
Open, Snapshot, Act, and Re-observe
Use one test control and one expected result for the first run. The ref in the example represents the shape of a snapshot handle; use the value from the actual page and follow the installed core guide if its command syntax differs.
Load the guide and open the URL
Read agent-browser skills get core, then run agent-browser open <test-url> with the supplied address. Check that the opened page is the application and account intended for the task. A login page or deployment error is a setup finding, not the target screen.
Find the interactive element
Run agent-browser snapshot -i. Locate the requested button or field by accessible role and name and retain its current @eN ref. If it is missing, inspect loading or alternate UI state before choosing a different control.
Perform one action and refresh the evidence
For a button, use agent-browser click with the returned ref; @e1 is only an example. Read a fresh snapshot after the change and compare the expected panel, text, or records. If the page did not change, inspect the action error and current structure before retrying.
Produce a reproducible result
Report the starting URL, control, action, expected state, and observed state; attach a screenshot for a visual claim. Include a blocked or failed outcome when appropriate. Run agent-browser close when the task’s browser work is finished and no review state needs to remain open.
Related Software Projects
Compare the workflows, operating requirements, and source licenses of these projects.
agent-browser FAQ
Why does the Skill send me back to the CLI?
The repository Skill is intentionally a discovery stub. agent-browser skills get core serves the workflow that matches the installed tool, reducing the chance that copied instructions describe obsolete commands.
Are refs stable selectors?
No. A ref belongs to an observed document state. Refresh it after navigation or meaningful DOM changes, and locate the requested control again; a still-open browser session does not preserve the old element mapping.
What does a snapshot leave unverified?
Accessibility text can establish available names and controls, but not pixel alignment, color, or responsive layout. Use screenshots and the intended viewport for those assertions, and report which evidence supports each conclusion.
When should I load dogfood or electron?
Use dogfood for exploratory QA and bug reports; use electron for an Electron application. These are specialized workflows served by the CLI, not requirements to load for every ordinary webpage.
Should I use MCP and CLI in the same check?
Choose an interface and keep its session identity explicit. The project documents both, but switching blindly can leave the agent observing one browser while acting in another. A terminal workflow is enough when the host can call the CLI.
Does this route give Floatboat a new model?
No. The coding host supplies reasoning and calls the browser tool. Follow the applicable external-agent setup after installing the runtime; any cloud provider and model data handling retain their own configuration and costs.