Selectors
Target elements by role, name, ID, CSS, or combinations.
Refs (fastest)
From the most recent snapshot:
@e1, @e2, @e3
Refs resolve via cached path — O(depth) lookup, no tree search.
Selector DSL
By role
agent-click click 'role=button' -a Calculator agent-click click 'button' -a Calculator # shorthand
By name
agent-click click 'name="Login"' -a Safari # exact agent-click click 'name~="Log"' -a Safari # contains (case-insensitive) agent-click click '"Login"' -a Safari # shorthand
By ID
agent-click click 'id="play"' -a Music # exact agent-click click 'id~="track-123"' -a Music # contains (case-insensitive)
IDs are the most stable selectors — they don't change when UI text is localized.
Combined
agent-click click 'role=button name="Submit"' -a Safari agent-click click 'button "Submit"' -a Safari # shorthand
By index
When multiple elements match:
agent-click click 'role=button index=0' -a Music # first button agent-click click 'role=button index=2' -a Music # third button
By depth
Limit how deep to search:
agent-click find 'role=button depth=3' -a Calculator
Chains (descendant selection)
Find elements inside other elements:
agent-click click 'id=sidebar >> role=button index=0' -a Safari agent-click click 'name="Form" >> button "Submit"' -a Safari agent-click click 'role=window >> role=group >> button "OK"' -a Finder
CSS selectors (Electron apps only)
For Electron apps with CDP:
agent-click click 'css=".submit-btn"' -a Slack agent-click click 'css="#login-form button"' -a Cursor
App scoping
agent-click click 'app="Safari" role=button name="Submit"' # equivalent to: agent-click click 'role=button name="Submit"' -a Safari
Priority
When choosing a selector:
- @ref — fastest, unambiguous
- id= — stable across UI changes
- id~= — for compound IDs
- name= — when ID isn't available
- role + name — when name alone is ambiguous
- css= — for Electron apps (CDP)
- coordinates — last resort