Reticle

A verification tool that a coding agent calls as MCP tools. In development the app embeds a small SDK that watches the DOM, network, console, routing and framework state over a local WebSocket; the agent looks, acts, observes and then asserts what should be true, and gets back yes, no or unknown with the evidence attached and the source file and line to fix. Nothing is graded from a screenshot: the reads are the accessibility tree, the network log, the console and the store, which is where the failures that never reach the pixels live. It ships as a CLI, an MCP server, build plugins for Vite, Next and Babel, and adapters for Electron, Tauri and command-line subjects; a flow is recorded once and replayed with no model in the loop, and a CI gate refuses to pass an edit to a covered file without a covering verdict.

Who built itThe account divshekhar wrote 2,226 of the repository’s 2,602 commits, which is 86% of everything in it; the next human contributor has 56. The README invites readers to book a call with “the founders”, plural, and the roadmap speaks as “we”. 1,890 commits carry a co-author trailer, and 934 of those name Claude Opus 5 with a one-million-token context, ahead of Claude Opus 4.8 at 661 and Cursor at 32.

1. 01

   A repository on 2026-06-11, a working bridge three days later

   The repository was created on 2026-06-11 and the first commit landed on 2026-06-13 with the message “M0: project scaffold + working bridge round-trip”: a scaffold and a socket that answered, in one step. By 2026-09-30 it held 2,602 commits, the newest a fix titled “a daemon skew is told to the connection that announced it” (issue #1136). The monthly shape is 395 in the creation month, 466 in July, 1,252 in August and 489 in September. The twenty releases listed run from v2.1.0 on 2026-07-18 to v3.4.0 on 2026-09-30, about one every four days and four of them in the last twelve; the tag list also carries a v3.0.0 the release list does not, so the move from 2.14.0 to 3.1.0 skipped a number. The last day is worth reading in order: between 18:16 and 18:20 the maintainer filed thirty issues, each naming a file and a “Done when” clause, v3.4.0 was tagged at 18:25, and commits kept arriving until 18:42. Two of them were claimed from outside within the hour, under a repository that also carries issue templates, code owners, a DCO check, a governance document, a code of conduct and the hacktoberfest topic. A changelog of 706,454 bytes is assembled by a script, and tests keep the published packages and the Rust crate in version lockstep while treating an additive contract as something other than skew.

2. 02

   The sensor sits inside the page, not beside it

   The organising choice is in the README: Playwright, DevTools and browser agents stand outside the browser looking in, which is right for a site you do not own and wrong for the app you are building, where the bugs that matter never reach the pixels. So the app carries the sensor. In development it calls connect and opens a WebSocket to the bridge at ws://localhost:4400/reticle by default, sending a HELLO with a session id, the protocol version and, if configured, a pairing token; each tab generates its own id, so two tabs never collide. The SDK then installs a MutationObserver for DOM changes, wrappers around fetch and XMLHttpRequest, a console hook and a history hook for routing, plus the registries an app opts into by name, and pushes all of it into a bounded ring buffer, so recent history is always available and memory is capped. The agent calls an MCP tool, the server turns it into a command over that socket, and the SDK runs it in the real page and streams structured events back — look, act, read state and navigate. The seam between the two runtimes is a package rather than a convention: every string and shape that crosses the browser, the bridge and the agent lives once in @reticlehq/core, and the server parses every inbound socket message against it, closing the connection on malformed input instead of letting it reach logic.

3. 03

   The same protocol over Electron, Tauri and a command line

   The desktop work is where the repository stops being a browser tool. Electron gets an adapter that lives in the main process, with an IPC observer and main-process capture in a preload script of about 11 KB, which is how the boundary between a renderer and its privileged process becomes evidence; the README names that boundary as the thing a browser-only tool cannot see. Tauri gets a Rust capture backend — a crate outside every JavaScript gate, compiled by dedicated CI jobs, with one capture module per operating system — plus a desktop contract file generated by a script and checked by a test. A third realm handles a command-line subject: it spawns and watches the process, puts no code inside it, and renders its own terminal HUD. All three answer to the same protocol package, whose subject vocabulary is deliberately open — web, desktop, mobile, service, game, device, or anything else — on the stated ground that a protocol which must be revised to admit a new kind of computer has an expiry date. The price of that generality is written down beside it: the instance must change when the thing it names is replaced, a navigation invalidates evidence totally while a hot update does so only partially, and both have to be reportable.

4. 04

   The file and line come from the build, and the SDK never ships

   A verdict that names src/checkout/PayButton.tsx and a line is only worth what the mapping is worth, and the mapping is made at build time: three plugins stamp data-reticle-source into the markup — a Babel plugin, a Next adapter that keeps SWC and wraps the config, and the Vite plugin, which also injects the connect call, discovers the dev server port and writes a pairing token. @reticlehq/react maps a DOM node to a component to a source location, and it is optional by design: the project states that the core works without the source-mapping half. The same build step is why the SDK never ships — it applies to the dev server only, a production build replaces it with an inert stub, and a runtime guard refuses to connect when the build reports NODE_ENV=production. That guard also produced a piece of wrong advice the maintainers filed against themselves: issue #1267 records an agent pointed at a deployed URL getting sdk_never_dialled and the hint to run reticle init in the directory, which cannot help, because the stub is deliberate. The other boundaries are properties rather than promises: the bridge binds 127.0.0.1, an app pairs with an owner-only token at ~/.reticle/pairing-token, a non-loopback bind without that token is refused, and passwords, tokens, API keys and card numbers are replaced with [REDACTED] before they reach the agent.

5. 05

   Yes, no, unknown — and the blind spots are published too

   The verdict has three values, and the third is the point: unknown means the evidence could not decide, and the README states that a verdict is never a quiet pass. Evidence is graded in tiers — a signal the app emits is strongest because a wrong element cannot fake it, network plus route plus state is next, DOM or text presence is the weak fallback the tool nudges away from. The protocol turns that into numbered requirements: evidence for a consequence must not come from the channel that performed the action, a disagreement is not a fault unless one of the two channels is independent, and a claim reading a channel nobody declared must be unknown rather than a failure, because “nothing was watching” and “it did not happen” produce identical empty evidence. The same reflex produces the small print: a backgrounded tab warns that timer, rAF and pointer gestures may silently no-op, an evicted buffer reports held and dropped counts, warning that a negative result may be a false negative, and the limits sit beside the strengths — IndexedDB, Web Workers, closed shadow roots and cross-origin iframes are named as unseen, and races around a single action are partial. The measurement behind the grading: on a deterministic corpus a locator that resolves to the wrong element satisfies a presence check but never a consequence check, and that difference is “1 false green in 88” against 29.

6. 06

   Nine tools advertised, forty-five in the table

   The advertised surface is a budget decision rather than a leftover, because MCP re-sends every tool definition to the model on every turn: the tool list is rent, not a menu you pay for once. The table holds 45 tools, the agent is shown nine, and only two of them can produce a verdict — a drive that ends without reticle_act_and_wait or reticle_assert has no result. Most of the rest were merged rather than removed outright. A measurement off a fresh daemon on 2026-09-16 puts the default surface at nine tools and 17,663 bytes against thirty tools and 126,954 bytes with everything advertised. Two tools were promoted out of the cold tail after a measured mistake: reachable only through a generic invoke tool, they left a login form driven one call at a time, because “a tool an agent must already know about is a tool that never gets called”. Trimming further has a floor: an eight-tool cut measurably dropped real-agent accuracy, and the note calls that reading dated evidence rather than proof. Replay is the other half of the budget, and the gate sits on top of it: a recorded flow re-runs with no model, 47 tokens against roughly 120,000 to re-drive it, and the gate exits non-zero unless a passing artifact covers every flow an edit has touched, which the README calls the one check nobody can satisfy by reasoning about their own diff.