Reticle Docs: verification for AI coding agents

Run npx @reticlehq/server init in your project root. It installs the SDK, wires your build config, writes the agent rule files, boots the app, and prints a plan you can read. It is idempotent, so running it twice is safe.

npx @reticlehq/server init

This is the PROJECT step. The machine step comes first and is one command in a terminal, curl -fsSL https://raw.githubusercontent.com/reticlehq/reticle/main/install/install.sh | sh, which registers the MCP server with every agent it can reach so the tools are there when you open your agent. init will register the server itself if nobody has, but doing it from inside an agent that has already read its server list means the tools cannot appear until that agent restarts. Terminal first, then open the agent, then init. See the quickstart.

The install is designed for the agent to run rather than you. The agent is about to be the primary user of this tool, so it may as well set up its own workspace.

Always write the package scope: npx @reticlehq/server <command> is the CLI. Dropping the scope and npx-ing the bare, unscoped reticle name fetches a different package published by somebody else, which will not give you Reticle. Once @reticlehq/server is installed, reticle works as a bin name on your PATH, which is the only context where the unscoped name is ours.

What do I paste into my coding agent to install Reticle?

Copy this whole block into Claude Code, Cursor, Copilot, Codex, Windsurf, OpenCode, or any MCP agent. It tells the agent what Reticle is, why it should want it, and what counts as finished. That last part is the one that matters.

Reticle is the proof layer for AI coding agents. It runs a dev-only SDK inside my
running web app, so instead of guessing whether your change worked, you can drive
the real app and read what actually happened: the network calls, the store, the
console, the routes, the DOM. You get back pass, fail, or "couldn't tell", with
the file:line to fix. No screenshots, no vision model, no test syntax.

Use it because you cannot otherwise tell whether your own code works. Reading the
diff proves nothing, and unit tests do not run the app. Reticle is how you check
your work before telling me it is done, and how you stop reporting "fixed" over a
silent 500.

Install it now:

  RETICLE_INSTALL_SOURCE=docs_site npx @reticlehq/server@latest init

Then follow https://docs.reticle.sh/install-agentic.md and, if anything needs a
manual edit, https://docs.reticle.sh/install-manual.md. Do not stop until you have
driven one real flow in my app and produced a verdict. That, not a config file, is
what "installed" means.

Afterwards, use it whenever you change any user-facing behaviour.

Prefer installing the skills instead? npx skills add reticlehq/reticle on most agents, or /plugin marketplace add reticlehq/reticle then /plugin install reticle@reticlehq on Claude Code, which registers the MCP server and all eleven skills in one step. Then type /reticle and the agent runs this same setup from the skill.

The RETICLE_INSTALL_SOURCE=docs_site marker is how we tell which published route an install came through. It is self-declared by this page and never inferred, it carries no information about you or your project, and dropping it changes nothing about the install.

Everything on this page is real output. It was captured by scaffolding a pristine npm create vite React app and running init inside it while writing this.

See the plan before anything is written

--dry-run prints exactly what would happen and touches nothing:

npx @reticlehq/server init --dry-run

On a fresh Vite + React + TypeScript app, that produced:

reticle init (dry run, no files written)
  in /tmp/initdemo

  [·] MCP server (Claude, global) → global (claude user scope)
      reticle already registered (install once, used by every project)
  [·] MCP server (Cursor, global) → /Users/you/.cursor/mcp.json
      reticle already in Cursor global config
  [⚠] MCP server (Codex CLI) → /Users/you/.codex/config.toml
      add this to /Users/you/.codex/config.toml by hand:
      [mcp_servers.reticle]
      command = "npx"
      args = ["@reticlehq/server", "mcp"]

  [✓] Agent verification rule → CLAUDE.md
      teach the agent to verify features with Reticle after building them
  [✓] The /reticle command → .claude/commands/reticle.md
      type /reticle to verify one flow in the browser
  [✓] Install dependencies → package.json
      npm i -D @reticlehq/react@<version> @reticlehq/vite-plugin@<version>
  [✓] Reticle config → .reticle.json
      write project config (framework + port)
  [✓] Vite plugin → vite.config.ts
      add reticle() to plugins (also injects connect())
  [✓] Capabilities + store → src/reticle-dev.ts
      no data-testid values yet; no state library detected

Reading the marks

There are five, and they mean different things. This is the part worth understanding, because a run full of green ticks can still leave you with a broken install. Two of the five ask something of you.

