Reticle Docs: verification for AI coding agents

Installing Reticle by hand is two independent halves: register the MCP server so your agent gets the reticle_* tools, then add the SDK to your app so there is something for those tools to talk to. You need both, in that order. Do only the first half and the tools appear but every call reports no session. Do only the second and your app connects to a daemon nobody is asking questions.

You probably do not need this page. Two commands do all of it:

curl -fsSL https://raw.githubusercontent.com/reticlehq/reticle/main/install/install.sh | sh   # or: irm https://raw.githubusercontent.com/reticlehq/reticle/main/install/install.ps1 | iex
npx @reticlehq/server init                      # in your project

The first registers the MCP server with every agent it can reach. The second wires the app. See the quickstart.This page is for the cases those cannot cover: a machine where piping a script is not allowed, an agent Reticle does not know, or a step the installer reported as needing a hand (Codex CLI is the usual one, because its config is TOML that Reticle will not rewrite).

If you want the CLI without the script:

npm install -g @reticlehq/server
npx @reticlehq/server setup mcp

reticle setup mcp is exactly the registration half of the installer, and it prints any client it could not write for you.

Part 1. Register the MCP server

There is no config file that all agents share. Each harness has its own path and its own schema, so write only the one you actually use.

Tool	File	Root key	`type` needed?
Claude Code	`~/.claude.json` (prefer the CLI below)	`mcpServers`	no
Cursor	`~/.cursor/mcp.json`	`mcpServers`	no
VS Code	`.vscode/mcp.json`	`servers`	no
Windsurf	`~/.codeium/windsurf/mcp_config.json`	`mcpServers`	no
OpenCode	`opencode.json`	`mcp`	`"local"` required
Codex CLI	`.codex/config.toml`	`[mcp_servers.reticle]`	no
Zed	`~/.config/zed/settings.json`	`context_servers`	no

Claude Code

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

Confirm with claude mcp list. reticle should be there. If the claude CLI isn’t available, merge one key into mcpServers in ~/.claude.json. It is a large stateful file, so merge, never rewrite:

{
  "mcpServers": {
    "reticle": {
      "command": "npx",
      "args": ["@reticlehq/server", "mcp"]
    }
  }
}

Cursor, VS Code, Windsurf

Same shape, different file and root key. Cursor and Windsurf use mcpServers; VS Code uses servers:

{
  "mcpServers": {
    "reticle": {
      "command": "npx",
      "args": ["@reticlehq/server", "mcp"]
    }
  }
}

Codex CLI

TOML, in .codex/config.toml. This is the one init cannot write for you:

[mcp_servers.reticle]
command = "npx"
args = ["@reticlehq/server", "mcp"]

OpenCode

Note the flat command array and the required type:

{
  "mcp": {
    "reticle": {
      "type": "local",
      "command": ["npx", "@reticlehq/server", "mcp"]
    }
  }
}

Restart your agent afterwards. It read its server list at startup and nothing re-reads it. /mcp manages servers that are already loaded, so it cannot discover a new one. Restart Claude Code, reload the Cursor window, or press Start in .vscode/mcp.json.

Part 2. Wire the SDK into your app

Vite

npm i -D @reticlehq/react @reticlehq/vite-plugin

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

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

That’s the whole web install. The plugin stamps source locations onto elements. The thing that turns a DOM node into src/components/Login.tsx:81. And injects connect() so you can’t forget it.

Anything without the plugin

If you’re not on Vite or Next, call connect() yourself, guarded so it never reaches production:

import { reticle } from '@reticlehq/browser';

if (import.meta.env.DEV) reticle.connect();

connect() is dev-only by design. Guard it with whatever your bundler gives you: import.meta.env.DEV, process.env.NODE_ENV !== 'production', or a build flag. Reticle also self-guards, but two locks on a door that leads to your users is a reasonable number.

Tauri. and the step whose failure is silent

The frontend is identical to any web app. The CSP is not optional:

{
  "app": {
    "security": {
      "csp": "default-src 'self' ipc: http://ipc.localhost; connect-src 'self' ipc: http://ipc.localhost ws://localhost:4400 ws://127.0.0.1:4400"
    }
  }
}

Tauri’s default CSP blocks the bridge WebSocket before it opens. Your app runs perfectly and simply never connects, with no error to go on. Keep ipc: http://ipc.localhost in connect-src, Tauri v2 needs it for invoke itself. And drop the ws:// entries from your release config.

Screenshots and headless mode need the Rust crate, which is versioned independently of the npm packages:

[dependencies]
reticle-tauri = "3.3"

tauri::Builder::default()
    .invoke_handler(tauri::generate_handler![reticle_tauri::reticle_capture])
    .on_page_load(reticle_tauri::on_page_load)

IPC observation needs nothing on the Rust side. An invoke('load_todos') already reaches Reticle as ipc://load_todos.

Electron, and the rest of desktop

Main-process and renderer wiring, IPC observation, and what differs from the web install.

Part 3. Prove it

npx @reticlehq/server status

A session in the output means the app connected. That. Not a tick in a checklist, is the install finished. If it says nothing connected, the usual cause is a port disagreement between your app and the daemon. The browser console will carry [Reticle] this page could not open a websocket to … naming the exact address it tried; set it explicitly with VITE_RETICLE_WS_URL=ws://localhost:4400/reticle or reticle.connect({ url }). Still stuck? npx @reticlehq/server doctor checks Chromium, the daemon and the port in one command.

Instrument your app

Quickstart

Drive your first flow and read a real verdict.

Get started

Install

Instrument

Verify and ship

Working with agents

When it goes wrong

Manual install: by hand, on purpose

Part 1. Register the MCP server

Claude Code

Cursor, VS Code, Windsurf

Codex CLI

OpenCode

Part 2. Wire the SDK into your app

Vite

Anything without the plugin

Tauri. and the step whose failure is silent

Electron, and the rest of desktop

Part 3. Prove it

Instrument your app

Quickstart

​Part 1. Register the MCP server

​Claude Code

​Cursor, VS Code, Windsurf

​Codex CLI

​OpenCode

​Part 2. Wire the SDK into your app

​Vite

​Anything without the plugin

​Tauri. and the step whose failure is silent

Electron, and the rest of desktop

​Part 3. Prove it

Instrument your app

Quickstart

Part 1. Register the MCP server

Claude Code

Cursor, VS Code, Windsurf

Codex CLI

OpenCode

Part 2. Wire the SDK into your app

Vite

Anything without the plugin

Tauri. and the step whose failure is silent

Part 3. Prove it