Install
Three steps. The first one is the whole install.
Before you run any of it. Reticle is a dev tool that edits your build config and registers an MCP server, so here is what it does, up front, rather than after you have run it:
- You do not need an account, and a verdict is entirely local. Nothing is sent anywhere unless you explicitly run
reticle login and reticle link. Without them there is nowhere for anything to go.
- See the plan before anything is written to your project:
npx @reticlehq/server init --dry-run prints every file it would touch and writes nothing. --app <dir> picks which app in a monorepo; --no-mcp skips registering with your agents; --files-only writes the files and stops. (The machine-level installer in step 1 has no dry run — it is a shell script, so read it first if you want to know what it does.)
- If you do link a project, what syncs is yours to choose with
reticle config --runs/--memory/--flows on|off, and what each of those contains is written down. A flow records the journey you drove, so drive staging rather than production until you have read it.
- The CLI sends anonymous usage events (event names and a random id — no code, no page content).
RETICLE_TELEMETRY=0, DO_NOT_TRACK=1 or reticle telemetry disable turns them off.
1. Run the installer
macOS · Linux
curl -fsSL https://raw.githubusercontent.com/reticlehq/reticle/main/install/install.sh | sh
Windows (PowerShell)
irm https://raw.githubusercontent.com/reticlehq/reticle/main/install/install.ps1 | iex
It puts reticle on your PATH and registers the MCP server with every coding agent it can reach: Claude Code, Cursor, Windsurf, VS Code, Zed, Gemini CLI, Copilot CLI, OpenCode, Warp, Kiro, Amazon Q, Cline, Amp, Continue and Factory Droid. Nothing is written outside your agent configs and ~/.reticle. It is a shell script: curl -fsSL <url> | less reads it before you run it.
Codex CLI keeps a TOML config we don't rewrite, so the installer prints the four lines to paste and where they go. It tells you; it doesn't pretend.
2. Open your coding agent
That's it. The tools are already there, because the installer wrote the config before your agent started.
Run the installer first, in a terminal. A coding agent reads its MCP server list once at startup. Install while it's closed and there is nothing to restart. If it was already open, quit and reopen it once.
3. Wire your app
In your project, let your agent run:
RETICLE_INSTALL_SOURCE=readme npx @reticlehq/server init
Like npm init or git init, this is the per-project step. It installs the dev-only SDK, wires your build config, restarts your dev server, and then opens your app and proves a session connected. A config file is not an install, so init doesn't stop until it has seen your app.
Step 1 is once per machine. This step is once per project.
Check it worked
npx @reticlehq/server doctor
Or just ask your agent: "Is Reticle connected to my app?"
Manual install (no pipe to shell)
npm install -g @reticlehq/server # 1. the CLI
npx @reticlehq/server setup mcp # 2. register it with your agents
Step 2 registers the same agents as the installer, and writes the /reticle skill where the agent supports one. On Claude Code it also pre-approves the Reticle tools, so there is no Accept prompt on every call.
Any other MCP client: point it at npx @reticlehq/server mcp.
{ "mcpServers": { "reticle": { "command": "npx", "args": ["@reticlehq/server", "mcp"] } } }
Then continue at step 2 above: open your agent, and run npx @reticlehq/server init in your project.
The RETICLE_INSTALL_SOURCE prefix above is optional. It tells us which page somebody installed from, so we know which docs are working.
Requires Node 20.11+.
Claude Code plugin (skill + MCP in one step)
/plugin marketplace add reticlehq/reticle
/plugin install reticle@reticlehq
Registers the MCP server and installs the Reticle skill together. Reopen Claude Code once and the tools are there.
For other agents that support the skills CLI:
npx skills add reticlehq/reticle
Use it
You never write test syntax. You say what should be true, in plain English.
Verify what you just built
"I changed checkout. Verify it with Reticle before you tell me it's done."
Find what the screen is hiding
"The page looks fine but something's off. Use Reticle to check what's happening underneath."
Prove a bug is fixed
"Reproduce the bug with Reticle, fix it, then prove the fix with the same steps."
Lock a flow so it can't break
"Record the login flow with Reticle, then re-verify it after every change."
Sweep before you ship
"Walk the main routes with Reticle. Tell me anything broken."
Reticle answers with evidence: the request that fired, the state that changed, the console line, and the file to open.
Make it unavoidable in CI
npx @reticlehq/server gate --since HEAD~1
gate works out which saved flows your edits affect and exits non-zero unless a passing artifact covers each one. An agent that edits a covered file cannot call itself finished without re-verifying, and it is the one check nobody can satisfy by reasoning about their own diff. See docs/cli/gate.mdx.
Why not Playwright?
Playwright, DevTools and browser agents all stand outside the browser looking in. For a site you don't own, that's right. For the app you're building, the bugs that matter never reach the pixels.
| Bug |
Looks fine on screen? |
Reticle reads |
Pay button silently returns 500 |
yes |
the network response, tied to the click |
Badge shows "12", the store holds 0 |
yes |
your app's state |
| The form fired the request twice |
yes |
request count |
| "Deploy succeeded", the deploy failed |
yes |
the store's real status |
| A console error slipped in |
yes |
the console since the action |
| Component re-renders 60×/sec |
yes |
the React commit stream |
Use both. Playwright for sites you don't own, many browsers, real pixels. Reticle for the app you're building, inside your agent's loop.
The problem
Your agent writes code, assumes it worked, and moves on. It never opens the app.
So the broken modal, the silent 500, the "Deploy succeeded" over a failed deploy: they all ship, and you find them by clicking around afterwards. You've become your agent's QA.
The truth was in the running app the whole time. It just never reached the screen.
This isn't something your agent forgot. A coding agent is built to produce a change, and it's optimistic by construction. Verification is the opposite motion: going to find out, and being willing to come back with no.
How it works
You: "Verify login works."
Agent, via Reticle: clicks Sign in → POST /api/login → 200 (14 ms) → dashboard rendered → store holds auth: { email: "admin@…" } → PASS, evidence attached.
flowchart LR
A["Your agent<br/>(Claude Code, Cursor…)"] -->|"look · act · observe · assert"| B(("Reticle"))
B <-->|"structured events,<br/>not pixels"| C["Your running app<br/>DOM · network · console<br/>store · React fiber"]
B -->|"verdict + evidence<br/>+ file:line"| A
style B fill:#8b7bff,stroke:#5b4bd0,color:#fff
style A fill:#15131f,stroke:#3a3550,color:#fff
style C fill:#1c2433,stroke:#2f3d57,color:#fff
A verdict points at the line that caused it. That pointer is the difference between "something broke" and a fix.
One call checks many things at once. Say "save that as a flow" and it replays on every later edit with no model in the loop, so today's fix can't quietly break last week's feature.
What one call looks like underneath
// The agent clicked "Pay". Did the right things actually happen?
reticle_assert({
predicate: { allOf: [
{ kind: "net", method: "POST", urlContains: "/api/order", status: 200 },
{ kind: "element", query: { role: "dialog", name: "Order confirmed" }, state: "visible" },
{ kind: "signal", name: "order:saved" }, // the charge actually committed
{ kind: "console", level: "error", absent: true } // …and nothing errored
]}
})
// → { pass: false,
// failureReason: "POST /api/order returned 500, expected 200",
// source: { file: "src/checkout/PayButton.tsx", line: 42 } }
Benchmarks
88 real regressions injected into a controlled app, Reticle against a Playwright script. Every number comes from a committed harness. Reproduce it with pnpm bench.
Re-verification has no model in the loop, so a recorded suite is a fixed, tiny read. Reticle is ahead from the second run even when charged a full LLM drive to author the suite.
Faster for a structural reason rather than a browser-speed one: a time-gated transition is verified from the event stream instead of waited out, and a batch of flows runs as a batch.
Limits
A verification tool that oversells its reach is worse than none.
|
|
| Strong |
silent failed requests, state that disagrees with the screen, stale caches, double-submits, a write that failed while the UI moved on |
| Partial |
races around a single action. It detects request-never-settled and duplicate-request; it is not a scheduler-level race analyser |
| Not the tool |
cross-browser rendering, visual regressions, sites you don't own. That's Playwright |
| Can't see yet |
IndexedDB, Web Workers, closed shadow roots, cross-origin iframes |
When Reticle can't see something, it says so. A verdict is yes, no, or unknown, where unknown means the evidence couldn't decide. Never a quiet pass.
Cost: zero bytes in production. The SDK sits behind import.meta.env.DEV and is dead-code eliminated; a runtime guard refuses to connect under NODE_ENV=production. No app data leaves your machine.
Supported
|
|
| Web |
Next.js (App + Pages), Vite + React, CRA, SvelteKit, Svelte, Astro, Vue 3, Preact, plain HTML |
| Desktop |
Electron, Tauri, including the IPC boundary a browser-only tool can't see |
| Agents |
anything that speaks MCP. Config written automatically for Claude Code, Cursor, Windsurf, VS Code, Zed, Gemini CLI, Copilot CLI, OpenCode, Warp, Kiro, Amazon Q, Cline, Amp, Continue, Factory Droid. Codex CLI is a printed four-line paste |
| Browsers |
Chrome, Edge, Arc, Brave, Opera, Firefox, Safari, plus Electron and Tauri webviews |
| State |
zustand and Redux need no adapter. Shipped: TanStack Query, Jotai, XState, Valtio, MobX, Recoil, Svelte stores, Pinia |
| OS |
macOS, Linux, Windows |
On the roadmap
Routing verification flows with TypeSafe AI's Jev. A verification run makes a lot of small decisions — is this page settled, is this finding worth chasing, does this failure warrant a full capture — and today an LLM answers each one at LLM latency and LLM cost. Jev is a System One model: it returns a typed, probabilistic choice from a fixed set instead of prose, in 70–500ms. That is the exact shape of a routing decision inside Reticle's infra, so when we build that layer, Jev is what decides which flow a run takes. That layer is the roadmap item; it does not ship yet.
What DOES ship, since 3.2.0, is Jev driving the app rather than routing inside it: reticle_verify { action: "explore", driver: "jev" } explores a page by selecting from candidates Reticle enumerated off the DOM, so the model chooses and never composes. See docs/autodrive.md.
Docs
docs.reticle.sh — a page per tool, a page per command, every example captured from a real run.
Quickstart · Frameworks · Troubleshooting · Architecture · Contributing
Join the Discord → Where the work happens in the open: what's being built, what's up for grabs, and design calls before they land.
If Reticle proves useful, a ⭐ helps other developers find it.
License
SDK and adapters are Apache-2.0. The server is FSL (source-available, converts to Apache-2.0 after two years). See LICENSE.
dev-only · localhost-only · your app data stays local
Reticle 让编码 AI 智能体通过操控真实运行中的应用并读取实际发生的事情——网络请求、应用状态、控制台——来验证自己的工作，而不是想当然地认为代码没问题，最后给出通过、失败或“未知”的判定结果，并附上需要修复的确切 file:line。