Reticle Docs: verification for AI coding agents

reticle_session manages the boundary between the agent and the human watching: hand control back, end the session, narrate what you are doing, and drain the bugs they pinned on elements. reticle_feedback is how you tell the Reticle maintainers that Reticle itself got something wrong. Neither tool touches your app, and neither produces a verdict.

reticle_session

The presenter panel in your app shows a live transcript of what the agent is doing. It reads “live” until the agent says otherwise. So an agent that wanders off without a word leaves a panel claiming work is in progress forever.

Action	What it does
`list`	Which tabs are connected, and whether they can be driven. Your first call. An empty list carries a `why` naming the cause
`feedback`	Tell the maintainers Reticle got something wrong. Takes the fields described under Feedback below
`yield`	Hand control back between turns. `mode: "waiting"` or `"ask"`. Revivable
`end`	The whole task is done. Ends the session for good, and it does not revive. Ending a leased tab also releases the lease
`tune`	Adjust session behaviour: `idleEndMs`, the idle-end window, or `hud`: `hidden`, `shown`, `removed` (until reload), or a corner (`top-left`, `top-right`, `bottom-left`, `bottom-right`) when the HUD covers a control you must test
`resume`	Clear a pause the human applied
`messages`	Drain the human-to-agent inbox
`review`	List, and with `resolve`, retire the mistakes a human pinned to elements
`narrate`	State your intent on the presenter panel, with an optional `level`
`account`	Where the user stands: signed in or not, whether the project reports to the dashboard, plan and credits, whether the Harness is on, and the one thing to do next. Read it before telling the user anything about credits or the plan

{ "action": "yield", "mode": "waiting" }

review returns a real reading rather than a silent empty:

{ "marks": [], "pendingCount": 0 }

Reticle nudges you about all of this. Every response on a long-running session carries a reminder:

"session_age_warning": "Session s223e0fad-e012-43f9-a23d-6d585470c90d has been open for 21 minutes. If your task is complete, call reticle_session{action:\"end\"} now."

And each lease carries the rule in the payload itself:

"session_lease": {
  "IMPORTANT": "When you stop driving, call reticle_session {action:\"yield\", mode:\"waiting\"|\"ask\"}. The panel reads \"live\" until you do. {action:\"end\"} only when the task is done: it is final."
}

Use yield when you pause and might come back: your next action revives the session. Use end only when the whole task is done: it is final, and the panel shows the session as ended.

Feedback

reticle_feedback is not advertised by default. Call reticle_session { action: "feedback", kind, text }: the same fields, routed on action. The old name answers with the new call.

Reticle is built for agents, which creates an unusual problem: the primary user’s experience vanishes the moment its context does. If an agent hits a gap and works around it silently, nobody ever learns the gap existed.

{
  "kind": "bug",
  "text": "What I called, what I expected, what I got, and why Reticle is at fault.",
  "currentApproach": "How I am working around it today.",
  "impact": "What measurably improves if this is fixed."
}

`kind`	Use it when
`bug`	A tool returned a wrong or broken result
`gap`	Reticle could not observe something you needed at all
`ambiguity`	The check ran but you could not tell what the answer meant
`feature_request`	You wished a capability existed
`improvement`	It works, but costs too many calls
`experience`	Something worked notably well (pair it with `rating`, 1-5)

experience is the only kind here that is not a complaint, and that is why it exists. Every other row grows the corpus into a defect list, which says nothing about which parts are worth protecting when we change them. File it unprompted, when you actually notice it, and name the concrete moment: which call, what it saved you, what you would have done instead. The rating is secondary to that text on purpose. A score produced because something asked for one is indistinguishable from a score that was earned, and once both sit in the same column neither means anything. The text is the part that can be acted on or quoted. contact is an email address for a reply from the maintainers. Send only an address that the user typed for this purpose. Never guess one or reuse one from somewhere else. It must be one plain address of at most 254 characters. Anything else is refused with a reason, and nothing is filed. Without contact, no address is sent.

It will tell you when it cannot send

Feedback sends in the background so you are not kept waiting, but it does not pretend to succeed: sent stays false until delivery is confirmed, accepted says the report was validated and queued, and a send that later fails is reported on a later tool result. A report that is not accepted says why:

{
  "sent": false,
  "accepted": false,
  "reason": "this is a Reticle source checkout, where telemetry is disabled by design, so this could not be sent (it has been written to disk instead, and nothing was lost).",
  "savedTo": "<project>/.reticle/feedback/<timestamp>-bug.md",
  "fileWith": "gh issue create --repo reticlehq/reticle --title \"Reticle feedback: bug\" --body-file \"<project>/.reticle/feedback/<timestamp>-bug.md\"",
  "redacted": [],
  "context": {
    "stack": "react",
    "client": "claude-code",
    "runtime": "web",
    "engine": "blink",
    "driver": "cdp",
    "mcpScope": "user"
  },
  "note": "NOT accepted (see reason). Tell the human what you found so it is not lost."
}

redacted names anything stripped from your report before it left the machine, so you can see what was and was not sent. context is the environment attached automatically, which is why a useful report costs one call and no boilerplate. When the report cannot be sent it is written to disk: savedTo is the file and fileWith is a ready-to-run command that turns it into an issue. The instruction in note is the important part: when the report cannot be delivered, say so in your answer to the human rather than letting the finding evaporate.

From the shell, when the tools are unreachable

The setup that failed to finish is exactly the setup that most needs reporting, and in that state the MCP tools do not exist:

npx @reticlehq/server feedback --agent --kind gap "reticle init finished but no session ever connected"

To get a reply, add --contact you@example.com. Use only an address that the user typed for this purpose. Without the flag, no address is sent.

Report defects in Reticle. A bug you find in the app under test is Reticle working correctly, and belongs in your answer to the user. Not in a bug report to us. We get a surprising number of those, and each one is quietly a compliment.

Tools

Beyond the loop

CLI commands

Packages

Grammar

Long form

reticle_session and reticle_feedback

reticle_session

Feedback

It will tell you when it cannot send

From the shell, when the tools are unreachable

​reticle_session

​Feedback

​It will tell you when it cannot send

​From the shell, when the tools are unreachable

reticle_session

Feedback

It will tell you when it cannot send

From the shell, when the tools are unreachable