| name | agent-browser |
| description | when asking to check ui or tests automation in browser |
Browser Automation with agent-browser
Use agent-browser CLI for browser automation tasks: UI checks, form testing, screenshots, visual diffs.
Requires: npm install -g agent-browser && agent-browser install
Screenshots directory
Save screenshots, PDFs and diffs to .claude/local/screenshots/ (unversioned via .claude/ gitignore).
Create the directory before first use: mkdir -p .claude/local/screenshots
agent-browser screenshot .claude/local/screenshots/page.png
agent-browser pdf .claude/local/screenshots/page.pdf
agent-browser diff screenshot --baseline .claude/local/screenshots/before.png -o .claude/local/screenshots/diff.png
Core workflow
- Navigate:
agent-browser open <url>
- Snapshot:
agent-browser snapshot (returns elements with refs like @e1, @e2)
- Interact using
@refs from the snapshot
- Re-snapshot after every navigation or DOM change — refs go stale immediately
- Close:
agent-browser close
@eN refs are single-use per snapshot. Any click that triggers navigation invalidates all refs. Always call snapshot again before the next interaction.
Known limitations
Commands
Navigation
agent-browser open <url>
agent-browser close
Snapshot & screenshots
agent-browser snapshot
agent-browser screenshot [path]
agent-browser pdf <path>
Interactions (use @refs from snapshot)
agent-browser click @e1
agent-browser dblclick @e1
agent-browser fill @e2 "text"
agent-browser type @e2 "text"
agent-browser press Enter
agent-browser press Control+a
agent-browser hover @e1
agent-browser check @e1
agent-browser uncheck @e1
agent-browser select @e1 "value"
agent-browser scroll down 500
agent-browser scrollintoview @e1
agent-browser drag @e1 @e2
agent-browser upload @e1 file.png
Get information
agent-browser get text @e1
agent-browser get value @e1
agent-browser get html @e1
agent-browser get attr @e1 href
agent-browser get title
agent-browser get url
agent-browser get count @e1
State checks
agent-browser is visible @e1
agent-browser is enabled @e1
agent-browser is checked @e1
Wait
agent-browser wait @e1
agent-browser wait 2000
agent-browser wait --text "Success"
agent-browser wait --url "**/path"
agent-browser wait --load networkidle
Semantic locators (alternative to @refs)
agent-browser find role button click --name "Submit"
agent-browser find text "Sign In" click
agent-browser find label "Email" fill "user@test.com"
agent-browser find testid "login-btn" click
Tabs
agent-browser tab
agent-browser tab new [url]
agent-browser tab <n>
agent-browser tab close [n]
Diff & comparison
agent-browser diff snapshot
agent-browser diff snapshot --baseline before.txt
agent-browser diff screenshot --baseline before.png
agent-browser diff url <url1> <url2>
Evaluate JS
agent-browser eval "document.title"
Network
agent-browser network requests
agent-browser network requests --filter api
agent-browser network route <url> --abort
Browser settings
agent-browser set viewport 1280 720
agent-browser set device "iPhone 15"
agent-browser set media dark
agent-browser set offline on
Debugging
agent-browser console
agent-browser errors
DO / DON'T
| DO | DON'T |
|---|
Call snapshot again after every click, navigation, or DOM mutation | Reuse @eN refs from a previous snapshot — they are invalid after any page change |
Use eval "document.querySelector('...').scrollIntoView()" to scroll to an element | Use scrollintoview @eN — it expects a CSS selector, not a ref |
Use find role/text/label/testid for stable semantic locators when only click or hover is needed | Use find ... fill — find only supports click and hover as subactions |
Create .claude/local/screenshots/ before the first screenshot command | Assume the directory exists |
Call wait --load networkidle after navigation-triggering clicks | Proceed immediately after a click — network may not have settled |
Close the browser with agent-browser close when done | Leave the session open between tasks |
Multi-step Checklist
Use this checklist when running a multi-step browser flow:
Example: Form submission
agent-browser open https://example.com/form
agent-browser snapshot
agent-browser fill @e1 "user@example.com"
agent-browser fill @e2 "password123"
agent-browser click @e3
agent-browser wait --load networkidle
agent-browser snapshot