Reticle Docs: verification for AI coding agents

reticle init is the one command a person runs before anything else. It inspects the directory it is standing in, works out the framework, and writes every piece of wiring Reticle needs: the MCP server registration, the agent rule files, the dev dependencies, .reticle.json, and the bundler plugin.

npx @reticlehq/server init [--env KEY=VALUE]... [--app <dir>] [--license <key>] [--json]
                           [--files-only] [--relaunch] [--no-open] [--no-agents] [--url <app url>]
                           [--timeout S] [--dry-run] [--hooks] [--port N] [--no-mcp] [--no-install]
                           [--start] [--capture-bodies] [--no-first-run] [--new-id] [--no-prompt-capture]

Flags

Flag	Type	Default	What it does
`--dry-run`	boolean	`false`	Print the full plan and write nothing
`--port N`	number	unset (resolves to `4400`)	Bridge port to write into the config
`--no-mcp`	boolean	`false` (MCP is registered)	Skip the MCP registration and the agent rule files (`CLAUDE.md`, `AGENTS.md`, `.cursor`) and the `/reticle` command
`--no-install`	boolean	`false` (deps are installed)	Do not run the install. The step becomes `[–]` (“skipped (—no-install); install them yourself: …”) with the install command for you to run by hand, rather than vanishing from the plan
`--new-id`	boolean	`false`	Give this checkout a project id of its own. A copied repository keeps the original’s `.reticle.json`, and Reticle refuses a session from a second checkout of one id as ambiguous. This replaces `projectId` in this checkout’s `.reticle.json` (and in the agent-root copy that names the same id) with the id derived for this folder, and keeps every other field. Nothing in the original checkout changes
`--app <dir>`	string	unset	Pick which app to wire in a monorepo, without changing directory. On its own it implies `--files-only`
`--start`	boolean	`false`	With `--app`, also boot the app the way a plain `init` does
`--capture-bodies`	boolean	`false`	Write `captureNetworkBodies: true` into the Vite plugin call, so request and response bodies are captured
`--no-first-run`	boolean	`false`	Connect and stop, without the coverage summary
`--no-prompt-capture`	boolean	`false` (the hook is installed)	Do not install the prompt hook in each agent’s project config. See prompt capture
`--hooks`	boolean	`false`	Also add a print-only Stop hook to `.claude/settings.json`, merged into what is there. When the agent stops without a claim that held, it prints one line; it never blocks. See `reticle report`
`--env KEY=VALUE`	string, repeatable	none	What the app needs to reach a usable state: a key from `.env.example`, a mock backend, a variable that skips an auth wall. A value may contain spaces and `=`
`--license <key>`	string	unset	Write an enterprise license key to `.env` and keep `.env` out of git
`--json`	boolean	`false`	Put the result on stdout as one object, for an agent to read
`--files-only`	boolean	`false`	Write the files, register the MCP server and pre-approve the tools, then stop: no dev server, no browser. Also the upgrade path for an existing install
`--relaunch`	boolean	`false`	Print the exact command that restarts this agent conversation with the `reticle_*` tools loaded. Refuses when the session has no transcript behind it. Works with `--files-only`
`--no-open`	boolean	`false`	Do not open a browser window. The connect is checked in a hidden tab instead
`--no-agents`	boolean	`false`	Do not register the MCP server with the other agents on this machine
`--url <app url>`	string	unset	The app is already running at this URL: use it instead of starting a dev server
`--timeout S`	seconds	the framework’s own budget	How long to wait for the dev server and for a session to connect
`--yes`	boolean	`false`	Accepted for scripting. `init` has no interactive prompts today, so it is a no-op

--no-mcp skips more than the server registration. The agent rule files and the /reticle command go with it, because all three only make sense once the tools are reachable.

When init runs, and when it asks for a hand

Your agent runs init only when you agree. The first reticle_session call in a project that was never wired changes no file. It offers the zero-install lease, which checks the running app with nothing installed. reticle init, reticle connect and a setup request from you still wire the app. Some apps get a ⚠ manual step instead of an edit:

