Reticle Docs: verification for AI coding agents

reticle_query is not advertised. The default surface is the merged ten, so an agent does not see this name. Call reticle_look { action: "find" } instead. Everything below describes what that call does; only the spelling changed. A call to the old name is answered with the new one, but an allowedTools allowlist or an MCP permission rule naming it refuses before Reticle is asked.

reticle_look { action: "find" } 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 or testid. Your agent then binds to meaning, not to DOM structure that a refactor will move.

Example

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

Real response from a running app, with four of the six elements trimmed out for length:

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

Seven buttons matched and six came back, because limit is 6. Each one has a ref to act on and a source file to open, for 236 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`	Attribute NAMES to project per match, e.g. `['href']` to inventory links. The values come back in each match’s `attrs` map. It does not filter, so `name=value` is refused
`self`	Return the `scope` element itself instead of searching inside it

role, text, label, placeholder, testid and alt also have 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": "login-submit", "count_only": true }

{ "count": 1, "cost": { "bytes": 11, "tokens": 3 } }

Three tokens. Note that total is not emitted on this path, because count already is the total.

A zero-match result tells you what is there

{ "by": "testid", "value": "compose-prompt" }

{
  "count": 0,
  "elements": [],
  "hint": {
    "route": "/hostile",
    "knownEmptyState": true,
    "presentTestids": [
      "brand",
      "nav-overview",
      "nav-deployments",
      "nav-compose",
      "nav-diagnostics",
      "nav-hostile",
      "session-pill",
      "cmdk-open",
      "sign-out",
      "hostile-view",
      "hostile-ticker",
      "hostile-feed-count"
    ],
    "presentRegions": [
      { "role": "list", "childCount": 0, "name": "hostile-feed", "sample": [] },
      { "role": "banner", "childCount": 0, "sample": [] }
    ]
  },
  "cost": { "bytes": 402, "tokens": 101 }
}

The testid existed, on another route. hint.route says where you actually are, presentTestids says what is on this page instead, and presentRegions distinguishes an empty list from a missing one. All of it without paying for a snapshot.

Reading the response

ref is the handle for every other call: reticle_act, reticle_look { action: "element" }, reticle_look { action: "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 the app is built in development with the Reticle build plugin. Production builds omit it. Both sidebar buttons above report Sidebar.tsx:41. That is the line where the component renders its nav buttons in a loop, which is the line you want to edit. truncated: true with total: 7 means limit cut the list, not that Reticle ran out of room. Neither field is emitted when nothing was cut, so their absence is itself the signal that you are looking at every match. states distinguishes present from visible from enabled. An element can be all three and still be covered by a modal. reticle_look { action: "element" } 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 commands

Packages

Grammar

Long form

reticle_query

Example

Arguments

Use `count_only` when you only need a number

A zero-match result tells you what is there

Reading the response

​Example

​Arguments

​Use count_only when you only need a number

​A zero-match result tells you what is there

​Reading the response

Example

Arguments

Use `count_only` when you only need a number

A zero-match result tells you what is there

Reading the response