Webnav

webnav

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):

$ 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 (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/ — 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.
• Teach mode — flip to Teach and demonstrate a task by hand once; it becomes a named, deterministic route any agent can walk (typed values never leave the browser).

Try it (needs the local server for the zero-LLM navigation + recording):

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.

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)

# 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, record a session yourself, or use the Chrome extension below. For development, map packs, and contributing from source:

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:

{ "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:

  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`](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/`](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 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