> ## 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/*` and the CLI is `reticle`. Install with `npx reticle init`. The complete tool surface is on the `/usage` page; `/agent-cheatsheet` is the one-screen version.
# Why Reticle
> AI-written code fails by looking correct. Reticle reads the running program instead of the pixels, so a silent failure stops being invisible.
Software has always had bugs. What changed is the *kind* of bug that reaches you.
A human writing code by hand produces errors that announce themselves: a stack trace, a red screen, a test that goes red. An agent writing code produces something more dangerous: a change that looks completely correct, renders beautifully, and does nothing. The page is fine. The data never saved.
We call it a **false green**, and it is the defining failure mode of the AI-coding era.
## What a false green actually looks like
The POST returns `200`. The row appears in the table. Reload the page and it's gone. Nothing was
ever persisted.
The button has an `onClick`. The `onClick` calls a function. The function was never wired to the
store. It looks connected all the way down.
One click, two POSTs. The user gets charged twice. Nothing on screen is wrong.
The form accepts `"abc"` as a quantity and cheerfully sends it to your database.
Every one of these renders as a perfectly nice page. A screenshot approves them all. So does an agent that just took the screenshot, and the agent is the one telling you it's done.
## Why looking harder doesn't fix it
The instinct is to give the agent better eyes: a screenshot, a vision model, a full accessibility tree. This does not work, for a reason that has nothing to do with model quality.
**The information is not in the picture.** Whether a request fired, what status it returned, whether application state changed, whether the console logged an error, whether one click sent one request or two, none of that is visible. You cannot see a network call. You cannot photograph a state mutation. Asking a better model to look more carefully at a screenshot of a page whose bug is non-visual is asking it to hallucinate more confidently.
Reticle takes the other route. It runs **inside** your app and reads the program: network, state, console, routing, framework internals, and the app's own success signals. The answer is not interpreted from pixels. It is read from the running program, which means it is deterministic and the same every time.
## The evidence
We built eleven scenarios: ten bugs, plus a control where nothing is wrong, so anything flagged on the control counts as a false positive. Each tool got the same app, the same moment, the same task.
| Tool | Bugs caught | Detection accuracy | Avg tokens per look | Verification efficiency |
| ------------------- | ----------- | ------------------ | ------------------- | ----------------------- |
| **Reticle** | **10 / 10** | **1.00** | **815** | **12.27** |
| Playwright MCP | 9 / 10 | 0.91 | 1,292 | 6.97 |
| Chrome DevTools MCP | 8 / 10 | 0.82 | 758 | 10.55 |
Observing one real dashboard once, with no bug involved:
| Tool | Snapshot | Network | Observe total | Can it assert success? |
| ------------------- | -------- | ------- | ------------- | ----------------------------------------------------- |
| **Reticle** | 678 | 345 | **1,023** | Yes, via the app's own signal. 46 tokens, un-fakeable |
| Chrome DevTools MCP | 1,105 | 252 | 1,357 | No. DOM and network only |
| Playwright MCP | 1,522 | 671 | 2,193 | No. DOM and network only |
That last column is the one that matters more than the token counts. The other tools can *describe* what a page looks like. Only Reticle can check whether the thing the app itself considers success actually happened.
The full method, the raw data, and the scenarios where Reticle comes second.
## Where Reticle loses
A benchmark that only shows you the wins is an advertisement wearing a lab coat. Ours doesn't.
* **Sites you don't own.** Reticle needs a dev-only SDK inside the app. If you're driving a third party's website, use Playwright. That is what it's for, and it's excellent at it.
* **Pixels.** Reticle reads the program, not the screen. If your bug is "the button is three pixels too far left", Reticle is the wrong instrument.
* **Chrome DevTools MCP is cheaper per look.** 758 tokens against our 815. It catches fewer bugs, so the efficiency works out in our favour, but on raw cost per glance it wins.
## What we have not proven
Being honest here costs us something, and we'd rather pay it than have you find out later.
We ran a controlled test of whether an agent equipped with Reticle *fixes* more bugs than one without it. **It did not show a fix-rate improvement.** The benchmark was confounded in ways we can point at, and we don't consider the question settled. But we are not going to claim a number we didn't measure.
What Reticle demonstrably does is catch failures that are invisible to the alternatives, and hand back the file and line to go fix. Whether that translates into a better fix rate is a separate question, and we're still working on measuring it properly.
## When you should use it
You own the app. An agent edits it. You want the agent to prove its work rather than assure you
of it. React gets you source pointers on top.
You're testing a site you don't control, you need pixel-level visual regression, or your app has
no dev build to instrument.
## The one-sentence version
Your agent already tells you it works. Reticle is the part that checks. And, more usefully, the part that says "I couldn't tell" instead of guessing.
Five minutes to your first real verdict.
How it reads the program without slowing your app down.