# webnav [Health: Active]
**Category:** π» Developer Tools
**Repository:** https://github.com/lucyfuur94/webnav-core
**GitHub Stars:** 0
**Views:** 0
**Installs:** 0
**Upvotes:** 0
**Directory Page:** https://allmcps.com/mcp/webnav
## Description
A zero-LLM MCP server that replays recorded site maps instead of re-exploring browser routes.
## Claude Desktop Quick Installation
Heuristic fallback β verify the package name and runner against the repository README before running it. Uses `npx` (confidence: low):
```json
"mcpServers": {
"webnav": {
"command": "npx",
"args": ["-y","webnav"]
}
}
```
## Documentation & README
# webnav
[](https://github.com/lucyfuur94/webnav-core/actions/workflows/ci.yml)
[](LICENSE)
[](https://www.typescriptlang.org/)
[](CONTRIBUTING.md)
**Stop your web-browsing AI agent from re-exploring the same sites every run.** Your agent maps
a website **once** β then travels it forever with `webnav walk`: deterministic, zero-LLM,
page-to-page autopilot that pauses only at genuine forks (what to buy, an irreversible button)
and hands the wheel back. It's a **reusable site map, not page compression** β most token-saving
tools shrink what the agent *reads*; webnav remembers *where things are* so it stops re-finding
the route. webnav is the map and the mechanics; the agent keeps all the judgment.
## See it
A real run against saucedemo's full checkout flow (map + credentials already recorded):
```console
$ webnav walk --start www.saucedemo.com:login --goal www.saucedemo.com:checkout-overview
{ "status": "needs-navigation",
"semanticStep": "open the shopping cart",
"question": "before \"open the shopping cart\", fire these in-page affordances: aff_addcart",
"snapshot": "β¦", "session": "walk-w-β¦", "browserSession": "w-β¦" }
# ^ paused at a REAL fork: webnav won't decide what you buy. The agent picks from the snapshot:
$ webnav use click e54 --session w-β¦ # add-to-cart β the agent's one judgment call
$ webnav walk-resume walk-w-β¦ --ref e124 # continue; e124 = the icon-only cart badge
{ "status": "done", "cost": { "playwright_calls": 12 } }
```
**4 agent-visible CLI calls**, login β inventory β cart β checkout form (**auto-filled from
locally-stored creds** β never in the map) β overview. 12 browser actions underneath, zero
agent tokens spent on navigation.
In our [navigation benchmark](https://github.com/lucyfuur94/webnav-core/blob/HEAD/bench/results/2026-06-13-nav-v2.md) (both arms on Haiku, the same
browser underneath), on a deep multi-step route **`walk` used ~3Γ fewer agent steps than an agent
ad-hoc-driving the raw browser β median 6 calls vs 18 β and reached the goal more reliably (3/3 vs
2/3).** Honest caveat, also in that file: the win shows up on *deep, reliably-walked* routes; on
shallow 1β2-hop routes, or when the agent falls back to manual driving, the two tie. webnav helps
most exactly where ad-hoc driving hurts most β the long, repeated journeys.
## Drive a tab from a side panel (Chrome extension)
There's also a Chrome extension in [`webnav-extension/`](https://github.com/lucyfuur94/webnav-core/blob/HEAD/webnav-extension/) β a docked side
panel where you type a goal and watch the agent drive your **active tab** (read / click / type /
scroll, via `chrome.debugger`/CDP), on your own Claude Code subscription. It **recalls first**
(`list_routes` β `check_route`) so a site you've mapped is replayed, not re-explored β and every
run is recorded back into the map, so the *next* time is the cheap deterministic `walk`.
- **Ask** (approve a plan first) or **Act** (run on its own); irreversible steps (pay / place
order / delete) always pause for you.
- **Watch every step** β narration + the tool trail render live; a cursor glides to each action.
- **Take over** any time, drive by hand, hand back.
**Try it** (needs the local server for the zero-LLM navigation + recording):
```console
cd webnav-extension && npm i && npm run build # emits the *.js next to *.ts
webnav dev agent-serve --port 7779 # prints a token β paste it into the panel
```
Then `chrome://extensions` β Developer mode β **Load unpacked** β pick `webnav-extension/`,
open the panel (toolbar icon or **β/Ctrl-E**), paste the token, and type a goal. Runs show up on
the dashboard tagged **Extension**. Full walkthrough: [`webnav-extension/README.md`](https://github.com/lucyfuur94/webnav-core/blob/HEAD/webnav-extension/README.md).
## Why
Web agents re-discover the same websites every single day, paying the same token bill every
time: snapshot β reason β click β snapshot. For sites you (or your agents) use repeatedly β
internal tools, automation testing, back-office workflows β that navigation should be
**remembered, not re-reasoned**. webnav stores the durable *intent* of each step, replays it
deterministically, self-heals when the site drifts, and **never** auto-fires an irreversible
action: commit points always pause for the agent (or you) to decide.
## Quickstart (β2 minutes to a working walk)
```bash
# Node 18, 20, or 22
npm install --global @playwright/cli@latest @dikshanty94/webnav@latest
# A complete Saucedemo map ships with webnav. Credentials stay local on your machine.
webnav creds set www.saucedemo.com username=standard_user password=secret_sauce
webnav walk --start www.saucedemo.com:login \
--goal www.saucedemo.com:checkout-complete --headless
# β webnav drives the known route and pauses before irreversible decisions.
webnav dev list # inspect the local map store
```
The seeded Saucedemo map is a working example. To map **your own** site, hand an agent the prompt in
[`docs/LEARNING-A-SITE.md`](https://github.com/lucyfuur94/webnav-core/blob/HEAD/docs/LEARNING-A-SITE.md), record a session yourself, or use the Chrome
extension below. For development, map packs, and contributing from source:
```bash
git clone https://github.com/lucyfuur94/webnav-core
cd webnav-core
npm install && npm link # source checkout: runs current TypeScript via tsx
webnav --help # the tool menu (a peer of playwright-cli)
npm test # unit tests (+ gated browser e2e)
npm run build # tsc -> dist/ (only for the published build; the CLI runs src directly)
```
**Using it from an MCP client (Claude Desktop/Code, etc.)** β webnav serves every verb as an MCP
tool over stdio, so your agent gets `walk`/`use`/`search`/β¦ natively, no shelling out. One line:
```json
{ "mcpServers": { "webnav": { "command": "webnav", "args": ["mcp"] } } }
```
## How the map grows (start here if you're new)
webnav is a **map** β and a fresh install is **not** blank, but it is small. Here's
honestly what you get and how it grows, so there are no surprises:
- **What ships, out of the box.** The first time you run any verb, webnav seeds a shared
map at **`~/.webnav/webnav.db`** (per-user, shared across every terminal/folder on the
machine β *not* a per-directory file). It comes pre-seeded with **one** worked example:
**saucedemo.com** β a full loginβbrowseβcartβcheckout `walk` map. This works immediately:
```bash
webnav walk --start www.saucedemo.com:login \
--goal www.saucedemo.com:checkout-complete # saucedemo, seeded
```
Nothing else is seeded β webnav is a blank-slate map tool, and saucedemo is the single
example that proves it works. **You record your own sites** (see below); that's the
product. This fits any flow you repeat against the same site: automation testing,
internal tools, back-office workflows, recurring agent tasks. (An earlier GitHub-recall
+ internet-graph engine β the v1 proof-of-engine β was removed from the tree 2026-06-13;
it lives in git history if that surface ever returns.)
- **The map persists and self-heals.** It's saved to `~/.webnav/webnav.db` and reused on
every run β you do **not** rebuild it each time. When a remembered step drifts (a renamed
or moved element), a `walk` escalates once for the agent to pick the element, then **writes
the fix back** so the next run resolves it deterministically (principle #3). Routes you use
stay fresh. Credentials for login-gated sites live **outside** the
map, locally, at `~/.webnav/credentials.json` (chmod 600) β never in the DB, never shared.
- **Mapping a NEW site β hand your AGENT the learn prompt.** webnav is built for agents, so you
don't map by hand: you give an agent (even a cheap one β we use Haiku) the reusable prompt in
**[`docs/LEARNING-A-SITE.md`](https://github.com/lucyfuur94/webnav-core/blob/HEAD/docs/LEARNING-A-SITE.md)** and let it run autonomously. It drives the
site once through webnav's `use` primitives while recording, then `dev graph-analyse --draft` folds
that into a SELF-VERIFIED map (absolute URLs, unique element fingerprints, the in-page affordance
repertoire, the declared domain shadow) which it persists with `dev graph-edit`. No hand-authoring
of fingerprints or URLs. (That prompt learned the seeded OrangeHRM map β login + 11 modules,
exercised β in a single one-shot run.) Re-learn cleanly with `dev node-clear`.
- **Or skip learning β import a map pack someone already made.** A map travels as a pack, so only the
first person learns a site. `webnav dev import-map ` loads a site's skeleton; set your own
login with `dev creds set` (packs are skeleton-only, never carry credentials). Two packs ship in
**[`mappacks/`](https://github.com/lucyfuur94/webnav-core/blob/HEAD/mappacks/)** (saucedemo, OrangeHRM); `dev export-map ` makes your own to share.
- **Or record a site by browsing it yourself.** No agent needed: run `webnav dev record-live
--session S --url ` β it opens a headed browser at that URL, and you click through the
flow naturally. Every action you take is captured (real playwright a11y snapshots, never typed
values β only which field changed) into the same session store the agent-record path uses. Stop
with Ctrl-C or `webnav dev record-stop --session S`, then it's the same `dev graph-analyse
--draft` β `graph-edit` β `walk` pipeline.
- **Or drive + record from the Chrome extension** β the [side panel](#drive-a-tab-from-a-side-panel-chrome-extension)
above: give the agent a goal, it drives your active tab (recalling known routes first), and the
run is captured back into the map. (An earlier extension *capture-only* path that approximated the
a11y tree from the raw DOM is retired β it broke on SPAs; the current extension captures via real
CDP accessibility instead. `dev ingest` still exists as that legacy receiver.)
- **Inspect what you have** anytime: `webnav dev dashboard` (a localhost operator UI). Its
**Sessions** tab lists every recorded run β tagged by source (**Extension** / **Agent** /
**Manual**), with a filter, step counts, and a Verified badge β plus record-by-clicking + replay:
Or the text views `dev outline ` / `dev mermaid `.
**TL;DR:** out of the box you can `walk` saucedemo; everything else you map yourself. Same
machine + a mapped site β instant, cached, self-healing. A brand-new site β you (or your
agent) record it once first.
## Verbs
```
# Travel a map you've built (the core win: deterministic, low-token replay)
webnav walk --start --goal autopilot a multi-step route; pauses at genuine forks
webnav walk-resume --ref|--classify answer a paused walk's fork and continue
webnav creds set key=value... store login/form creds locally (~/.webnav, chmod 600)
# Drive a live browser one step at a time (explore/build; each step recordable)
webnav use navigate --session S open a URL (records a landing if S is recording)
webnav use snapshot --session S read the page + element refs (never records)
webnav use click [ / use type ][ act on a ref; records the before/after effect
webnav read [--raw] open a URL -> distilled content
webnav search "" [--top N] open-web search -> extracted evidence
webnav eval "" | network targeted JS extraction | the page's API calls
# Author a site's map (the record -> analyse -> edit flow)
webnav dev record-start / record-stop bracket a mapping session
webnav dev record-live --session S --url U headed browser; click through it yourself, webnav records
webnav dev agent-serve [--port 7779] local server the Chrome extension drives (SSE + CDP); records each run
webnav dev ingest [--port 7778] legacy receiver for the retired DOM-capture extension path
webnav dev graph-analyse --session S [--draft] mechanical structure from what you recorded
(--draft = a self-verified, ready-to-edit graph spec)
webnav dev graph-edit --node --graph J write the validated graph
webnav dev effects --session S the RAW recorded before/after snapshots
webnav dev outline | mermaid completeness check | renderable diagram
webnav dev graph-show --node a site's stored states + edges (JSON)
webnav dev export-map a site's map pack as JSON (skeleton only, no creds)
webnav dev dashboard [--port N] local operator UI: sites + JSON map + credentials
webnav dev list the sites you have maps for + state counts
webnav dev node-clear / node-rm --node empty a site's map (re-learn) / delete it entirely
webnav dev node-add / edge-add / capture teach + inspect helpers
```
`webnav --help` for details. Output is JSON on stdout; exit 0 ok / 2 error / 3 empty.
### MCP server
`webnav mcp` serves every verb as an MCP tool over stdio β point an MCP client at it and
agents get the verbs natively (no shelling out). Tools are generated from the same command
registry as `--help`, and every call runs the real CLI, so the two surfaces can't drift:
```json
{ "mcpServers": { "webnav": { "command": "webnav", "args": ["mcp"] } } }
```
Consumer verbs can also be invoked canonically as `webnav use ...` and map-authoring verbs as `webnav dev ...`; bare consumer verbs (e.g. `webnav read ...`) still work too.
### Inspect a site's map
The map is for the calling AGENT (walk), not a human dashboard. To inspect
what's captured, use the text views β no UI:
```bash
webnav dev outline www.saucedemo.com # top-to-bottom states + affordances + completeness cues
webnav dev mermaid www.saucedemo.com # paste into GitHub/mermaid.live to render
webnav dev graph-show --node # raw JSON
```
## Architecture (one CLI, three components, ZERO LLM)
- **Explorer** β reads a site's declared structure (observe-first), folds a recording into a
self-verified map draft (states, typed affordances, the declared domain shadow), recognizes states.
- **MapStore** β SQLite persistence: states (+ affordances + declared shadow), projected edges, the
site-node index, and record sessions.
- **Router** β walks a route, replays it (cached selector β deterministic fingerprint re-resolve),
self-heals, returns evidence OR a `needs-navigation`/`needs-classification` "your move" response for
the agent. Never judges, never calls an LLM.
## Source map (`src/`)
```
cli.ts, cli-spec.ts, cli-help.ts CLI: parsing, command registry, help rendering
protocol.ts, contract.ts walk response types Β· published @dikshanty94/webnav types
paths.ts, creds.ts, hosted.ts ~/.webnav paths Β· local credential store Β· remote-map client
mcp/ server.ts `webnav mcp`: every verb as an MCP tool (generated from cli-spec)
mapstore/ types.ts, store.ts, record.ts, schema.sql SQLite persistence (states+affordances+shadow, edges, nodes, node_edges, record sessions)
playwright/ adapter.ts, snapshot.ts, capture.ts, fingerprint.ts, sessions.ts, throttle.ts playwright-cli child-process Β· a11y snapshot parser Β· element fingerprints Β· session guardrails
explorer/ analyse.ts, diff.ts, draft.ts, shadow.ts, fingerprint.ts, fingerprint-page.ts analyse a recording β self-verified draft (affordances + declared domain shadow) + state recognition
router/ resolve.ts, replay.ts, path.ts, walk.ts, walk-live.ts, walk-session.ts deterministic resolve/replay + interactive multi-step walk + pathfinding
readiness.ts, extract.ts, extract-content.ts, tokens.ts, browse.ts, read.ts bot-wall detection Β· signal/content extraction Β· token-savings Β· page reading
search.ts, search-providers.ts, search-live.ts multi-provider open-web search
catalog.ts dev list (the map index)
graph/ seed.ts, teach.ts, edit.ts, show.ts, coverage.ts map authoring + inspection (saucedemo seed, graph-edit, graph-show, outline/mermaid)
dashboard/ server.ts, shell.ts `webnav dev dashboard` local operator UI
```
Tests mirror this under `tests/`. The live e2e walk tests are gated behind `WEBNAV_LIVE=1`.
## Principles (full list in CLAUDE.md)
1. Observe first, traverse rarely. 2. Never traverse a declared commit point. 3. Store durable
semantic routes; cache selectors. 4. Usage-learned weights are a hosted-service concern. 5. The map
surfaces evidence; the **agent** judges. **5a. ZERO LLM in webnav** β all reasoning offloaded to
the calling agent via a call-and-response protocol. 6. The map is a use-case-independent
navigation skeleton; goals declare signal interests. **Never evade bot-walls** β detect + escalate.
## Status
All current work is merged to `main`, tests green. See **`docs/STATUS.md`** for the live
checklist, pending work, and known limitations; **`CLAUDE.md`** holds the settled design,
mental model, and principles. Design docs: `docs/superpowers/specs/`.
## Contributing
PRs welcome β see [`CONTRIBUTING.md`](https://github.com/lucyfuur94/webnav-core/blob/HEAD/CONTRIBUTING.md) (the settled principles, dev setup, and how
to contribute a **site map or map pack** β the highest-leverage contribution). Map packs are
skeleton-only and never include credentials; the shipped examples are in [`mappacks/`](https://github.com/lucyfuur94/webnav-core/blob/HEAD/mappacks/).
Report security issues privately per [`SECURITY.md`](https://github.com/lucyfuur94/webnav-core/blob/HEAD/SECURITY.md). Be excellent to each other:
[`CODE_OF_CONDUCT.md`](https://github.com/lucyfuur94/webnav-core/blob/HEAD/CODE_OF_CONDUCT.md).
## License
[Apache License 2.0](https://github.com/lucyfuur94/webnav-core/blob/HEAD/LICENSE). Free to use, modify, and redistribute (including commercially)
**with attribution**: retain the copyright notice and the [`NOTICE`](https://github.com/lucyfuur94/webnav-core/blob/HEAD/NOTICE) file. Includes an
explicit patent grant. Copyright 2026 Dikshant Yadav.
]