Reticle Docs: verification for AI coding agents

@reticlehq/vite-plugin is one line in vite.config.ts that does the two things everyone forgets: injecting reticle.connect() and enabling source mapping. Install it if your app builds with Vite. On Next.js use @reticlehq/next instead; on any other bundler, wire @reticlehq/browser by hand. Apache 2.0. Depends on @babel/core, @reticlehq/babel-plugin and @reticlehq/core. Optional peer dependency: vite >= 4.

Install and use

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

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

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

The import specifier is @reticlehq/vite-plugin and the export is reticle. An old README documented @reticlehq/core/vite; that subpath has never existed in core’s exports map, and npx @reticlehq/core init is not a command either. The binary is reticle, from @reticlehq/server.

Set RETICLE_PORT in the dev server or desktop build environment to use the same custom bridge port as the CLI. A valid value overrides discovery and .reticle.json; invalid values are ignored.

Why it exists

In a production vite build the plugin injects nothing and swaps the browser SDK for an inert stub, so the bundle carries no Reticle runtime code. That is the guarantee that lets you leave it in the config permanently: there is no way to ship Reticle to your users by forgetting to remove a line.

What it injects

A virtual module at /@reticle-connect, added to the HTML, whose contents are:

import { reticle, install } from '@reticlehq/react';
install();
reticle.connect({/* resolved args */});
if (import.meta.hot) reticle.observeHotUpdates(import.meta.hot);

An app with @reticlehq/browser and no @reticlehq/react (Vue, Svelte, plain TypeScript) gets the same module importing reticle from @reticlehq/browser, without install(). Plus a dynamic import of your dev module if one exists. It looks for src/reticle-dev.ts, .js, .tsx or .jsx, in that order, and leaves the file alone if you have one: that file is yours to edit.

Options

reticle(options?: ReticleVitePluginOptions): ReticleVitePlugin. Every option is optional.

Option	Type	Default
`port`	`number`	Used only when the daemon registry and `.reticle.json` name no port; otherwise `4400`. `RETICLE_PORT` overrides all of them
`root`	`string`	Vite’s `root`, else `process.cwd()`
`sdkVersion`	`string`	Read from the installed `@reticlehq/react`
`session`	`string`	Omitted, so the SDK generates one
`projectId`	`string`	Derived from the package name plus the root path
`token`	`string`	`readPairingToken()`, from `~/.reticle/pairing-token`
`present`	`boolean`	`true`. Set `false` to hide Reticle’s presenter while keeping the agent connection active
`sourceMapping`	`boolean`	`true`. Set `false` to skip the Babel pass
`inject`	`boolean`	`true`. Set `false` to call `connect()` yourself
`discoverStores`	`boolean`	`true`. Set `false` to disable auto-discovery of context stores in React apps (`install({ discoverStores: false })`)
`desktop`	`boolean`	`false`. When `true` the connect passes `allowInProduction: true`, which an Electron or Tauri renderer needs, and a `vite build` in a non-production mode (`--mode development`) is instrumented too. A production-mode build is stubbed like a web build
`captureNetworkBodies`	`boolean`	`false`. Also enabled by `VITE_RETICLE_CAPTURE_BODIES=1`
`networkBodyMaxChars`	`number`	`8192`, clamped to 256 to 262144. Also `VITE_RETICLE_BODY_MAX_CHARS`
`captureErrorBodies`	`boolean`	`true`: a failed response keeps its body. `VITE_RETICLE_NO_ERROR_BODIES=1` turns it off
`testIdAttribute`	`string`	`.reticle.json`’s `testIdAttribute`, else `data-testid`
`allowNonLocalhost`	`boolean`	`false`. Lets Reticle run off localhost; a pairing token is still required. Also `VITE_RETICLE_ALLOW_NON_LOCALHOST=1`
`exposePresenter`	`boolean`	`false`. Contributors only: makes Reticle’s own presenter visible to its tools. Also `VITE_RETICLE_EXPOSE_PRESENTER=1`
`onWarn`	`(message: string) => void`	`console.warn`

reticle({ present: false }) still lets the plugin create and configure the connection; it only hides Reticle’s visible presenter. reticle({ inject: false }) disables that generated connection, so your application must call connect() itself. In that manual call, pass the pairing token explicitly:

reticle.connect({
  token: __RETICLE_TOKEN__,
  root: __RETICLE_ROOT__,
  sdkVersion: __RETICLE_SDK_VERSION__,
});

Add ambient declarations for these identifiers to src/vite-env.d.ts (or another included .d.ts) in a TypeScript app:

declare const __RETICLE_TOKEN__: string;
declare const __RETICLE_ROOT__: string;
declare const __RETICLE_SDK_VERSION__: string;

Vite replaces these define identifiers in application source at build time; the declarations let TypeScript typecheck them and do not create runtime globals. The SDK does not discover the pairing token, so pass it explicitly in a hand-written connection.

Other exports

Export	Type	What it is
`RETICLE_VITE_PLUGIN_NAME`	`'reticle'`	The plugin name
`RETICLE_TOKEN_GLOBAL`	`'__RETICLE_TOKEN__'`	The Vite `define` identifier replaced with the pairing token
`RETICLE_CONNECT_MODULE`	`'/@reticle-connect'`	The virtual module id
`RENDER_PREHOOK_SOURCE`	`string`	The inline render prehook snippet
`RETICLE_DEV_MODULE_CANDIDATES`	readonly tuple	The four dev-module paths it looks for
`readPairingToken`	`() => string \| undefined`	Read the pairing token from disk
`findDevModule`	`(root: string, exists: (p: string) => boolean) => string \| null`	Locate the dev module
`connectModuleSource`	`(options: ReticleVitePluginOptions, devModule?: string \| null) => string`	Build the injected module source

Types: ReticleVitePluginOptions, ReticleVitePlugin, ViteDevServerLike.

Desktop

reticle({ desktop: true });

A packaged Electron or Tauri renderer is loaded from a custom protocol with no dev server and reports NODE_ENV=production, so the default guards would refuse. This flag injects the connect into the entry module and opts it into production. It does NOT instrument a release: a production-mode vite build (the default) ships no Reticle code, exactly like a web build. To drive a packaged renderer with no dev server, build it with vite build --mode development.

Desktop wiring in full

Including the Tauri CSP whose failure is completely silent.

Tools

Beyond the loop

CLI commands

Packages

Grammar

Long form

@reticlehq/vite-plugin

Install and use

Why it exists

What it injects

Options

Other exports

Desktop

Desktop wiring in full

​Install and use

​Why it exists

​What it injects

​Options

​Other exports

​Desktop

Desktop wiring in full

Install and use

Why it exists

What it injects

Options

Other exports

Desktop