> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reticle.sh/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Reticle is a dev-only, localhost-only verification layer for AI coding agents. It reads program truth (network, state, console, routing, animations, framework state) from inside a running web app and returns a deterministic verdict with evidence. It is not a screenshot tool and not a browser automation library.
> Only `reticle_act_and_wait` and `reticle_assert` produce a verdict. Every other tool moves or reads the app and proves nothing. A drive that ends without one of those two has no result, however many tools it used.
> A verdict of `verified: "unknown"` is not a pass. It means Reticle drove the app and could not tell what happened. Report it as unknown; never weaken a check to make it pass.
> Package names are scoped `@reticlehq/*` and the CLI is `reticle`. Install with `npx reticle init`. The complete tool surface is on the `/usage` page; `/agent-cheatsheet` is the one-screen version.

# reticle_observe

> The full timeline of everything the app did in a window. DOM, network, routing, console, animations and signals, with a summary.

`reticle_observe` is the wide-angle lens. Where `reticle_network` and `reticle_console` answer one question each, `observe` returns everything that happened in a window, in order.

## Example

```json theme={"dark"}
{ "window_ms": 4000, "max_events": 4 }
```

Real response:

```json theme={"dark"}
{
  "window_ms": 4000,
  "events": [
    {
      "t": 925870,
      "type": "page.health",
      "seq": 586,
      "data": {
        "hidden": true,
        "focused": false,
        "runtime": "web",
        "engine": "blink",
        "brand": "chrome",
        "reason": "heartbeat"
      }
    }
  ],
  "summary": {
    "total": 1,
    "network": 0,
    "domAdded": 0,
    "domRemoved": 0,
    "domChanged": 0,
    "routeChanges": 0,
    "consoleErrors": 0,
    "animations": 0,
    "signals": 0
  },
  "cost": { "events": 1, "bytes": 374 }
}
```

A quiet window, honestly reported as quiet.

## Read the summary first

The `summary` block is the cheap answer. `consoleErrors: 0` and `network: 0` tells you most of what you need without reading a single event. Pull the timeline only when the summary says something interesting happened.

## Arguments

| Argument          | What it does                                                       |
| ----------------- | ------------------------------------------------------------------ |
| `window_ms`       | How far back to look                                               |
| `since` / `until` | Cursors from a prior act. The precise way to scope                 |
| `actionId`        | Only events attributed to one action: "what did that click cause?" |
| `filters`         | Event-type allowlist. The cheapest way to shrink a big timeline    |
| `max_events`      | Cap the timeline to the most recent N                              |

## Scope by cursor, not by clock

Every `reticle_act` response includes a `since` cursor. Passing it to `observe` scopes the timeline to exactly what followed that action, with no guessing about how many milliseconds to look back:

```json theme={"dark"}
{ "since": 28123 }
```

This is more precise than `window_ms` and it does not drift when the machine is slow. Which matters, because a timing-based window that works on your laptop and fails in CI is a flaky test waiting to happen.

## When to use it

Use `observe` when you do not yet know what went wrong. Use the narrow tools when you do.

<CardGroup cols={2}>
  <Card title="Good use" icon="circle-check">
    "Something broke after that click, show me everything that happened."
  </Card>

  <Card title="Wasteful use" icon="circle-xmark">
    "Did a POST fire?" [`reticle_network`](/tools-network) answers that far more cheaply.
  </Card>
</CardGroup>

<Note>`observe` reads. It does not produce a verdict. It is for diagnosis, not proof.</Note>