​

Getting Started with Reticle

• What you’re setting up
• Prerequisites
• Step 1 — Connect your coding agent (MCP)
• Step 2 — Embed the SDK in your app
  • Vite + React
  • Next.js
  • Plain / other frameworks
• Step 3 — (React) component & source-file mapping
• Step 4 — Run it & verify the connection
• Step 5 — Your first verification
• Step 6 — Make your app agent-legible
• Common setups at a glance
• Troubleshooting

​

What you’re setting up

┌─────────────┐   MCP    ┌──────────────────────┐   WebSocket   ┌─────────────────────┐
│ coding agent │◀───────▶│  reticle bridge + server │◀─────────────▶│ your app + the Reticle │
│ (Claude Code)│  stdio  │  (npx @reticlehq/server)  │  localhost    │   SDK (dev only)    │
└─────────────┘          └──────────────────────┘  :4400        └─────────────────────┘

1. The MCP server — your agent launches it with npx @reticlehq/server mcp; it hosts the tools and the WebSocket bridge your app connects to. You don’t run it by hand; the agent does.
2. The SDK — import { reticle } from '@reticlehq/react', a few lines in your app’s dev entry point.
3. (Optional) React adapter + source-mapping — so reticle_inspect can tell the agent which component/file to edit (also from @reticlehq/react).

​

Prerequisites

• Node 18+ and a package manager (npm/pnpm/yarn).
• A coding agent that speaks MCP: Claude Code, Cursor, Windsurf, Claude Desktop, etc.
• A web app you run locally in dev (any framework; React gets the richest features).

​

Fastest path — reticle init

npx @reticlehq/server init

• registers the Reticle MCP server once, globally, for each agent you have installed — Claude Code (claude mcp add reticle -s user) and/or Cursor (~/.cursor/mcp.json) — so every project on this machine gets it; you never re-add it per project,
• writes a verification rule into your agent’s instruction file — CLAUDE.md, .cursor/rules/reticle.mdc, or AGENTS.md — so the agent knows to verify a feature with Reticle after building it, not only when you remember to ask (idempotent; appended below anything you already have),
• installs the SDK kit (@reticlehq/react) and the right build plugin (@reticlehq/vite-plugin or @reticlehq/next) as dev dependencies,
• Vite: adds the reticle() plugin to your config — which wires source mapping and reticle.connect() for you, so there is nothing else to edit,
• Next / other: creates the dev component and prints the exact withReticle / mount / connect snippets to paste (it never half-edits a build config).

​

Step 1 — Connect your coding agent (MCP), once

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

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

Want a different port? Set RETICLE_PORT in the server env and pass the same URL to reticle.connect({ url }) in Step 2.

​

Step 2 — Embed the SDK in your app

npm i -D @reticlehq/react @reticlehq/vite-plugin     # Vite; or: pnpm add -D …
# Next.js instead? npm i -D @reticlehq/react @reticlehq/next

​

Vite + React

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

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

​

The pairing token (why some setups need one line more)

• Vite plugin users: nothing to do. The plugin reads the token server-side and injects it into connect() for you.
• Next.js / hand-wired connect(): your connect() runs in the browser and can’t read the file, so pass the token in yourself. The simplest path is a shared secret: set RETICLE_TOKEN for the daemon (it uses that instead of auto-generating) and expose the same value to the client as NEXT_PUBLIC_RETICLE_TOKEN, then pass it to connect({ token }) (see below). On a single-user machine you can also just read ~/.reticle/pairing-token in your dev tooling and forward it the same way.

​

Next.js

// app/reticle-dev.tsx
'use client';
import { useEffect } from 'react';

export function ReticleDev() {
  useEffect(() => {
    if (process.env.NODE_ENV === 'development') {
      // SESSION_AUTO = a unique id per tab, so several Next apps/tabs never collide on one session.
      // NEXT_PUBLIC_RETICLE_TOKEN carries the pairing token to the browser (see "The pairing token").
      const token = process.env.NEXT_PUBLIC_RETICLE_TOKEN;
      void import('@reticlehq/react').then(({ reticle, SESSION_AUTO }) =>
        reticle.connect({ session: SESSION_AUTO, ...(token ? { token } : {}) }),
      );
    }
  }, []);
  return null;
}

// app/layout.tsx
import { ReticleDev } from './reticle-dev';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        {process.env.NODE_ENV === 'development' && <ReticleDev />}
        {children}
      </body>
    </html>
  );
}

​

Plain / other frameworks

import { reticle, SESSION_AUTO } from '@reticlehq/react';
// Pass the pairing token (see "The pairing token" above); on a hand-wired setup you supply it yourself.
if (location.hostname === 'localhost')
  reticle.connect({ session: SESSION_AUTO, token: import.meta.env.VITE_RETICLE_TOKEN });

<script type="module">
  import { reticle, SESSION_AUTO } from 'https://esm.sh/@reticlehq/react';
  reticle.connect({ session: SESSION_AUTO });
</script>

Want to watch the agent work? Add present: true to reticle.connect() for a glowing border, a synthetic cursor that flies to targets, click/hover effects, and a narration HUD. See usage §16.

​

Running multiple apps at once

// project-b/.mcp.json — give this project its own bridge port
{
  "mcpServers": {
    "reticle": {
      "command": "npx",
      "args": ["-y", "@reticlehq/server", "mcp"],
      "env": { "RETICLE_PORT": "4401" },
    },
  },
}

// project-b's app — dial the same port
reticle.connect({ session: SESSION_AUTO, url: 'ws://localhost:4401/reticle' });

// project-b/vite.config.ts
plugins: [react(), reticle({ port: 4401 })],

​

Step 3 — (React) component & source-file mapping

import { install as installReticleReact } from '@reticlehq/react';
if (import.meta.env.DEV) installReticleReact(); // call before reticle.connect()

