agent-browser organizes browser tasks around observing the page, selecting an element, acting and checking again. Install both the discovery skill and the CLI/browser runtime before expecting it to control a page.
Install and prepare
Set up the runtime and skill in a terminal:
npm install -g agent-browser
agent-browser install
npx skills@latest add vercel-labs/agent-browser
Prepare Node.js, a terminal-capable agent and an accessible target page. These terminal commands install the CLI, browser and skill; the last line alone does not provide the runtime. On Linux, follow the installation guide for missing system libraries.
Your first task
Enter this in the agent conversation, adapting the files and goal to your task:
Use agent-browser to check the course-booking flow at http://localhost:3000. Read the installed CLI’s core guide first. Run `agent-browser session id --scope worktree --prefix course-check` to get a session ID, pass that same ID with `--session` on every browser command, and finish with `agent-browser --session <ID> close`, replacing `<ID>` with that same ID. Check class selection, form entry and returning to edit, without submitting real payment. Save failing steps and a final screenshot.
Load instructions for the installed version
The repository skill is a discovery entry point; the CLI supplies the detailed workflow. Have the agent read agent-browser skills get core --full before choosing a session and opening the page. Read it again after upgrades so command choices match the installed version.
Act on a current snapshot
After opening the page, inspect its interactive elements and identify classes, buttons and fields from current labels and references. Refresh the snapshot when new options or errors appear because old references may no longer identify the intended element. Wait for a meaningful state instead of an arbitrary delay.
Record a reviewable result
A useful booking report identifies the failing step, test input and difference between expected and actual behavior. Screenshots locate the issue while extracted text explains the state. Close the named session afterward so another task does not inherit an unrelated page or half-filled form.
Try the smallest loop before involving an agent
Once the CLI and browser are installed, run these commands together from the target project directory to learn the three basic actions on a public test page:
COURSE_CHECK_SESSION="$(agent-browser session id --scope worktree --prefix course-check)"
agent-browser --session "$COURSE_CHECK_SESSION" open https://example.com
agent-browser --session "$COURSE_CHECK_SESSION" snapshot -i
agent-browser --session "$COURSE_CHECK_SESSION" screenshot example.png
agent-browser --session "$COURSE_CHECK_SESSION" close
Run the block in one terminal so every step uses the same named session. If an agent starts a fresh shell for each command, retain the generated ID and pass it explicitly with --session each time. For a form, select an element reference such as @e3 from the current snapshot -i output. Snapshot again after a click or fill, and wait for a specific condition with a command such as agent-browser --session "$COURSE_CHECK_SESSION" wait --text "Success" when needed. Open the saved screenshot file to inspect it. The official core guide also covers read, text extraction, tabs and accessibility checks; learn those when a task needs them rather than packing everything into a first session.
Read back the target field after filling a form
Identify the control in the current snapshot: use fill for an editable text field, select for a native HTML <select>, and check for a checkbox. A combobox role may describe a custom widget; open its menu, snapshot again and choose through the page UI. The role alone does not establish that select applies.[8]
FredAmartey reports that, with agent-browser 0.38.2 and headless Chrome 147, misusing fill / type on a non-text control can report completion while inserting text into the previously focused text field.[7] On an open test form, check a text field like this:
agent-browser --session "$COURSE_CHECK_SESSION" fill @e3 "test@example.com"
agent-browser --session "$COURSE_CHECK_SESSION" get value @e3
Replace @e3 with the current text-field ref and retain this task's named session ID. The returned value should match your test input. If filling re-renders the page, snapshot again before locating the field. Confirm selected options and checked state from the current page before continuing.
Authentication, sessions and failure evidence
For a logged-in site, confirm account permission and the test-data scope. The unnamed default session is shared with other tasks on the same machine. With the normal CLI-launched browser, different named IDs isolate pages and login state for parallel tasks. If sessions attach to the same external Chrome through --cdp, they only separate tab selection, not browser-wide cookies; do not use that mode as an account-isolation boundary. A session name alone does not preserve login after closing or restarting the browser; configure --restore separately if that is needed. To report a failure, record target URL, last snapshot, command, expected text and actual text, then add a screenshot or recording if useful. A successful click command only means the action was issued, not that the business flow completed. CAPTCHA, site access rules and permissions remain real boundaries; a headed browser does not inherently bypass them.
Another case: filter orders in an admin UI
Scope an automation to read-only verification: “Open the staging orders page, filter Pending, record the before/after count and first order ID, then switch to Completed and confirm the status changes. Do not edit an order or trigger a notification.” Snapshot after each filter action and extract text from the current page. If an asynchronous request updates the list, wait for the result state rather than sleeping a fixed interval. The deliverable is the action sequence, text actually observed and any useful screenshot. If login or page verification blocks access, report the stopping point rather than inferring that no orders exist from an empty page.
Diagnose browser launch or connection failures
If the CLI is on PATH but Chrome will not start, a connection fails or versions mismatch after an upgrade, run:
agent-browser doctor --offline --quick
agent-browser doctor
The first skips network probes and the browser launch test; use the second to check those too. Exit 0 means no check is marked fail (warnings may remain); 1 means at least one failed. Every run cleans stale daemon sidecar files. Adding --fix can install missing Chrome or delete expired state; detecting a version mismatch can also close all active sessions. Inspect the check details before choosing a repair.[5] [9]
Common questions
The skill is installed but the command is missing. Install the CLI separately and check PATH.
It clicked the wrong element. Refresh the snapshot after page changes and use current references.
Does headed mode open every site? No. Authentication, verification and site access rules can still prevent a task.