reticle_query

reticle_query answers “where is the thing I mean?” without dumping the whole page into your context window. It queries the way a testing library does. By role, label, text, testid. So your agent binds to meaning rather than to DOM structure that a refactor will move.

Example

{ "by": "role", "value": "button", "limit": 6 }

Real response from a running app:

{
  "count": 7,
  "elements": [
    {
      "ref": "e18",
      "role": "button",
      "name": "Overview",
      "visible": true,
      "source": "src/components/Sidebar.tsx:41",
      "states": ["present", "visible", "enabled"]
    },
    {
      "ref": "e20",
      "role": "button",
      "name": "Compose",
      "visible": true,
      "source": "src/components/Sidebar.tsx:41",
      "states": ["present", "visible", "enabled"]
    }
  ],
  "total": 7,
  "truncated": true,
  "cost": { "bytes": 938, "tokens": 235 }
}

Seven buttons, each with a ref to act on and a source file to open, for 235 tokens.

Arguments

Argument	What it does
`by`	`role` · `text` · `label` · `placeholder` · `testid` · `alt` · `component`
`value`	The query value for that strategy
`name`	Accessible-name filter. Narrows a broad `role` query
`scope`	CSS selector or ref, to search inside a subtree
`limit`	Cap the descriptors returned. Cuts tokens hard on broad queries
`count_only`	Return just `{ count }`, around 30x smaller
`attrs`	Extra attributes per match, e.g. `['href']` to inventory links
`self`	Return the `scope` element itself instead of searching inside it

Every argument also has a predicate spelling, so { "role": "button" } works as shorthand for { "by": "role", "value": "button" }.

Use `count_only` when you only need a number

“Are there still three rows?” does not require three row descriptors:

{ "by": "testid", "value": "todo-row", "count_only": true }

Reading the response

ref is the handle for every other tool: act, inspect, state. It stays valid until the element leaves the DOM, so you do not need to re-snapshot between actions on the same element. source appears when @reticlehq/react is installed. Note that all five sidebar buttons above report Sidebar.tsx:41. That is the line where the component renders them in a loop, which is exactly the line you want to edit. truncated: true with total: 7 means limit cut the list, not that Reticle ran out of room. states distinguishes present from visible from enabled. An element can be all three and still be covered by a modal. reticle_inspect reports occluded for that.

Query by testid when you can. Role and text queries survive refactors well; testids survive redesigns, translations, and the day someone rewrites your button labels for the marketing team.

Tools

Beyond the loop

CLI

Libraries

Grammar

Long form

Example

Arguments

Use `count_only` when you only need a number

Reading the response

​Example

​Arguments

​Use count_only when you only need a number

​Reading the response

Example

Arguments

Use `count_only` when you only need a number

Reading the response