| title | Architecture |
|---|---|
| description | The moving parts, the data flow between them, and the design decisions behind each one. |
| icon | sitemap |
Reticle has three moving parts: a development SDK inside your page that instruments the DOM, network, console, routing and framework state; a local server that runs a WebSocket bridge to that SDK and an MCP server for your agent; and a git-checked .reticle/ workspace holding flows, baselines and run artifacts. Your agent calls an MCP tool, the server turns it into a command over the WebSocket, the SDK runs it in the real page and streams structured events back.
For engineers evaluating Reticle, integrating it at scale, or contributing. It explains the moving parts, the data flow, and the design decisions behind them. If you just want to get running, start with Getting started; come back here when you want to know why.
Your app, in dev, embeds a tiny SDK that instruments the page (DOM, network, console, routing, framework state) and opens a WebSocket to a local bridge. The bridge runs inside the Reticle server, which also exposes an MCP server, the standard protocol AI agents speak.
Your coding agent calls MCP tools (reticle_look { action: "find" }, reticle_act, reticle_assert, …); the server turns them into commands over the WebSocket; the SDK executes them in the page and streams back structured events. The agent thus looks, acts, observes, and asserts on the real running app, never on a screenshot.
flowchart LR
A["AI agent<br/>Claude Code, Cursor, ..."]
S["@reticlehq/server<br/>bridge + MCP + CLI<br/>(Node)"]
B["@reticlehq/browser<br/>SDK in your app<br/>(the DOM)"]
D[(".reticle/<br/>flows · baselines<br/>runs · contract")]
A -- "MCP (stdio/SSE)<br/>reticle_look / act / assert" --> S
S -- "tool results" --> A
S <-- "WebSocket<br/>commands / events" --> B
S <--> D
Reticle is a pnpm + Turborepo monorepo. The split is not cosmetic: each boundary enforces a rule.
| Package | Runs in | Responsibility | Hard rule |
|---|---|---|---|
@reticlehq/core |
both | The wire contract: every constant + zod schema crossing any boundary | Depends only on zod and open-verification |
open-verification |
both | The Open Verification Protocol: vocabulary, rules, adjudicate() |
Depends only on zod |
@reticlehq/engine |
Node | The rules that decide a verdict | No browser, no daemon, no CLI |
@reticlehq/init |
Node (build time) | reticle init: writes files and runs the package manager |
Never opens a socket |
@reticlehq/browser |
the browser | Instrument the page; execute commands; emit events | Never imports Node APIs |
@reticlehq/server |
Node | The bridge, the MCP server, the reticle CLI, flow/run storage |
Never imports DOM APIs |
@reticlehq/react |
the browser | The SDK kit you install in a browser app: re-exports the browser sensor (so one install gives both reticle and install) and maps a DOM node → React component → source file:line |
Core works without the source-mapping half |
@reticlehq/babel-plugin, @reticlehq/next, @reticlehq/vite-plugin |
build time | Stamp data-reticle-source for source mapping (and, for Vite, inject connect()) |
Plain tooling |
@reticlehq/electron |
Electron main process | Adapter for the desktop runtime: IPC observer, main-process capture | Desktop-only, outside the web gates |
adapters/realm/tauri (reticle-tauri) |
Tauri (Rust) | Capture backend for the Tauri desktop runtime | Rust, outside every JS gate; compiled by CI's rust/rust-macos jobs |
@reticlehq/test |
Node (dev dependency) | Spec runner + matchers for running Reticle checks in your CI | Peer dependency on vitest |
@reticlehq/eslint-plugin |
dev tooling | Lint rule for your app: a state change must fire a signal | Dev-only, never shipped in a user's bundle |
Note: pre-2.0,
@reticlehq/corewas a single umbrella package that re-exported all of the above under subpaths. In 2.0 the umbrella was retired and@reticlehq/corebecame the bottom-of-graph wire contract.
Why core-as-contract matters: because the browser and the server are two different runtimes (a DOM and a Node process) that must agree exactly on every message, the temptation is to inline a string like "net.request" in both. That's how drift and silent breakage start. Instead, every such string and shape lives once in @reticlehq/core as a named constant + a zod schema.
The browser and server both import it; neither can invent a message the other doesn't understand. The server zod-parses every inbound WebSocket message; malformed input never flows into logic. A malformed HELLO is refused, and a malformed frame on a live session is dropped and recorded as a gap in that window.
- Connect. In dev, your app calls
reticle.connect({ session }). The SDK opens a WebSocket to the bridge (ws://localhost:4400/reticleby default) and sends aHELLOcarrying the session id, protocol version, and (if configured) a pairing token. Each browser tab usesSESSION_AUTO(a unique id), so multiple apps/tabs never collide. A secondconnect()on a live page does not open a second socket. If it names aprojectIdand the first call did not, the SDK sendsHELLOagain with the id, and the bridge moves the session to that project. An app that callsconnect()itself, before the build plugin'sconnect({ projectId }), keeps its project this way. - Capture. The SDK installs observers: a
MutationObserverfor DOM changes, wrappers aroundfetch/XHRfor network, a console hook, a history hook for routing, and registries the app opts into (registerStore,registerCapabilities,reticle.signal). Events flow into a bounded ring buffer, so recent history is always available and memory is capped. - Look / act. The agent calls an MCP tool.
reticle_look { action: "find" }finds an element by role/text/testid/ component and returns a stable ref.reticle_actdispatches an action against that ref and returns an effect report (did it land, did the DOM mutate, did focus move…). The server sends the command over the WebSocket; the SDK runs it and replies. - Observe. After an action, the agent reads what happened with
reticle_observe { action: "network" },reticle_observe { action: "console" },reticle_look { action: "state" }, or the reaction digest fromreticle_act_and_wait. The server pulls the relevant slice of the ring buffer (scoped to a cursor so stale events can't leak in) and returns a compact summary. - Assert.
reticle_assert(and a flow's declaredsuccess) evaluates a predicate over program truth (a network call that returned 200, a store value, asignalthe app emitted), not just "an element exists." This is the difference between "looks done" and "is done."
Most agent-browser tools can confirm "an element matching X is present." That's the weakest possible oracle: a wrong or healed-to-wrong element satisfies it, and the regression ships anyway. Reticle grades evidence in tiers:
- Tier 1, an app signal (
reticle.signal('order:placed')): the strongest, because a wrong element can't fake it. Available when the app emits it (a ~30-second opt-in). - Tier 2, network + route + state: a POST returned 200, the URL changed, a store value updated. Strong, and works on most SPAs with no setup.
- Tier 3, DOM/text presence: the weak fallback Reticle nudges away from.
Reticle is honest about which tier a given assertion used, so "green" carries its own confidence.
A screenshot is ~1,365 image tokens per look, slow, non-deterministic, and blind to everything non-visual: the failed request, the console error, the route that didn't change. Reticle reads the accessibility tree, the network log, the console, and framework state as compact structured data. That's an order of magnitude cheaper and it sees the bugs pixels can't. See Benchmarks for the measured comparison.
The same verification runs over and over, every commit, every CI run. Reticle records a flow once, then replays it with no AI model: it re-resolves each element's durable anchor against the live DOM and re-asserts the declared consequence. A CI gate diffs the verdict exactly, at ~0% flake, for a couple hundred tokens, versus an agent re-driving the whole flow with the model every time. Self- healing rebinds a drifted anchor only if the consequence still fires, so it never "heals to the wrong element and ships the regression."
By default the SDK is tree-shaken out of production builds and connects only to a local bridge. Production mode is the one exception: it is opt-in, and a page loads the SDK only with a signed, single-use activation ticket. The bridge binds to loopback by default. It refuses a connect without the pairing token, also on localhost. Exposing it beyond localhost also needs the token (and the server refuses to start on a non-loopback host unless RETICLE_ALLOWED_ORIGINS names the app's origins). Every environment variable that gates a security control is a single named constant, so a typo can't silently disable auth. Nothing from the app under test leaves your machine unless you link a project: no DOM, network, console, state, or source. What a linked project syncs is set by reticle config; see what is recorded. The CLI reports anonymous, opt-out usage metrics only (a random id + event names like cli_command_run/daemon_started; no code, no PII; see telemetry); opt out with reticle telemetry disable, RETICLE_TELEMETRY=0, or DO_NOT_TRACK=1. The one thing that carries free text is feedback you or your agent deliberately send (reticle feedback / reticle_session { action: "feedback" }). It is never collected passively, it is redacted before sending, and it is disabled separately with RETICLE_FEEDBACK=0.
The server persists project state under .reticle/ in your repo:
flows/holds recorded, replayable flows (the golden journeys).baselines/holds saved snapshots for diffing.runs/holds verification run artifacts (the evidence trail; writes are atomic and bounded so a crash never leaves a half-written artifact, and the directory is pruned).- the capabilities contract is the testids/signals/stores/flows the app advertises, frozen under a version so the public artifact can't break silently.
This is plain, reviewable, version-controllable data, not a black box.
- Multiple apps / tabs on one bridge: fine. Each connection has a unique
SESSION_AUTOid; a tool call targets the focused/most-recent session, or you pass an explicitsessionId. - Multiple isolated projects: give each project its own bridge port via
RETICLE_PORT(set it in the MCP config and dial the same port from the app). A port already in use fails fast with a clear error rather than hanging. See Getting started → Running multiple apps at once. - CI / no MCP:
reticle verify <url>replays the saved flows headlessly and exits non-zero on failure. It writes the same verdict artifact the MCP path produces, with no agent in the loop.
Every npm package is Apache-2.0: the protocol and the rules (open-verification, @reticlehq/core, @reticlehq/engine), the embeddable SDK and its adapters, and the server, CLI, init and spec runner. The reticle-tauri crate is MIT.
See LICENSE and each package's own LICENSE file.
- Getting started wires Reticle into your app in a couple of minutes.
- Benchmarks covers how we measure, and the honest results against the alternatives.
- Usage is the full tool reference and advanced modes.
- CONTRIBUTING.md has the development loop and the rules.