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.

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: