Getting started

Looking for the fast path? Quickstart gets you to a real verdict in five minutes, and every response on it was captured live. Agentic install and Manual install cover setup in detail, per agent and per framework. This page is the long-form walkthrough: the same ground, more slowly, plus per-framework wiring, multi-app setups and prerelease notes. Start here if you want the whole picture in one file rather than the fast route.

• 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 and source-file mapping
• Step 4: Run it and 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

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_look { action: "element" } can tell the agent which component/file to edit (also from @reticlehq/react).

​

Prerequisites

• Node 20 or newer, 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

RETICLE_INSTALL_SOURCE=docs_site npx @reticlehq/server init

• registers the Reticle MCP server once, globally, for each agent you have installed (Claude Code via claude mcp add reticle -s user, and/or Cursor via ~/.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

curl -fsSL https://raw.githubusercontent.com/reticlehq/reticle/main/install/install.sh | sh     # macOS, Linux
irm https://raw.githubusercontent.com/reticlehq/reticle/main/install/install.ps1 | iex          # Windows PowerShell

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: [reticle(), react()],
});

​

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>
  );
}

​

Streamlit

​

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: [reticle({ port: 4401 }), react()],

​

Step 3: (React) component and 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_look { action: "element" } returns file:line (e.g. app/page.tsx:30):

// next.config.ts
import { withReticle } from '@reticlehq/next';
import type { NextConfig } from 'next';

const nextConfig: NextConfig = {};
export default withReticle(nextConfig); // no-op in production

This is exactly what reticle init writes. @reticlehq/next is CommonJS, so a default import (import reticleNext from '@reticlehq/next' then reticleNext.withReticle(...)) and a CJS const { withReticle } = require('@reticlehq/next') both work too, if your config is .mjs or .js. 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 and verify the connection

reticle init does this for you: it starts the dev server, opens the app and waits for the session. Read on only if you are wiring by hand, or if it told you it could not.

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

reticle_verify { action: "explore", persona: "<what>" } drives this for you and saves the flow. This section is what it does, for when you want to do it yourself.

“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_look({ action: "find", 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: { kind: "allOf", predicates: [
  { 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_look({ action: "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_verify { action: "heal" } repairs renamed anchors.
• Testing with @reticlehq/test gives you 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 covers 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_look({ action: "page", 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_assert { action: "wait" }.
• 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

​

Frequently asked questions

​

What exactly does reticle init change in my project?

​

Do I have to re-register the MCP server for every project?

​

Why do the Reticle tools not appear after installing?

​

Which Node version do I need?

​

Do I need the React adapter?

​

Can I run several apps against Reticle at once?

​

Will Reticle end up in my production bundle?

​

Why is my install failing with ERESOLVE?