# Reticle

> Reticle is the proof layer for AI agents: it verifies a running web app from the inside, without screenshots, and returns a verdict with evidence.

> ## 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.

## Docs

- [Quickstart](https://docs.reticle.sh/quickstart.md): Install Reticle, connect your coding agent, and get a real verdict with evidence in about five minutes.
- [Why Reticle](https://docs.reticle.sh/why-reticle.md): AI-written code fails by looking correct. Reticle reads the running program instead of the pixels, so a silent failure stops being invisible.
- [Getting started](https://docs.reticle.sh/getting-started.md): Zero to your agent verifying your real app, step by step, with working code for Vite, Next.js, React and plain HTML.
- [Docs for agents](https://docs.reticle.sh/for-agents.md): Fetch any page as plain Markdown, pull the whole site as one file, or hand a page straight to your agent.
- [Agentic install](https://docs.reticle.sh/install-agentic.md): Run npx reticle init and let your coding agent wire Reticle into the project. What it changes, what it asks, and how to read its report.
- [Manual install](https://docs.reticle.sh/install-manual.md): Wire Reticle by hand. Register the MCP server for your agent, add the SDK, and connect it. Every step init automates, written out.
- [Frameworks](https://docs.reticle.sh/frameworks.md): Which frameworks Reticle supports, which are wired but unverified, and the exact wiring for each one.
- [Instrument your app so it can testify](https://docs.reticle.sh/instrumentation.md): Register stores, emit signals, add testids. The three things that decide whether your verdicts say "the DOM changed" or "the app succeeded".
- [State management](https://docs.reticle.sh/state-management.md): Register any store so Reticle can read what your app believes. Zustand and Redux work natively, and eight more have adapters.
- [Flows and the recorder](https://docs.reticle.sh/flows.md): Record an interactive run once and replay it forever as a git-checked, self-healing program anchored on meaning, not selectors.
- [Specs for CI](https://docs.reticle.sh/testing.md): Turn an interactive drive into a repeatable suite with @reticlehq/test: declarative specs bound to signals, never DOM structure.
- [Deploy checks](https://docs.reticle.sh/deploy-checks.md): Enforce verification at the moment code becomes a preview URL, as a Vercel or Netlify check on the PR.
- [Integration patterns](https://docs.reticle.sh/integration-patterns.md): The recommended shape for a real codebase: a minimal production footprint and a signal layer that cannot silently drift.
- [Multi-agent and multi-project](https://docs.reticle.sh/multi-agent-testing.md): Several apps at once, ports that shift between runs, and many agents driving the same app in parallel without a Chromium each.
- [Human-in-the-loop control](https://docs.reticle.sh/human-control.md): Watch the agent’s live transcript, steer it mid-run, or end the session, all from inside the page itself.
- [Integrating Reticle](https://docs.reticle.sh/platform-integration.md): Adopt Reticle on your own codebase, or embed it inside an AI app-builder’s generation pipeline.
- [Troubleshooting](https://docs.reticle.sh/troubleshooting.md): Nothing connected, the click did nothing, the verdict says unknown. The failures people actually hit, and the diagnostic for each.
- [Debugging Reticle](https://docs.reticle.sh/debugging.md): For people working on Reticle itself. How to work out why a flow behaved the way it did.
- [Tools overview](https://docs.reticle.sh/tools-overview.md): The 18 tools your agent sees every turn, the 30 more it can reach on demand, and why the surface is deliberately small.
- [reticle_snapshot](https://docs.reticle.sh/tools-snapshot.md): A semantic accessibility snapshot of the page or a subtree, in three sizes. From the full tree down to a 25-token route check.
- [reticle_query](https://docs.reticle.sh/tools-query.md): Find elements by Testing-Library semantics. Role, text, label, placeholder, testid, alt, or React component, including inside open shadow roots.
- [reticle_inspect](https://docs.reticle.sh/tools-inspect.md): Everything about one element. Accessibility properties, geometry, computed styles, design tokens, React component stack, and the exact source file and line.
- [reticle_navigate](https://docs.reticle.sh/tools-navigate.md): Move the connected tab to a URL or reload it, and understand why ok does not mean the page arrived.
- [reticle_act](https://docs.reticle.sh/tools-act.md): Perform an action without checking the result. Useful for setup steps, and dangerous as a final step, because ok means dispatched, not worked.
- [reticle_act_and_wait](https://docs.reticle.sh/tools-act-and-wait.md): Act on an element and wait for a named consequence in one call. This is the tool that produces a verdict, and the one you should reach for by default.
- [reticle_act_sequence](https://docs.reticle.sh/tools-act-sequence.md): Run several actions in order in one round trip. Fill, fill, submit. Instead of paying a full turn for each step.
- [reticle_observe](https://docs.reticle.sh/tools-observe.md): The full timeline of everything the app did in a window. DOM, network, routing, console, animations and signals, with a summary.
- [reticle_network](https://docs.reticle.sh/tools-network.md): A filtered log of every request the app made, with bodies, status, timing, automatic credential redaction, and an honest note when evidence has expired.
- [reticle_console](https://docs.reticle.sh/tools-console.md): The console log, filtered by level, and an empty result that tells you it is a real reading rather than a missing one.
- [reticle_state](https://docs.reticle.sh/tools-state.md): Read live framework state directly from the running app. What it believes, not just what it rendered, without the app broadcasting anything.
- [reticle_wait_for](https://docs.reticle.sh/tools-wait-for.md): Block until a predicate holds. Or return immediately if it is already true in the recent buffer.
- [reticle_assert](https://docs.reticle.sh/tools-assert.md): Evaluate a predicate against what the app actually did, and get a verdict. Including a clear explanation when it fails.
- [reticle_sessions](https://docs.reticle.sh/tools-sessions.md): List every connected browser tab, with the health fields that tell you whether it can actually be driven.
- [reticle_tools and reticle_run](https://docs.reticle.sh/tools-tools-and-run.md): Discover the 30 tools that are not advertised, load their argument grammar on demand, and invoke any of them by name.
- [reticle_session and reticle_feedback](https://docs.reticle.sh/tools-session-and-feedback.md): Hand the session back to the human, end it cleanly, and tell the maintainers when Reticle got something wrong.
- [Beyond the verify loop](https://docs.reticle.sh/capabilities.md): Coverage, storage, fake clocks, autonomous crawling, visual diffing and network mocking. What Reticle does once look-act-observe-assert is not enough.
- [CLI reference](https://docs.reticle.sh/cli.md): Every reticle command. What it does, what it prints, and what it exits with. Captured from real runs.
- [reticle init](https://docs.reticle.sh/cli/init.md): Wire Reticle into the project in the current directory, registering the MCP server and installing the SDK.
- [reticle status](https://docs.reticle.sh/cli/status.md): Ask whether the Reticle daemon is up and which app sessions have connected to it.
- [reticle serve](https://docs.reticle.sh/cli/serve.md): Start the Reticle daemon on the bridge port and wait until it has actually bound.
- [reticle stop](https://docs.reticle.sh/cli/stop.md): Stop the Reticle daemon on a port, escalating from SIGTERM to SIGKILL if it will not go.
- [reticle kill](https://docs.reticle.sh/cli/kill.md): Free the bridge port by killing its listener, without touching the agent's own MCP proxy.
- [reticle restart](https://docs.reticle.sh/cli/restart.md): Free the bridge port and put a daemon back on it, reporting each half separately.
- [reticle mcp](https://docs.reticle.sh/cli/mcp.md): Run the MCP stdio proxy your agent talks to, starting a daemon if one is not already up.
- [reticle open](https://docs.reticle.sh/cli/open.md): Show the app in a browser, reusing the already-connected tab when there is one.
- [reticle drive](https://docs.reticle.sh/cli/drive.md): Run Reticle in the foreground against a URL, with the browser visible, for debugging.
- [reticle verify](https://docs.reticle.sh/cli/verify.md): Drive a URL once, replay every saved flow, and exit zero only on a real pass.
- [reticle affected](https://docs.reticle.sh/cli/affected.md): List which saved flows must re-verify for a set of changed files.
- [reticle gate](https://docs.reticle.sh/cli/gate.md): Exit non-zero unless passing verification artifacts cover every flow the changed files affect.
- [reticle watch](https://docs.reticle.sh/cli/watch.md): Watch the working tree and report which saved flows must re-verify on every save.
- [reticle capsules](https://docs.reticle.sh/cli/capsules.md): List the saved fail-to-pass bug capsules recorded from failed assertions.
- [reticle hunt](https://docs.reticle.sh/cli/hunt.md): Aggregate many crawl reports into one false-green rate across already-merged changes.
- [reticle update](https://docs.reticle.sh/cli/update.md): Install the latest Reticle server version, sync the project SDK to match, and restart.
- [reticle rollback](https://docs.reticle.sh/cli/rollback.md): Restore the previously installed Reticle server version and restart.
- [reticle license](https://docs.reticle.sh/cli/license.md): Show the enterprise license status resolved from the environment, offline.
- [reticle version](https://docs.reticle.sh/cli/version.md): Print the version of the Reticle server that is actually executing.
- [reticle telemetry](https://docs.reticle.sh/cli/telemetry.md): Show, enable, or disable Reticle's anonymous usage metrics on this machine.
- [reticle feedback](https://docs.reticle.sh/cli/feedback.md): Send a report to the Reticle maintainers from the shell, including from a setup that never finished.
- [reticle identify](https://docs.reticle.sh/cli/identify.md): Opt in to telling the Reticle maintainers who you are, and undo it at any time.
- [reticle help](https://docs.reticle.sh/cli/help.md): Print the complete Reticle command grammar, every command and every flag, on one screen.
- [reticle cloud commands](https://docs.reticle.sh/cli/cloud.md): Sign in, link a repository, and read runs and regressions from Reticle Cloud.
- [Packages](https://docs.reticle.sh/packages.md): Every Reticle package. What it does, why it exists, when you actually need it, and what it depends on.
- [@reticlehq/browser](https://docs.reticle.sh/packages/browser.md): The Reticle instrumentation SDK that runs inside your page, observing the DOM, network, console, routing and state.
- [@reticlehq/server](https://docs.reticle.sh/packages/server.md): The Reticle bridge, MCP server, and the reticle CLI, all in one Node package.
- [@reticlehq/react](https://docs.reticle.sh/packages/react.md): The React kit for Reticle, mapping a DOM node to its component stack, its hook state, and its source file.
- [@reticlehq/vite-plugin](https://docs.reticle.sh/packages/vite-plugin.md): One line in vite.config.ts that stamps source locations on your JSX and auto-injects reticle.connect().
- [@reticlehq/babel-plugin](https://docs.reticle.sh/packages/babel-plugin.md): A Babel plugin that stamps data-reticle-source on JSX host elements so Reticle can name the file a node came from.
- [@reticlehq/next](https://docs.reticle.sh/packages/next.md): Next.js source mapping for Reticle without giving up SWC, via a dev-only loader.
- [@reticlehq/test](https://docs.reticle.sh/packages/test.md): The Reticle spec runner for CI, driving the tools directly with no MCP or stdio in the loop.
- [@reticlehq/eslint-plugin](https://docs.reticle.sh/packages/eslint-plugin.md): Two lint rules that keep Reticle's signal layer and its comment hygiene self-enforcing.
- [@reticlehq/electron](https://docs.reticle.sh/packages/electron.md): The Reticle adapter for Electron, making main-process IPC observable and the window screenshottable.
- [reticle-tauri](https://docs.reticle.sh/packages/tauri.md): The Rust crate that gives a Tauri app Reticle screenshots and headless mode.
- [Predicate reference](https://docs.reticle.sh/predicates.md): The grammar for declaring what should be true. Every kind, every field, and which ones actually prove something.
- [Action reference](https://docs.reticle.sh/actions.md): Every action reticle_act and reticle_act_and_wait can perform, with its arguments and the one that has a history.
- [Recipes](https://docs.reticle.sh/recipes.md): Worked examples for the situations you are actually in, with the real response each one returned.
- [Agent cheat sheet](https://docs.reticle.sh/agent-cheatsheet.md): One screen to get fluent: the look → act → observe → assert loop, with the exact calls to make.
- [Complete usage guide](https://docs.reticle.sh/usage.md): The full reference and cookbook: every tool, flag, and workflow, with worked examples.
- [FAQ](https://docs.reticle.sh/faq.md): Does it run in production, does it need React, does it replace Playwright, and the other questions people actually ask.
- [Desktop apps](https://docs.reticle.sh/desktop.md): Reticle verifies Electron and Tauri apps from inside, including the IPC boundary the renderer cannot see. No browser, no screenshot, no URL to open.
- [Wiring up Electron and Tauri](https://docs.reticle.sh/desktop-apps.md): Install and wire Reticle into an Electron or Tauri app, drive the IPC boundary, and read the troubleshooting for each runtime.
- [Architecture](https://docs.reticle.sh/architecture.md): The moving parts, the data flow between them, and the design decisions behind each one.
- [Benchmarks](https://docs.reticle.sh/benchmarks.md): How we measure Reticle, what each number actually means, and the places Reticle loses.
- [Token efficiency](https://docs.reticle.sh/token-efficiency.md): Why asking narrow questions costs a fraction of feeding the whole accessibility tree to the model every step.
- [Reticle vs Playwright MCP](https://docs.reticle.sh/vs-playwright-mcp.md): Playwright MCP drives any website from the outside. Reticle verifies an app you own from the inside. They solve different problems, and they compose.
- [Reticle vs Chrome DevTools MCP](https://docs.reticle.sh/vs-chrome-devtools-mcp.md): Chrome DevTools MCP is slightly cheaper per look. Reticle caught every bug it missed. Here is the trade, measured.
- [Why screenshots cannot verify AI-generated code](https://docs.reticle.sh/vs-screenshots.md): The failures that AI coding agents actually produce are invisible in a rendered frame. Here is why a better vision model does not fix that.
- [Best practices](https://docs.reticle.sh/best-practices.md): The habits that make a verdict worth trusting, and the specific mistakes that produce a confident, wrong pass.
- [The SKILL file](https://docs.reticle.sh/skill-file.md): One URL you paste into any coding agent to teach it Reticle. How it works, what it contains, and when you need it at all.
- [Telemetry](https://docs.reticle.sh/telemetry.md): The complete description of the anonymous usage data Reticle collects, what it is for, and how to turn it off.
- [Enterprise](https://docs.reticle.sh/enterprise.md): Premium access and activation, what is gated, the security and data-handling posture, and the licensing model.
- [Gates](https://docs.reticle.sh/gates.md): I changed some files. Which command do I run before I push?
- [Release gate plan](https://docs.reticle.sh/gate-plan.md): What has to be true before a PR merges and before a release ships, and what is built so far.
- [System map](https://docs.reticle.sh/system-map.md): How a tool call travels from a coding agent to your app and back, and which of those failures are silent.
- [Telemetry contract](https://docs.reticle.sh/telemetry-contract.md): Read this before adding a tool, an event, a finding kind, or a failure path. Telemetry fails silently.
- [Telemetry events reference](https://docs.reticle.sh/telemetry-events.md): Every Reticle telemetry event, its payload schema, where it is emitted from, and the question it exists to answer.
- [Fixture apps](https://docs.reticle.sh/fixtures.md): Why the apps in apps/ cannot answer the one question that matters before a release, and what does.
- [Local registry](https://docs.reticle.sh/local-registry.md): Exercise local, unpublished Reticle changes in a real external app before they ship.

## Optional

- [GitHub](https://github.com/reticlehq/reticle)
- [Discord](https://discord.gg/BwAbzv9ZRz)
- [npm](https://www.npmjs.com/org/reticlehq)
- [Changelog](https://github.com/reticlehq/reticle/blob/main/CHANGELOG.md)