Mark	Meaning	Do you need to act?
`✓`	Done, or would be done	No
`·`	Already in place from a previous run or another project	No
`–`	Deliberately skipped, usually by a flag you passed	No
`⚠`	Could not be done automatically, with the exact fix printed	Yes
`ℹ`	Done, but incomplete in a way that matters	Yes, read it

A ⚠ is not cosmetic. In the run above, Reticle could not write the Codex CLI’s TOML config, so it printed the exact block to paste. Leave it and Codex simply never sees the tools.

That ℹ line is the one people skim past, so here it is in full:

  [ℹ] AGENT: finish the capabilities file → src/reticle-dev.ts
      src/reticle-dev.ts was written but registers nothing, so `hasCapabilities` stays false
      and reticle_state has nothing to read.

init wrote the file, but a brand-new Vite template has no testids and no state library, so there was nothing to register. Reticle tells you this instead of counting it as a win. See Instrument your app for what to put in it.

What it actually changes

Four files in your project, none of them mysterious.

.reticle.json (project config)

{
  "framework": "vite",
  "projectId": "initdemo-308da9fe"
}

The projectId is how Reticle scopes sessions to this project, so two apps running at once don’t get confused for each other.Keeping .reticle/ small. Reticle bounds the directory for you, by count and by total size. Add a retain block to change what it keeps:

{
  "retain": { "sessions": 20, "visual": 10, "feedback": 20, "budgetMb": 512 }
}

Those are the defaults, and every field is optional. sessions is how many session journals survive, visual how many overlay diffs (pixel baselines are never deleted, because the next comparison needs them), feedback how many local copies of reports already sent, and budgetMb the total the whole evidence tier may occupy. 0 means keep none, and "sessions": 0 also stops journals being written in the first place.Saved flows, capsules, baselines, the contract and the intent ledger are not touched by any of this. They are the part meant to be committed, and a bound that deleted them would be deleting the regression checks your team shares.Your app’s own background calls. An analytics or heartbeat endpoint on your app’s own host looks exactly like the app’s work, so Reticle never guesses. If one of them keeps a verdict waiting, or fails and gets blamed on an unrelated action, name it:

{
  "background": ["/api/analytics/events", "/api/heartbeat"]
}

Each entry is matched the way urlContains is. A listed request stops holding the wait open and stops contradicting a claim; when a contradiction is still reported, it lists what was set aside. It is never hidden from an assertion that names it: net { urlContains: "/api/heartbeat" } still sees it. Keep entries specific: /api would set aside your whole backend. Third-party calls (another site’s beacon or SDK) need no entry; they are already set aside.

vite.config.ts (the plugin)

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import { reticle } from '@reticlehq/vite-plugin';

export default defineConfig({
  plugins: [reticle(), react()],
})

One import, one entry. The plugin stamps source locations onto your elements, which is what turns a DOM node intosrc/components/Login.tsx:81. It also injects connect() so you don’t have to remember to.

src/reticle-dev.ts (your capabilities)

// Dev-only. Imported automatically by @reticlehq/vite-plugin, so you do not need to import it.
// Self-guards on import.meta.env.DEV, so it is a no-op in a production build.
import { registerCapabilities } from '@reticlehq/react';

if (import.meta.env.DEV) {
  registerCapabilities({
    testids: [], // none found; add data-testid to your key elements
    signals: [], // names you pass to reticle.signal()
    stores: [],  // the keys you registered above
  });
}

This is the file that decides how good your verdicts get. Empty, you still get DOM, network and console. Filled in, your agent can check what the app believes, not just what it rendered.

CLAUDE.md and the /reticle command (agent rules)

A rule telling your agent to verify features after building them, and a /reticle command that drives one flow. Skipped entirely with --no-mcp, because rules for tools the agent can’t reach are just noise in the context window.

Flags

reticle init  [--dry-run] [--port N] [--no-mcp] [--no-install] [--app <dir>]
              --app picks WHICH app in a monorepo, when several are found
              --no-mcp skips MORE than the server registration: also the agent rule files
              (CLAUDE.md / AGENTS.md / .cursor) and the /reticle command, because all three
              only make sense once the tools are reachable.

Three of these are answers only the caller has. init reads your repository; it cannot read your request, and these live only there.

