Reticle Docs: verification for AI coding agents

reticle_network is not advertised. The default surface is the merged ten, so an agent does not see this name. Call reticle_observe { action: "network" } instead. Everything below describes what that call does; only the spelling changed. A call to the old name is answered with the new one, but an allowedTools allowlist or an MCP permission rule naming it refuses before Reticle is asked.

reticle_network returns a filtered log of every request the app made, with status, timing, and automatic credential redaction. Request and response bodies are recorded only when the app connects with captureNetworkBodies: true (off by default); a failed response keeps its body either way. Reach for it to answer “did that call actually fire, and what came back?”, which is the thing a screenshot fundamentally cannot show.

Example

{ "limit": 3, "bodies": true }

Real response with bodies: true, with the second call’s headers block trimmed off:

{
  "calls": [
    {
      "method": "POST",
      "url": "http://localhost:8787/api/login",
      "status": 401,
      "statusText": "Unauthorized",
      "contentType": "application/json; charset=utf-8",
      "responseSize": 37,
      "requestBody": "{\"email\":\"admin@reticle.dev\",\"password\":\"[REDACTED]\"}",
      "responseBody": "{\"error\":\"invalid email or password\"}",
      "ms": 23
    },
    {
      "method": "POST",
      "url": "http://localhost:8787/api/login",
      "status": 200,
      "statusText": "OK",
      "contentType": "application/json; charset=utf-8",
      "responseSize": 67,
      "requestBody": "{\"email\":\"admin@reticle.dev\",\"password\":\"[REDACTED]\"}",
      "responseBody": "{\"token\":\"[REDACTED]\",\"user\":{\"email\":\"admin@reticle.dev\"}}",
      "ms": 4
    }
  ],
  "buffer": {
    "held": 535,
    "dropped": 10,
    "note": "event buffer evicted older events (age/size cap): a negative result here may be a false negative; the evidence may have expired. Grade sooner or widen the buffer."
  },
  "cost": { "bytes": 1133, "tokens": 284 }
}

Two attempts at the same login, the first rejected and the second accepted, with the server’s own error text attached to the failure. That is the whole diagnosis in one read.

Redaction is automatic

Look at requestBody. The password is [REDACTED] and so is the returned token, without anyone configuring anything. Reticle strips credential-shaped values before they leave the page, so neither your agent’s context nor any transcript of it ever holds them. The email is not redacted, because an email is not a credential. The line is drawn at secrets.

The buffer note is the important bit

"buffer": { "held": 535, "dropped": 10, "note": "…the evidence may have expired…" }

Reticle keeps a bounded event buffer. When it overflows, older events are evicted. And if you then ask “did a POST to /api/orders happen?”, the honest answer is not “no”. It is “not in what I still have.” Most tools would return an empty array and let you draw the wrong conclusion. This one tells you the result may be a false negative and suggests grading sooner or widening the buffer. Take that note seriously: a confident “no requests fired” built on evicted evidence is exactly the kind of false green Reticle exists to prevent.

Filters

Argument	What it does
`urlContains`	Substring the URL must contain
`method`	`GET` · `POST` · `PUT` · `DELETE` · `PATCH`
`status`	Exact status code, e.g. `500`
`ok`	`false` keeps only failures. The fastest way to “did anything break?”
`limit`	Most recent N. Older matches are dropped and counted
`actionId`	Only requests attributed to one action: “what did that click request?”
`since` / `until`	Cursors from a prior act, to scope to a window between two actions
`bodies`	Omitted: keep a body only where it can decide a verdict (failures, unscored calls, calls your filter named), and report the rest in `bodiesWithheld`. `true`: every captured body. `false`: no bodies
`assets`	`true` lists the dev server’s own successful asset requests. Omitted: they are folded into `assetsFolded`

Catching a double submit

The bug where one click fires two POSTs is invisible on screen and obvious here:

{ "urlContains": "/api/orders", "method": "POST" }

If calls has two entries with near-identical timestamps, you have found it. Better still, assert it up front so the agent cannot rationalise it afterwards. reticle_act_and_wait accepts an exact count predicate, which turns “roughly one request” into a check that fails at two.

A zero-match filter says what did fire

That exact call, on a fixture that never touches /api/orders, comes back diagnosable rather than blank:

{
  "calls": [],
  "hint": {
    "totalInWindow": 1,
    "present": [{ "method": "POST", "url": "http://localhost:8787/api/login", "status": 200 }]
  },
  "buffer": { "held": 1, "dropped": 281, "note": "…the evidence may have expired…" },
  "cost": { "bytes": 328, "tokens": 82 }
}

hint.present is the difference between “your endpoint never fired” and “you filtered on the wrong URL”. Read it before you go looking in the app.

Checking that nothing fired

{ "ok": false } keeps only the calls that failed, so an empty result there is a genuinely useful answer: nothing broke. Provided the buffer note says nothing was dropped. Read both. Desktop IPC (ipc://) has no status code, so its 200 and 500 are derived. Filter those on ok rather than status.

Prove it, don't just look at it

reticle_network reads. It does not produce a verdict. Name the expected request in reticle_act_and_wait instead.

Tools

Beyond the loop

CLI commands

Packages

Grammar

Long form

reticle_network

Example

Redaction is automatic

The buffer note is the important bit

Filters

Catching a double submit

A zero-match filter says what did fire

Checking that nothing fired

Prove it, don't just look at it

​Example

​Redaction is automatic

​The buffer note is the important bit

​Filters

​Catching a double submit

​A zero-match filter says what did fire

​Checking that nothing fired

Prove it, don't just look at it

Example

Redaction is automatic

The buffer note is the important bit

Filters

Catching a double submit

A zero-match filter says what did fire

Checking that nothing fired