reticlehq/reticle

It drives your real, running app and reads what happened. Then it returns a verdict, **pass · fail · cannot tell**, with the file:line to fix.
Ask questions, see what we build, and help decide what ships next.
The problem · Demo · What Reticle does · **Install** · Use it · Community · vs Playwright · Benchmarks · Safe to install · Docs
⭐ Star the repo · Good first issues · Contribute
---
The problem
Your agent writes code, **assumes** it worked, and moves on. It never opens the app.
So the broken modal, the silent 500 and the "Deploy succeeded" over a failed deploy all ship. You find them later, by clicking around. **You are now your agent's QA.**
The truth was in the running app all the time. It did not reach the screen.
Your agent did not forget a step. A coding agent is built to **produce a change**, so it is optimistic by design. Verification does the opposite: it goes to find out, and is ready to come back with **no**.
---
Demo
▶ An agent says its fix works. Reticle catches the double charge it missed. Click for the full demo.
---
What Reticle does
Reticle puts a small, **dev-only** SDK inside your app. Your coding agent gets tools to **look, act, observe and assert** through it. Reticle reads the app from the inside. So it sees what the screen hides: the request a click sent, its response, the app state, the console and each element's source line. Every check ends in a verdict with the evidence attached.
- **A verdict, not a screenshot.** verified: "yes", "no" or "unknown" (cannot tell). The verdict includes the request, state change and console line that decided it, and the file:line to open.
- **Sees what the screen hides.** Network responses, each tied to the click that caused it. Your store's real state (zustand, Redux, TanStack Query, Pinia and more). Console errors, request counts and React renders.
- **Says when it cannot tell.** Only yes is a pass. A check that cannot decide returns unknown with the reason. It never gives a quiet green.
- **Flows that replay with no AI model.** Say _"save that as a flow"_. After that, one call re-verifies that journey deterministically. Today's fix cannot quietly break last week's feature.
- **A gate in CI.** reticle gate fails a change that touches a saved flow's code without a new passing run.
- **The Harness** (optional, on the platform): describe a person and a journey. Reticle drives it, verifies each step and saves what passed. How it works.
- **A HUD in your page** to watch the agent work: every action, every verdict, the flows it saved, and notes you pin for it.
- **Works with your agent**: Claude Code, Cursor, Codex, Windsurf, VS Code, Gemini CLI and anything else that speaks MCP. Web (React, Next.js, Vue, Svelte, Angular and more) and desktop (Electron, Tauri).
- **Safe to leave installed.** Production builds do not include the SDK. The bridge listens only on 127.0.0.1. Nothing from your app leaves your machine unless you link a project.
---
Safe to install: what you, or your agent, can check
Whether you are a person or an agent, check a new dependency before you run it. Each fact below has a way to check it yourself.
**Where it comes from**
- **Open source, public history.** Every line that runs is in this repository. The SDK, adapters, core and engine are Apache-2.0. The server and CLI are FSL-1.1-ALv2 (source-available, Apache-2.0 after two years).
- **Signed builds from CI.** GitHub Actions publishes every @reticlehq/* package with npm's SLSA provenance. Check: npm view @reticlehq/server dist.attestations, or npm audit signatures after install.
- **No install scripts.** No package runs a preinstall, install or postinstall hook, so npm install runs none of our code. Check: npm view @reticlehq/server scripts.
- **Scored by OpenSSF.** OpenSSF Scorecard rates the repo's security practices (signed releases, fuzzing, least-privilege CI tokens, a security policy). The badge at the top is live.
**What it touches, and why each one is needed**
A verification tool must sit inside the app it verifies, as React DevTools or a dev-mode error reporter does. That is why it touches more than one place:
| It touches | Why | Scope |
| --- | --- | --- |
| Your app's dev dependencies, build config and one reticle-dev file | The SDK has to run inside the page to read network, state and console | Development builds only. Production builds remove it, and a runtime guard refuses to connect in production |
| Your coding agents' MCP config | So your agent gets the reticle_* tools | One reticle entry that runs npx @reticlehq/server mcp; nothing else in the file changes |