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