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 give my coding agent?

Not a prompt first: a command. Run the installer in a terminal:

curl -fsSL https://raw.githubusercontent.com/reticlehq/reticle/main/install/install.sh | sh

On Windows: irm https://raw.githubusercontent.com/reticlehq/reticle/main/install/install.ps1 | iex. It registers Reticle with every coding agent it finds and closes with Next steps: restart your agent if it is already open, then paste the prompt it printed. That prompt is the one to give the agent. It has the agent run init, close the coverage gaps reticle doctor lists, and sets what counts as finished: one real flow in your app driven to a verdict, not a config file. The order matters. An agent reads its MCP server list when it starts, so a prompt pasted into an agent that is already running has no reticle_* tools to call until that agent restarts.

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

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)
  [·] MCP server (Cursor) → /Users/you/.cursor/mcp.json
  [⚠] 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
  [✓] The /reticle command → .claude/commands/reticle.md
  [✓] Install dependencies → package.json
  [✓] Reticle config → .reticle.json
  [✓] Vite plugin → vite.config.ts
  [✓] Capabilities + store → src/reticle-dev.ts

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 (the codex command was not installed to do it), so it printed the exact block to paste. Leave it and Codex simply never sees the tools.

An ℹ line is the one people skim past. Init prints this one when it finds a state library that it cannot register for you (punctuation changed to fit these docs):

  [ℹ] AGENT: finish the capabilities file → src/reticle-dev.ts
      This app's state lives in a library nothing in the running app points at, so it is the one thing Reticle cannot find for itself: reticle_state will not see it until you say where it is.
      Do this now, before driving anything:
        1. In src/reticle-dev.ts, uncomment the suggested line and complete it: <the hint for your library>.
        2. Prove it: drive one flow and check reticle_state returns your key. An empty state read means the line is still not doing anything, whatever else went green.

Do the two steps. Reticle tells you this instead of counting the file as a win. See Instrument your app for what to put in the file.

What it actually changes

The files it writes 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)

Trimmed, with the punctuation changed to fit these docs: the real file also has a comment block about where to start and a declare global block for the DEV type.

// Dev-only. Loaded for you after connect() (by @reticlehq/vite-plugin's injected connect, or by
// the connect file init wrote for a framework that connects itself), so you do not 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) {
  // No state library detected. If you add one, register it here. See https://docs.reticle.sh/state-management

  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>]
              [--env KEY=VALUE]... [--files-only] [--json] [--relaunch]
              --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>" }`, on a project linked with `reticle connect`; otherwise drive it with `reticle_act_and_wait`), 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. It writes that app’s files only; add `--start` to boot it too.
`--license <key>`	Writes `RETICLE_LICENSE_KEY` to `.env` and keeps `.env` out of git. Do not do those two by hand.
`--json`	One result object on stdout; progress and package-manager output go to stderr. Default init reports runtime setup and connection. `--files-only` and `--dry-run` report the wiring result. Init does not drive a flow or produce a verification verdict.
`--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 and VS Code need a window reload before the new server or 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 for the full run: boot the app and wait for a session to connect. Proving a flow is the first run, a separate call.

The two restarts, and when you need them

Your dev server: restart it once. One that was already running read your build config before init edited it, so it keeps serving a bundle without the SDK. Restart it and hard-reload the tab. init names this case when it finds it. Your agent: restart it once, if the tools are missing. An agent reads its MCP server list when it starts. If it started before Reticle was registered, the reticle_* tools are not in this session, and no slash command re-reads the list (/mcp manages servers already loaded). Restart the agent once. reticle init --relaunch prints the exact command that resumes this conversation with the tools loaded. Until then, npx @reticlehq/server verify <url> --expect '<predicate JSON>' proves a flow from the shell. Reticle registers globally, so this happens once per machine.

Confirm it worked

npx @reticlehq/server status

It confirms the app connected, or tells you exactly why it hasn’t. A session listed means the SDK reached the page. Setup is finished when the first run returns a verdict.

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 give my coding agent?

See the plan before anything is written

Reading the marks

What it actually changes

Flags

Already installed? Mostly automatic

The two restarts, and when you need them

Confirm it worked

Something marked ⚠?

​What do I give my coding agent?

​See the plan before anything is written

​Reading the marks

​What it actually changes

​Flags

​Already installed? Mostly automatic

​The two restarts, and when you need them

​Confirm it worked

Something marked ⚠?

What do I give my coding agent?

See the plan before anything is written

Reading the marks

What it actually changes

Flags

Already installed? Mostly automatic

The two restarts, and when you need them

Confirm it worked