// vite.config.ts
import react from '@vitejs/plugin-react';
import reticleSource from '@reticlehq/babel-plugin';

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

Next.js: verified on Next.js 15 / React 19 (app router, SWC). For source-file mapping, use @reticlehq/next instead of the Babel plugin — it adds a dev-only webpack pre-loader that keeps SWC and stamps data-reticle-source so reticle_inspect returns file:line (e.g. app/page.tsx:30):

// next.config.mjs
import reticleNext from '@reticlehq/next';
/** @type {import('next').NextConfig} */
const nextConfig = {};
export default reticleNext.withReticle(nextConfig); // no-op in production

Component identity works with or without it (Next’s internal wrappers are filtered out so you see your components, e.g. just Page).

​

Step 4 — Run it & verify the connection

1. Start your app’s dev server as usual (npm run dev).
2. Open it in the browser (the SDK connects when the page loads).
3. In your agent, ask it to confirm the connection:

“List Reticle sessions.”

{ "sessions": [{ "sessionId": "my-app", "url": "http://localhost:3000/", "title": "…" }] }

​

Step 5 — Your first verification

“Add a ‘Refresh’ button to the header that re-fetches the dashboard data, then use Reticle to verify clicking it fires GET /api/dashboard and shows no console errors.”

// finds the button it just added
reticle_query({ by: "role", value: "button", name: "Refresh" })   // → ref e12

// clicks it
reticle_act({ ref: "e12", action: "click" })                       // → { since: 920 }

// verifies the reaction
reticle_assert({ timeout_ms: 2000, predicate: { allOf: [
  { kind: "net", method: "GET", urlContains: "/api/dashboard", status: 200, since: 920 },
  { kind: "console", level: "error", absent: true }
]}})
// → { pass: true }

​

Step 6 — Make your app agent-legible (optional, high-leverage)

<button data-testid="refresh">Refresh</button>

import { reticle } from '@reticlehq/react';
onSaved(() => reticle.signal('order:saved', { id, total }));
// agent: reticle_assert({ predicate: { kind: 'signal', name: 'order:saved', dataMatches: { id: '*' } } })

Recommended: instead of importing reticle into components, inject a createReticleEmitter() emitter and pair each commit with commitAndSignal(...) so the mutation↔signal can’t drift — reticle.signal stays the primitive underneath. See integration-patterns.md.

import { registerStore } from '@reticlehq/react';
registerStore('cart', useCart); // pass the store itself → auto STATE_CHANGE diffs
// agent: reticle_state({ store: 'cart' })  → { stores: { cart: {...} } }

import { registerCapabilities } from '@reticlehq/react';
registerCapabilities({
  testids: ['refresh', 'cart-open', 'checkout'],
  signals: ['order:saved', 'cart:updated'],
  stores: ['cart'],
});
// agent: reticle_capabilities()  → the whole testable surface

Multi-domain apps: prefer registerReticleDomain({ testids, signals, stores }) co-located in one reticle.ts per domain — each self-registers and reticle_capabilities() assembles the union, so there’s no central map to forget. See integration-patterns.md.

Watch the agent work: pass present: true to reticle.connect() for a glowing border, a cursor that flies to targets, and a HUD; the agent can call reticle_session {action:"narrate"}({ text }) to show its intent. See usage §16.

Hover-gated UI (tooltips, hover menus, pointer drag)? Synthetic events can’t trigger native onMouseEnter. Enable real input by launching your browser with --remote-debugging-port=9222 and setting RETICLE_CDP_URL in the MCP server env — Reticle then drives real pointer input and reticle_act reports inputMode:"real". See usage §18.

​

Going further

• Flows, recorder & self-healing — record a golden path once; Reticle saves it to a git-checked .reticle/ flow anchored on testid+signal, replays it (with legible drift), and reticle_flow_heal repairs renamed anchors.
• Testing with @reticlehq/test — declarative reticleTest specs you run headless / in CI; flows can become the specs.
• Human-in-the-loop control — with present: true, pause / message / end the agent from the floating panel.
• Integration patterns — the recommended zero-prod-bundle emit adapter, store-layer signals, and incremental adoption.

​

Common setups at a glance

​

What Svelte support is, and what it is not

​

Troubleshooting

• Run reticle status — it shows whether the daemon is up and which tabs are connected (url, health, pending flagged bugs) at a glance. No connected sessions means the SDK isn’t reaching the bridge.
• Is your app actually running and open in a browser tab?
• Is reticle.connect() running? (Check it’s inside your dev guard and the guard is true.)
• Port mismatch? If you set RETICLE_PORT, pass the same URL to reticle.connect({ url: 'ws://localhost:<port>/reticle' }).
• Need to restart the daemon? reticle stop cleans it up — no pkill needed.

• Ask it to reticle_snapshot({ mode: "interactive" }) to see what’s actionable.
• Add a data-testid to the element for a stable handle.
• Narrow with scope (a CSS selector or a ref).

• Use timeout_ms on reticle_assert / reticle_wait_for.
• Pass the since cursor returned by reticle_act so only post-action events count.

• Wire up @reticlehq/babel-plugin (Step 3). Without it, only component identity is available.

• Keep reticle.connect() behind a dev guard (import.meta.env.DEV / NODE_ENV). The package is side-effect free and tree-shakes out when unused. As a backstop, connect() also self-disables when the build reports NODE_ENV=production (so an SSR healthcheck or a prod bundle opened on localhost won’t activate it) — pass allowInProduction: true only for a deliberate prod diagnostic.

​

Installing alongside a Next.js or React prerelease

npm install @reticlehq/next --legacy-peer-deps
# or use pnpm, whose peer resolution does not hard-fail here
pnpm add @reticlehq/next