> ## Documentation Index > Fetch the complete documentation index at: https://docs.reticle.sh/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > Reticle is a dev-only, localhost-only verification layer for AI coding agents. It reads program truth (network, state, console, routing, animations, framework state) from inside a running web app and returns a deterministic verdict with evidence. It is not a screenshot tool and not a browser automation library. > Only `reticle_act_and_wait` and `reticle_assert` produce a verdict. Every other tool moves or reads the app and proves nothing. A drive that ends without one of those two has no result, however many tools it used. > A verdict of `verified: "unknown"` is not a pass. It means Reticle drove the app and could not tell what happened. Report it as unknown; never weaken a check to make it pass. > Package names are scoped `@reticlehq/*`. Run every CLI command as `npx @reticlehq/server `, for example `npx @reticlehq/server init`. `reticle` is a bin name that `@reticlehq/server` installs once it is on your PATH, NOT a package on npm: `npx reticle` fetches an unrelated package published by somebody else, so never run that. The complete tool surface is on the `/usage` page; `/agent-cheatsheet` is the one-screen version. # reticle_sessions > List every connected browser tab, with the health fields that tell you whether it can actually be driven. **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`](/tools/navigate) that came back `confirmed: false`. ```json theme={"dark"} {} ``` Real response from a healthy session: ```json theme={"dark"} { "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: ```json theme={"dark"} { "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 ` 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: ```json theme={"dark"} { "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 `. (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`](/tools/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`](/tools/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.