Reticle Docs: verification for AI coding agents

reticle_sessions is not advertised. The default surface is the merged nine, so an agent does not see this name. Call reticle_session { action: "list" } 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_sessions lists every browser tab currently connected to the Reticle daemon, with the health fields that decide whether it can actually be driven. Reach for it first when a tool says no session is connected, and after every reticle_navigate that came back confirmed: false.

{}

Real response from a healthy session:

{
  "sessions": [
    {
      "sessionId": "sba6117a6-24ec-494d-8c2c-e2958cff2e7f",
      "url": "http://localhost:4310/",
      "title": "Reticle · Mission Control",
      "adapters": ["react"],
      "hasCapabilities": true,
      "hidden": false,
      "lastSeenMs": 155,
      "throttled": false,
      "focused": true,
      "attachment": { "connectedSinceMs": 18654, "outages": 0 },
      "realInputAvailable": false,
      "leased": false
    }
  ]
}

A backgrounded tab adds a recommendation telling you what to do about it, and attachment grows a lastOutage once the connection has dropped at least once:

{
  "hidden": false,
  "throttled": true,
  "attachment": {
    "connectedSinceMs": 1217047,
    "outages": 3,
    "lastOutage": { "startedMs": 1786818483776, "durationMs": 967 }
  },
  "recommendation": "tab hidden/throttled and may be un-focusable from here; refocus it, or run `reticle drive <url>` for a guaranteed scriptable context"
}

When nothing is connected

An empty list is not silent. It comes back with a why that separates the two causes, and refuses to guess between them:

{
  "sessions": [],
  "why": "no browser session connected. Two things to weigh, and neither of them is proof. (1) Nothing is listening on the ports Reticle scans, so the dev server may not be running. That scan is narrow though: a server on any other port is invisible to it, so if the app IS running, ask for its URL rather than assuming it is down, and open it with `reticle open <url>`. (2) There is no `.reticle.json` in the directory this daemon is running in. That is the file `reticle init` writes, so the app may carry no Reticle SDK."
}

That string is trimmed. The full text also lists the exact ports it scanned and warns that in a monorepo the daemon often runs at the root while the app lives in a subdirectory, so you should check the app’s own directory before re-running init.

The fields that decide whether driving will work

Field	Why it matters
`throttled`	The browser is deprioritising a background tab. Synthetic timers and pointer gestures may silently no-op
`hidden` / `focused`	Why it’s throttled, and what to do about it
`hasCapabilities`	Whether the app registered testids, signals and stores. `false` means `reticle_state` has nothing to read
`adapters`	`["react"]` means you get component names and source pointers
`realInputAvailable`	`true` when native CDP input is available, under `reticle drive`
`outages`	How often the connection has dropped. Non-zero is worth investigating

throttled: true is the most common cause of “the click did nothing”. Focus the tab, or drive a dedicated context. It is not your app being broken. It is the browser saving battery on a tab nobody is looking at.

Confirm after navigating

reticle_navigate can only report that a navigation was dispatched. sessions is how you confirm one arrived: a session at the new URL means the page loaded and is instrumented. No session means one of those two is false, and you find out now rather than after three confusing failures.

Scoping

You rarely need to pass sessionId to other tools. Reticle scopes to your project, prefers the active tab, and refuses rather than guesses when the choice is ambiguous. A refusal you can act on beats a silent pick of the wrong tab. Pass it explicitly when you genuinely mean one specific tab, such as when testing two apps at once.

Sessions accumulate. A stale entry pointing at a dev server you have since restarted will sit there looking plausible. reticle_session { action: "end" } clears one out.

Tools

Beyond the loop

CLI commands

Packages

Grammar

Long form

reticle_sessions

When nothing is connected

The fields that decide whether driving will work

Confirm after navigating

Scoping

​When nothing is connected

​The fields that decide whether driving will work

​Confirm after navigating

​Scoping

When nothing is connected

The fields that decide whether driving will work

Confirm after navigating

Scoping