> ## 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/*`. Run every CLI command as `npx @reticlehq/server <command>`, for example `npx @reticlehq/server init`. `reticle` is a bin name that `@reticlehq/server` installs once it is on your PATH, NOT a package on npm: `npx reticle` fetches an unrelated package published by somebody else, so never run that. The complete tool surface is on the `/usage` page; `/agent-cheatsheet` is the one-screen version.

# reticle hunt

> Aggregate many crawl reports into one false-green rate across already-merged changes.

`reticle hunt` is arithmetic, not driving. You point it at a directory of crawl reports (one JSON file per checkout, each produced by `reticle_crawl`) and it turns the pile into the one number the core claim needs: across N already-merged, already-green changes, how many carried a candidate false green?

```bash theme={"dark"}
npx @reticlehq/server hunt <dir-of-crawl-reports>
```

No control arm is needed. Those changes shipped, so the counterfactual is already established.

## Arguments

| Argument | Type                             | Default | What it does                                                                  |
| -------- | -------------------------------- | ------- | ----------------------------------------------------------------------------- |
| `<dir>`  | string, positional, **required** | none    | Directory of `*.json` crawl reports. Each file is one crawl over one checkout |

Each input file is read for `label` (falling back to the filename), `anomalies[]`, and `stepsRun`.

## What it prints

One `reticle_hunt` line with the summary:

| Field                    | Meaning                                                                                                                                                                            |
| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `runs`                   | Report files read                                                                                                                                                                  |
| `runsWithCoverage`       | Runs that drove at least one control. The only honest denominator: a run that drove nothing is not evidence of cleanliness                                                         |
| `runsWithContradictions` | Runs with at least one cross-channel contradiction                                                                                                                                 |
| `contradictions`         | Total contradictions. The kinds are `ui-advanced-request-failed`, `signal-contradicted`, `response-ignored`, `duplicate-request`, `request-never-settled`, `failure-misattributed` |
| `singleChannelFaults`    | Everything else: console errors, failed requests, dead controls. Context, not the claim                                                                                            |
| `byKind`                 | Counts per anomaly kind                                                                                                                                                            |
| `flagged`                | The labels with contradictions, so each can be confirmed by hand                                                                                                                   |
| `headline`               | A sentence phrased so it cannot overstate itself. It says "candidate", because every flag still needs manual confirmation                                                          |

## Exit codes

Always `0`. A read failure is logged as `reticle_hunt_failed`. Omitting the directory is a usage error:

```
{"t":"2026-08-14T19:38:47.116Z","event":"reticle_usage_error","message":"usage: reticle hunt <dir-of-crawl-reports>"}
```

That path exits `1`.

## Worked example

```bash theme={"dark"}
for sha in $(git log --format=%H -n 30 main); do
  git checkout "$sha" && npm run dev &
  # drive reticle_crawl over the app, write the JSON:
  # .../reports/$sha.json
done
npx @reticlehq/server hunt ./reports
```