Snapshots and Refs
The snapshot command captures a compact accessibility tree of the current page and assigns each interactive or content element a unique ref like @e1, @e2.
Taking a snapshot
agent-browser snapshot
agent-browser snapshot -i # Interactive viewExample output:
Snapshot output
- heading "Sign in to GitHub" [ref=e1]
- textbox "Username or email address" [ref=e2]
- textbox "Password" [ref=e3]
- link "Forgot password?" [ref=e4]
- button "Sign in" [ref=e5]Using refs
Refs from the snapshot are used directly in interaction commands:
agent-browser fill @e2 "user@example.com"
agent-browser fill @e3 "mypassword"
agent-browser click @e5Why refs beat CSS selectors for agents
| Approach | Tokens | Reliability | Agent-friendly |
|---|---|---|---|
| Refs (snapshot) | ~200-400 | High | Yes |
| Full DOM | ~3000-5000 | Medium | No |
| Screenshot + vision | ~800+ | Medium | Slow |
Ref validity
Refs are valid for the current page load. After navigation or a dynamic DOM update, take a fresh snapshot before using refs.
agent-browser click @e5 # Submit form
# Page navigates after submit
agent-browser snapshot # Take new snapshot with new refs
agent-browser get text @e1 # Use refs from NEW snapshot