llms.txt git:20260923.08f4893A

Immutable. This exact content never changes and is served at /api/v1/blob/afef113862375ccf.

# Navvi

> Compile it once so you never drive it again. Navvi is a self-healing scraper compiler: `npx navvi "<prompt>" <url...>` turns a plain-words request and a few URLs into JSON records and a compiled scraper file in one step. `npx navvi make "<prompt>" <url...> --work <dir>` runs the same pipeline staged into eight inspectable phases — spec, sample, investigate, reconcile, schema, determinism, compile, verify — each writing its own artifact into the work directory, re-runnable from any artifact you edit by hand. The first run asks a small number of multiple-choice questions about the page (answered by the host coding agent with no API key, or by Jev / any AI SDK model with one); every later run replays the compiled scraper with zero model calls and heals a moved field or a renamed button instead of failing. Secrets stay in the environment, logins use a local browser profile, and the tool never solves captchas or runs model output as code.

## Start here

- [SKILL.md](SKILL.md): the agent skill. The one command, the no-key question protocol on stdio, the file-and-resume path (exit 3), input contract, output shape, exit codes and limits.
- [README: Install and run](README.md#install-and-run): four lines from zero to data.
- [README: What you get](README.md#what-you-get): records, the scraper JSON you can commit, the zero-model second run.
- [README: Before the compile](README.md#before-the-compile-navvi-spec-and-navvi-heuristics): `navvi spec` (a brief into a spec, with what the brief left unsaid as open questions) and `navvi heuristics` (the rules that decide what a model is even asked). Neither reads a page.
- [README: `navvi make`](README.md#navvi-make-the-driver): the driver — one whole compile as eight artifacts in a work directory, staleness tracked by content hash rather than mtime, and what "fewer fields than requested" means in `reconcile.md` and `scorecard.md`.
- [README: Choosers](README.md#choosers): claude and codex (an installed, signed-in CLI on your subscription), jev, model, agent (no key), and what each needs.
- [README: Exit codes](README.md#exit-codes): what each status means and what to do next.
- [README: Limits](README.md#limits): drift versus redesign, captchas, logins and secrets.

## Reference

- `npx navvi --help`: every flag in one screen, including `make`'s.
- `storage/key_value_stores/scraper-cache/<cacheKey>.json`: the compiled scraper produced by a plain run.
- `storage/questions/<token>.json`: a parked question batch waiting for `--answers <file> --resume <token>`.
- `<work>/make.json`: `navvi make`'s ledger — the digest of what each stage read, used to decide whether it must run again.
- [docs/architecture.md](docs/architecture.md): the modules under `src/`, what each one owns, the import graph between them, the known cycles and the two orphans. Generated from the code and checked in CI.
- [docs/measurements.md](docs/measurements.md): questions, wait time and cost with and without Jev on the same pages.
- [LICENSE](LICENSE): MIT.