An Electron app with a static index.html. A packaged renderer can also run on localhost, so init does not write the localhost-only snippet or reticle.local.js. Connect only in development, for example only when !app.isPackaged. Keep reticle.local.js out of the package: electron-builder files: ["!reticle.local.js"], or Electron Forge packagerConfig.ignore: [/reticle\.local\.js$/].
A Vite config whose plugins is a call or the shorthand { plugins }. Init leaves the config unchanged and tells you where to add reticle().

When ~/.reticle cannot be written (a sandboxed agent host), init writes the dev server log to .reticle/logs/ in the project and prints where it is.

What it prints

A plan, one line per step, each with a status mark: ✓ written, · already in place or left alone, ⚠ needs a hand, – deliberately skipped by a flag, ℹ done, but incomplete in a way that matters. Captured from a real --dry-run inside apps/bench-app, trimmed to one row of each kind:

reticle init (dry run, no files written)
  in /Users/you/reticle/apps/bench-app

  [·] 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
  [✓] Agent verification rule → AGENTS.md
  [✓] Full agent rules → RETICLE.md
  [✓] The /reticle command → .claude/commands/reticle.md
  [✓] Claude Code resume-after-compaction hook → .claude/settings.json
  [✓] Prompt capture: Claude Code → .claude/settings.json
  [ℹ] Prompt capture → .reticle/request.json
  [✓] Install dependencies → package.json
  [✓] Reticle config → .reticle.json
  [✓] Vite plugin → vite.config.ts
  [·] Capabilities + store → src/reticle-dev.ts

Restart your dev server (`vite`).

init pins the packages to the version of Reticle you are running. When the codex binary is on your PATH, the Codex row is not a hand edit: it reads [✓] MCP server (Codex CLI) and registers through codex mcp add reticle -- npx @reticlehq/server mcp. Below the plan it also prints the two things that actually finish the install: restart your agent so it re-reads its MCP server list, then run npx @reticlehq/server status to confirm the app connected. A successful run ends with one more line, Tell us what you are building: https://discord.gg/BwAbzv9ZRz. A dry run and a failed run do not print it. With --no-mcp, the whole MCP and rules group collapses into one skipped line:

  [–] MCP server (global) → global (claude user scope)
      --no-mcp ... also skips the agent rule files (CLAUDE.md / AGENTS.md / .cursor) and the /reticle command

Run from a workspace root with several apps, it refuses to guess, prints a command for each one, and exits 1:

Several apps found in this workspace. Re-run `reticle init` for the one you want:
  reticle init --app adapters/build/next
  reticle init --app adapters/build/vite
  reticle init --app apps/atlas
  reticle init --app apps/bench-app
  reticle init --app apps/electron-smoke
  reticle init --app apps/large-dom-bench
  reticle init --app apps/next-smoke
  reticle init --app apps/tauri-smoke

Given --app, it writes that app’s files and starts nothing: no daemon and no dev server, since a monorepo app’s dev server is often run from the root. Add --start to boot it the way a plain init does. It says which directory it moved to before printing the plan:

No app in this directory ... wiring apps/bench-app instead.

In the two captures above, the punctuation that separates the two halves of the sentence is shown as ....

Exit codes

Code	Meaning
`0`	The app connected. Steps marked `⚠` still need a hand, and do not change the code
`1`	No session connected, init failed, an unknown flag was passed, or several apps were found and none was chosen

An unknown flag is rejected by name: reticle init --bogus prints unknown argument '--bogus', then the short usage (reticle --help), and exits 1.

Worked example

cd apps/web
npx @reticlehq/server init --dry-run     # read the plan first
npx @reticlehq/server init               # then run it
npx @reticlehq/server status             # confirm the app actually connected

The install, step by step

What each step writes and how to read the five status marks.

Tools

Beyond the loop

CLI commands

Packages

Grammar

Long form

reticle init

Flags

When init runs, and when it asks for a hand

What it prints

Exit codes

Worked example

The install, step by step