Reticle Docs: verification for AI coding agents

reticle_act clicks, fills, types, selects, drags. It does exactly one thing and makes exactly one promise: the event was dispatched.

reticle_act proves nothing. If the action is supposed to cause something, use reticle_act_and_wait and get the verdict in the same call. A drive that ends on reticle_act has no result.

Example

{ "ref": "e104", "action": "fill", "args": { "value": "reticle" } }

Real response:

{
  "since": 27544,
  "inputMode": "synthetic",
  "inputModeReason": "not-a-pointer-action",
  "dispatched": true,
  "settled": true,
  "settleReason": null,
  "result": {
    "ok": true,
    "ref": "e104",
    "action": "fill",
    "dispatched": true,
    "settled": true,
    "settleReason": null,
    "testid": "login-password",
    "component": "Login",
    "role": "textbox",
    "name": "Password",
    "effect": {
      "focusMoved": "null->e104",
      "valueChanged": true,
      "domMutatedWithin": 9
    },
    "source": { "file": "src/components/Login.tsx", "line": 59, "column": 8 }
  }
}

The effect block only lists what is worth knowing. Fields sitting at their uninformative default are omitted, so a clean action collapses to its consequence. An absent dispatched, targetMatched, visible or enabled means true; an absent occluded, scrolledIntoView, valueChanged or defaultPrevented means false; an absent focusMoved or occludedBy means null. Do not read a missing field as a failure.

Actions

click · dblclick · hover · focus · blur · fill · type · clear · select · check · uncheck · submit · press · upload · scrollIntoView · scroll · drag · tap · zoom Name the element with ref, or with target to find it in the same call: { testid }, { text }, { role, name } or { label }. A target that matches more than one element is refused. A press of Escape, Tab or a shortcut such as Cmd+K needs neither.

Action	Arguments
`fill`, `select`	`{ value }`
`type`, `press`	`{ text }`. For `press`, the key name, e.g. `Escape` or `Tab`
`drag`	`{ toRef }`. The ref to drop onto
`upload`	`{ path }` (a file on disk) or `{ name, content?, type? }`

Reading the effect block

This is where act earns its place even though it proves nothing.

valueChanged: true: the field took the value. false on a fill usually means that the input is controlled and rejected it, or that it is readonly.
focusMoved: "null->e104": focus went where you expected.
domMutatedWithin: 9: something re-rendered within 9 ms. A fill that changes nothing often means that no handler is attached.
defaultPrevented: a handler called preventDefault(), which is why your form did not submit.
occluded / occludedBy: the click landed on something else. This is the answer to at least half of all “the button does not work” reports.

`settled: false` is not a failure

settled: true with settleReason: null, as above, means a real frame flushed before Reticle stopped watching. settled: false with settleReason: "timeout" means the page was still busy. On a fill that’s normal and uninteresting. On a click you expected to complete something, it’s a hint that you wanted act_and_wait with an explicit until. A settle timeout never fails the tool.

`inputMode` tells you how real the input was

synthetic means Reticle dispatched events programmatically. real means native CDP input, available under reticle drive. Synthetic input is fine for the overwhelming majority of apps; a few drag-and-drop and pointer-gesture libraries only respond to the real thing. inputModeReason explains any choice Reticle made on your behalf, so it is never silent. not-a-pointer-action above means a fill has no pointer path to take, not that real input was unavailable. Clicks default to the occlusion-honest synthetic path even when CDP is configured; pass args.native: true to force a trusted native click for file pickers and clipboard access.

When the tab is backgrounded, synthetic timers and pointer gestures can silently no-op. Every response carries a warning when the tab is throttled. Pass refuseWhenThrottled: true to make Reticle throw instead of pretending it acted.

Tools

Beyond the loop

CLI commands

Packages

Grammar

Long form

reticle_act

Example

Actions

Reading the effect block

`settled: false` is not a failure

`inputMode` tells you how real the input was

​Example

​Actions

​Reading the effect block

​settled: false is not a failure

​inputMode tells you how real the input was

Example

Actions

Reading the effect block

`settled: false` is not a failure

`inputMode` tells you how real the input was