# Reticle: a proof layer that lets AI agents verify a running web app

> Reticle runs a dev-only SDK inside your application so an MCP agent can read the network, store, console and DOM and return pass, fail or "couldn't tell" with a file:line to fix. It is for teams whose agents already ship code they cannot check.

**reticlehq/reticle** — AI agents can generate code, but they still struggle to understand what they build. Reticle gives them runtime perception of web & desktop applications.

- Repository: https://github.com/reticlehq/reticle
- Website: https://www.reticle.sh
- Stars: 890 · Forks: 150
- Language: TypeScript
- License: NOASSERTION
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/reticlehq-reticle

## The gap Reticle targets: an agent that cannot see its own output

An agent can write a component, run a type check, and report success. None of that exercises the app. The README frames the failure mode directly: a silent 500 under a page that looks perfect, a flow that used to work and no longer does, mock data where the real API should be. Reticle's answer is to check the code against the real running application, reading the network calls, the store, the console and the DOM, then returning pass, fail, or "couldn't tell" with the file:line to fix. The audience is narrow and specific: teams already running an MCP-capable coding agent (the README names Claude Code, Cursor, Copilot, Codex, Windsurf and OpenCode) on React, Vue, Svelte, Preact, Astro or plain HTML, plus Electron and Tauri on macOS, Linux and Windows. If your agent cannot call MCP tools, nothing here applies to you.

## How the SDK, the MCP server and the skill fit together

Three pieces. A dev-only SDK is instrumented into your app, so the app itself exposes what happened at runtime. An MCP server, published as @reticlehq/server, answers the agent's tool calls against that instrumented app. A skill, shipped in the repository as SKILL.md and installed as the /reticle slash command, holds the procedure: instrument the app, start the dev server if nothing is serving it, open the app, drive one real flow, return a verdict. The README is explicit that the skill is the install path and that a config file is not an install. The repository layout matches this: packages/ holds the SDK and server, skills/ and plugin/ hold the agent-facing artifacts, apps/ holds the e2e harness, and bench/ holds a benchmark harness with its own gate scripts. The verdict vocabulary matters. "Couldn't tell" is a first-class result, not an error, which is the honest position for a tool that reads a live process.

## Installing Reticle and getting a first verdict

On Claude Code the plugin registers the MCP server and the skill in one step. Run these two commands in the client, then run /reticle. The README warns that installing the plugin has not touched your app yet, so the skill still has to instrument it.

```text
/plugin marketplace add reticlehq/reticle
/plugin install reticle@reticlehq
```

Everywhere the skills CLI reaches, including Cursor, Codex, Copilot, Gemini, Windsurf and OpenCode, the install is a single npx command. The README states that you must restart the client afterwards, because the tools do not appear until you do, and it calls this the step most installs stall on.

```bash
npx skills add reticlehq/reticle
```

If you prefer to drive it yourself, the CLI auto-detects your framework, installs the kit and build plugin, and registers the MCP server for every agent. The environment variable in the command is the one the README uses to mark the install source.

```bash
RETICLE_INSTALL_SOURCE=readme npx @reticlehq/server init
```

You can also register the server directly in Claude Code, then restart it. The -s user flag scopes the server to your user configuration.

```bash
claude mcp add reticle -s user -- npx @reticlehq/server mcp
```

After setup, typing /reticle is the whole interaction. The README says it auto-detects whether Reticle is already configured, runs the wizard the first time, and verifies the app on every run after that. What you should see is a verdict, not a config file: pass, fail, or "couldn't tell", with a file:line when something failed.

## Limits the README states plainly

The SDK is dev-only and localhost-only, and the README says app data stays local. That is a deliberate boundary, and it rules out using Reticle against a staging or production deployment, or against a colleague's machine. It also means the tool is only as good as the flow you drive: an agent that opens the app and clicks nothing will get a verdict about nothing. The framework list is a support matrix, not a promise of parity, and the README does not document per-framework differences in what the SDK can observe. There is no rollback story in the README either, so if instrumentation breaks your dev build you are removing it by hand. And the "couldn't tell" result, while honest, is a real cost: a verification loop that frequently returns it is not saving the reviewer any time. If you need a deterministic regression suite that runs in CI without an agent in the loop, this is the wrong layer.

## Reticle against Playwright and browser DevTools

The README addresses this comparison head on, and the difference is where the observation happens. Playwright drives a browser from outside the application and asserts on what the page shows. Reticle instruments the app from inside, so the agent reads the store, the network calls and the console rather than inferring state from rendered output. DevTools gives a human the same raw signal but no programmatic verdict and no file:line. The practical consequence: a Playwright test is a durable artifact you write and maintain, while a Reticle run is a check the agent performs on demand and repeats until it passes. Playwright also runs headless in CI for any language; Reticle is TypeScript, dev-only, and needs an MCP client. They are not substitutes. A team with a mature end-to-end suite gains less from Reticle than a team whose only quality gate is asking the agent whether it finished.

## Maintenance, releases and what the licence split implies

The repository is not archived and the last push was on 2026-09-10, so the project is being worked on now. The release cadence is visible in the tags: v2.12.0 on 2026-08-25, v2.13.0 and v2.13.1 on 2026-09-02, with the monorepo package.json at 2.14.0. The repository carries a CHANGELOG.md, a RELEASING.md, a GOVERNANCE.md and a ROADMAP.md, plus .changes/ for change entries and a prepare-commit-msg.sh hook, which suggests releases are assembled rather than tagged by hand. The root package.json requires Node >=22.12 and pins pnpm@10.33.2, so contributing or building from source has a real toolchain floor. The licence is the part to read carefully: the badge says Apache-2.0 plus FSL, while the repository metadata reports NOASSERTION, and the README describes the SDK as Apache-2.0. That split between an SDK and the rest of the distribution is a deliberate choice, but the README does not spell out which components fall under which terms. Check LICENSE before shipping anything built from this repository. This is not legal advice.

## Conclusion

Adopt Reticle if an MCP-capable agent already writes your UI code and you want verdicts from the running app instead of a diff review. Do not adopt it if your agent cannot speak MCP, if you need production or remote debugging, or if you want a synthetic test suite rather than a verification loop. Before trusting a verdict, confirm which SDK package matches your framework, that the tools appear after restarting the client, and how the Apache-2.0 plus FSL split applies to the components you deploy.

## FAQ

### Does Reticle need my app to be running?

Yes. Reticle instruments a dev-only SDK into your application and reads the live process, so the skill starts the dev server if nothing is serving the app. The verdict comes from the running app, not from static analysis.

### Which frameworks and platforms does Reticle support?

The README lists React, Vue, Svelte, Preact, Astro and plain HTML for the web, plus Electron and Tauri, on macOS, Linux and Windows. The README does not document per-framework differences in what the SDK observes.

### How do I install Reticle on Claude Code?

The README gives two commands to run in the client: /plugin marketplace add reticlehq/reticle, then /plugin install reticle@reticlehq. That registers the MCP server and the skill together, and the README notes you must restart the client before the tools appear.

## Sources

- [Issues](https://github.com/reticlehq/reticle/issues)
- [Project website](https://www.reticle.sh)
- [README](https://github.com/reticlehq/reticle/blob/main/README.md)
- [Releases](https://github.com/reticlehq/reticle/releases)
- [reticlehq/reticle on GitHub](https://github.com/reticlehq/reticle)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/reticlehq-reticle