Flag	When you want it
`persona: "<what>"`	Name the journey worth proving, on the FIRST RUN (`reticle_verify { action: "explore", persona: "<the journey worth proving>" }`), not on `init`, which does not drive. Reticle can list the buttons on a page; it cannot know that checkout matters and the theme toggle does not. Naming it is the difference between a drive that finishes and one that spends its budget looking for something to do.
`--env KEY=VALUE`	What the app needs to reach a usable state: the key from `.env.example`, the mock backend, the variable that skips an auth wall. Repeatable, and a value may contain spaces and equals signs. Without it a real app sits on a login screen and there is no flow to drive.
`--app <dir>`	Monorepos. `init` can find the apps that are servable; only your request says which one you are working in.
`--license <key>`	Writes `RETICLE_LICENSE_KEY` to `.env` and keeps `.env` out of git. Do not do those two by hand.
`--json`	One object on stdout: what was wired, what connected, the verdict, and an `agentTodo` array. For agents.
`--files-only`	Write the files, register the MCP server with every agent on the machine, pre-approve Reticle’s tools, and stop: no dev server, no drive. What `init` did before it learned to boot the app, and the upgrade path for a machine that installed Reticle on an earlier version.
`--no-open`	Do not open a browser: CI, a container, an SSH session, or a tab you already have.
`--dry-run`	See the plan before anything is written.
`--no-mcp`	Your MCP config is managed elsewhere (dotfiles, a team template).
`--no-install`	You want to add the dependencies yourself, at your own versions.
`--port N`	Something else already owns the bridge port. Not the dev server’s port.

Already installed? Mostly automatic

The first time reticle mcp starts on a new version it applies the pre-approval rules for the agents it finds, once, and records that it did. You get that by upgrading. There is nothing to type. One case is deliberately left out. Creating Cursor’s permissions.json when you do not already have one supersedes whatever you approved inside Cursor itself, so a version bump doing it silently would make your OTHER MCP servers start prompting again, with nothing to connect that to us. Reticle defers it and waits to be asked:

npx @reticlehq/server@latest init --files-only

That writes the files, registers the MCP server with every agent it finds, pre-approves Reticle’s tools so the per-call Accept dialog stops, and stops there: no dev server, no browser, no drive. Every step is idempotent, so a repo that is already wired reports “already” and changes nothing. Two things to know afterwards:

A GUI client reads its config at startup. Cursor, Antigravity, Claude Desktop and VS Code need a window reload before the new rules take effect. The CLIs pick them up on their next run.
The pre-approval is scoped to reticle alone, never a blanket rule for every MCP server, and never a global auto-run switch. If a client’s approval file did not exist before, init says so in a line, because in Cursor’s case that file supersedes what you had approved inside the app.

Drop --files-only to get the full run: boot the app, drive a flow, return a verdict.

The two restarts you no longer have to think about

Your dev server: init handles it. A dev server that was already running read your build config before init edited it, so it keeps serving the old bundle and nothing connects. init restarts it and waits for the port to answer, rather than telling you to. Your agent: not on the critical path any more. Your agent read its MCP server list at startup, before Reticle existed, and no slash command re-reads it. /mcp manages servers already loaded, so it cannot pick up a new one. That used to mean stopping the install to restart. It does not now: the flow is driven by a child agent process started after registration, which reads the list init just wrote. Your own session picks the tools up whenever you next start it, and nothing is waiting on that. This is a once-per-machine annoyance in any case, because Reticle registers globally.

Confirm it worked

npx @reticlehq/server status

It confirms the app connected, or tells you exactly why it hasn’t. A session in the list is the install actually finished. Not a green tick. A connected app.

Something marked ⚠?

The manual install covers every step init can’t automate, per agent and per framework.

Get started

Install

Instrument

Verify and ship

Working with agents

When it goes wrong

Agentic install: let the agent do it

What do I paste into my coding agent to install Reticle?

See the plan before anything is written

Reading the marks

What it actually changes

Flags

Already installed? Mostly automatic

The two restarts you no longer have to think about

Confirm it worked

Something marked ⚠?

​What do I paste into my coding agent to install Reticle?

​See the plan before anything is written

​Reading the marks

​What it actually changes

​Flags

​Already installed? Mostly automatic

​The two restarts you no longer have to think about

​Confirm it worked

Something marked ⚠?

What do I paste into my coding agent to install Reticle?

See the plan before anything is written

Reading the marks

What it actually changes

Flags

Already installed? Mostly automatic

The two restarts you no longer have to think about

Confirm it worked