webnav

webnav

ウェブ閲覧を行う AI エージェントが、実行のたびに同じサイトを再探索するのを防ぎます。 エージェントはウェブサイトを一度だけマッピングすれば、あとは webnav walk で何度でも移動できます。決定論的で LLM 不要のページ間自動操縦機能は、本当に選択が必要な分岐（何を買うか、取り消せないボタンなど）でのみ停止し、操作をエージェントに戻します。これはページ圧縮ではなく、再利用可能なサイトマップです。多くのトークン節約ツールはエージェントが読む内容を縮小しますが、webnav は場所を記憶することで、経路を再発見する必要をなくします。webnav が担うのは地図と移動の仕組みであり、判断はすべてエージェントに委ねられます。

実際の動作を見る

saucedemo のチェックアウト全体を対象にした実行例（マップと認証情報は記録済み）：

$ 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 } }

エージェントから見える CLI 呼び出しは 4 回です。ログイン → 商品一覧 → カート → チェックアウトフォーム（ローカル保存済みの認証情報から自動入力 — マップには保存されません）→ 注文概要。内部ではブラウザー操作を 12 回行いますが、ナビゲーションにエージェントのトークンは消費されません。

ナビゲーションベンチマーク（両方式とも Haiku を使用し、同じブラウザーを使用）では、複数の手順からなる長い経路で、walk はエージェントがブラウザーを場当たり的に操作する場合と比べて、エージェントの手順数が約 3 分の 1 でした。中央値は 6 回対 18 回で、目標への到達率も高くなりました（3/3 対 2/3）。 ただし、同じファイルに記載されているとおり、効果が見られるのは長く、安定してたどれる経路です。1〜2 ホップの短い経路や、エージェントが手動操作に切り替えた場合は、両方式に差はありません。webnav が最も役立つのは、場当たり的な操作が最も難しい場面、つまり長く何度も繰り返す移動です。

サイドパネルからタブを操作する（Chrome 拡張機能）

webnav-extension/ には Chrome 拡張機能もあります。ドッキング式のサイドパネルに目標を入力すると、Claude Code のサブスクリプションを使って、アクティブなタブを操作するエージェントの様子を確認できます（chrome.debugger/CDP を介した読み取り／クリック／入力／スクロール）。エージェントはまず再利用できる経路を確認し（list_routes → check_route）、マッピング済みのサイトを再探索せずに再実行します。また、実行内容は毎回マップに記録されるため、次回は低コストで決定論的な walk を利用できます。

• Ask（最初に計画を承認）または Act（自動実行）を選べます。支払い／注文／削除など、取り消せない操作は必ず一時停止して確認を求めます。
• すべての手順を確認できます。説明とツールの操作履歴がリアルタイムに表示され、カーソルが各操作へ移動します。
• いつでも操作を引き継ぎ、手動で操作してから、エージェントに戻せます。
• Teach モード — Teach に切り替えて、タスクを一度手動で実演します。実演内容は名前付きの決定論的な経路となり、どのエージェントからも walk で実行できます（入力値がブラウザーの外に出ることはありません）。

お試しください（LLM 不要のナビゲーションと記録にはローカルサーバーが必要です）：

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

次に chrome://extensions → デベロッパーモード → パッケージ化されていない拡張機能を読み込む → webnav-extension/ を選択し、パネルを開き（ツールバーアイコンまたは ⌘/Ctrl-E）、トークンを貼り付けて目標を入力します。実行結果はダッシュボードに Extension タグ付きで表示されます。詳しい手順は webnav-extension/README.md をご覧ください。

理由

Web エージェントは毎日同じウェブサイトを再発見し、そのたびに同じトークンコストを支払います。スナップショット → 推論 → クリック → スナップショット。あなた（またはエージェント）が繰り返し使うサイト（社内ツール、自動テスト、バックオフィスのワークフローなど）では、ナビゲーションは再び推論するのではなく、記憶されるべきです。webnav は各ステップの永続的な意図を保存し、決定論的に再生し、サイトに変化があれば自己修復します。また、取り消し不可能な操作を自動実行することは決してありません。確定ポイントでは、エージェント（またはあなた）が判断できるよう、必ず一時停止します。

クイックスタート（約 2 分でウォークを実行）

# 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

用意されている Saucedemo マップは、実際に動作するサンプルです。独自のサイトをマッピングするには、エージェントに docs/LEARNING-A-SITE.mdのプロンプトを渡すか、自分でセッションを記録するか、以下の Chrome 拡張機能を使ってください。開発、マップパック、ソースからの貢献については、次をご覧ください。

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)

MCP クライアント（Claude Desktop/Code など）から使用する場合 — webnav はすべての動詞を stdio 経由の MCP ツールとして提供するため、エージェントはシェルを介さずにwalk/use/search/…をネイティブに利用できます。1 行で設定できます。

{ "mcpServers": { "webnav": { "command": "webnav", "args": ["mcp"] } } }

マップの成長方法（初めての方はここから）

webnav はマップです。新規インストール時に空ではありませんが、小規模です。予想外のことがないよう、何が用意されているのか、そしてどのように成長するのかを率直に説明します。

• 初めから利用できるもの。 いずれかの動詞を初めて実行すると、webnav は共有マップを ~/.webnav/webnav.db に作成します（ユーザーごとに作成され、マシン上のすべてのターミナル／フォルダーで共有されます。ディレクトリごとのファイルではありません）。あらかじめ用意されている実例は 1つ です。saucedemo.com のログイン→閲覧→カート→チェックアウトを網羅した walk マップです。すぐに動作します。

  webnav walk --start www.saucedemo.com:login \
              --goal www.saucedemo.com:checkout-complete      # saucedemo, seeded
  

  これ以外にあらかじめ用意されているものはありません。webnav はまっさらな状態から使うマップツールで、動作を実証する唯一の例が saucedemo です。自分のサイトは自分で記録します（下記参照）。それがこの製品の使い方です。同じサイトで繰り返すあらゆるワークフローに適しています。たとえば、自動化テスト、社内ツール、バックオフィスのワークフロー、エージェントが定期的に行うタスクなどです。（以前の GitHub の想起とインターネットグラフを組み合わせたエンジン（エンジンの v1 実証版）は、2026-06-13 にリポジトリから削除されました。この機能が再び登場する場合に備え、Git の履歴に残っています。）

• マップは保持され、自己修復します。 マップは ~/.webnav/webnav.db に保存され、実行のたびに再利用されるため、毎回作り直す必要はありません。記憶された手順がずれた場合（要素の名前が変更された、または要素が移動した場合）、walk はエージェントに要素を選択させるために一度だけエスカレーションし、その後、修正内容を書き戻します。これにより、次回の実行で確実に解決できます（原則 #3）。使用するルートは常に最新の状態に保たれます。ログインが必要なサイトの認証情報は、マップの外部にあるローカルの ~/.webnav/credentials.json（chmod 600）に保存され、DB に保存されたり共有されたりすることはありません。

• 新しいサイトのマッピング — エージェントに学習プロンプトを渡します。 webnav はエージェント向けに構築されているため、手動でマッピングする必要はありません。再利用可能なプロンプトが docs/LEARNING-A-SITE.md にあります。エージェント（安価なものでも構いません。私たちは Haiku を使っています）にこのプロンプトを渡し、自律的に実行させます。エージェントは記録しながら webnav の use プリミティブを使ってサイトを一度操作します。その後、dev graph-analyse --draft がその内容を SELF-VERIFIED マップ（絶対 URL、一意の要素フィンガープリント、ページ内の操作手段のレパートリー、宣言されたドメインシャドウ）にまとめ、dev graph-edit で保存します。フィンガープリントや URL を手作業で作成する必要はありません。（このプロンプトは、シード済みの OrangeHRM マップ（ログインと11のモジュールを実際に操作）を、1回の実行で学習しました。）dev node-clear を使えば、きれいな状態から学習し直せます。

• または、学習を省略して、既存のマップパックをインポートします。 マップはパックとして共有できるため、サイトを学習するのは最初の人だけです。webnav dev import-map <pack.json> でサイトの骨組みを読み込み、dev creds set で自分のログイン情報を設定します（パックには骨組みだけが含まれ、認証情報は含まれません）。mappacks/ には2つのパック（saucedemo、OrangeHRM）が同梱されています。dev export-map <site> で自分のマップを作成し、共有できます。

• または、自分でサイトを閲覧して記録します。 エージェントは不要です。webnav dev record-live --session S --url <site> を実行すると、その URL で画面表示のブラウザーが開き、自然に操作してフローを進められます。実行したすべての操作が、エージェント記録の経路と同じセッションストアに記録されます（実際の Playwright a11y スナップショットを使用し、入力値は記録せず、変更されたフィールドのみを記録します）。Ctrl-C または webnav dev record-stop --session S で停止します。その後は同じ dev graph-analyse <session> --draft → graph-edit → walk のパイプラインを使います。

• または、Chrome 拡張機能から操作し、記録します — 上記のサイドパネルを使います。エージェントに目標を伝えると、既知のルートを先に再利用してアクティブなタブを操作し、その実行内容がマップに記録されます。（生の DOM から a11y ツリーを近似していた、以前の拡張機能のキャプチャ専用経路は廃止されました。SPA で動作しなかったためです。現在の拡張機能では、実際の CDP アクセシビリティを使ってキャプチャします。dev ingest は従来の受信機能として引き続き存在します。）

• いつでも記録内容を確認できます。 webnav dev dashboard（localhost で動作するオペレーター向け UI）を実行します。Sessions タブには、フィルター、ステップ数、Verified バッジとともに、記録されたすべての実行がソース別（Extension／Agent／Manual）に表示されます。クリック操作による記録と再生機能もあります。

  または、テキストビューの dev outline <site> / dev mermaid <site> を使います。

要約： 初期状態で walk を使えるのは saucedemo です。それ以外は自分でマッピングします。同じ マシンでマッピング済みのサイトを使えば、すぐに利用でき、キャッシュされ、自己修復します。新しいサイトの場合は、 まずあなた（またはエージェント）が一度記録します。

動詞

# Travel a map you've built (the core win: deterministic, low-token replay)
webnav walk --start <state> --goal <state>   autopilot a multi-step route; pauses at genuine forks
webnav walk-resume <session> --ref|--classify   answer a paused walk's fork and continue
webnav creds set <site> 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 <url> --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 <ref> / use type <ref> <t>  act on a ref; records the before/after effect
webnav read <url> [--raw]                    open a URL -> distilled content
webnav search "<query>" [--top N]            open-web search -> extracted evidence
webnav eval <url> "<js>" | network <url>     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 <id> --graph J  write the validated graph
webnav dev effects --session S               the RAW recorded before/after snapshots
webnav dev outline <site> | mermaid <site>   completeness check | renderable diagram
webnav dev graph-show --node <id>            a site's stored states + edges (JSON)
webnav dev export-map <site>                 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 <id>  empty a site's map (re-learn) / delete it entirely
webnav dev node-add / edge-add / capture     teach + inspect helpers

詳細は webnav <verb> --help を参照してください。出力は stdout に JSON 形式で表示されます。終了コードは正常時が 0、エラー時が 2、空の場合が 3 です。

MCP サーバー

webnav mcp は、stdio 経由であらゆる動詞を MCP ツールとして提供します。MCP クライアントを接続すると、 エージェントがシェルを介さずに、これらの動詞をネイティブに利用できます。ツールは --help と同じコマンド レジストリから生成され、各呼び出しは実際の CLI を実行するため、2 つのインターフェースに差異が生じることはありません。

{ "mcpServers": { "webnav": { "command": "webnav", "args": ["mcp"] } } }

コンシューマー向けの動詞は webnav use <verb> ...、マップ作成用の動詞は webnav dev <verb> ... という正式な形式でも呼び出せます。webnav read ... のような動詞を直接指定する形式も引き続き利用できます。

サイトのマップを調べる

マップは人間向けのダッシュボードではなく、呼び出し元のエージェント（walk）向けです。記録された内容を確認するには、 テキストビューを使ってください。UI は不要です。

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 <id>        # raw JSON

アーキテクチャ（1 つの CLI、3 つのコンポーネント、LLM ゼロ）

• Explorer — サイトで宣言された構造を読み取り（観察を優先）、記録を自己検証済みのマップ草案（状態、型付き操作対象、宣言されたドメインシャドウ）にまとめ、状態を認識します。
• MapStore — SQLite による永続化を担います。状態（操作対象と宣言されたシャドウを含む）、投影されたエッジ、サイトノードのインデックス、記録セッションを保存します。
• Router — ルートをたどり、再生し（キャッシュされたセレクターから、決定論的なフィンガープリントによる再解決へ移行）、自己修復し、エビデンス、またはエージェント向けの「次の操作」を示す needs-navigation／needs-classification 応答を返します。判断を下すことも、LLM を呼び出すこともありません。

ソースマップ（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/ 以下で同じ構成になっています。ライブ E2E ウォークテストは WEBNAV_LIVE=1 を指定した場合にのみ実行されます。

原則（全項目は CLAUDE.md を参照）

1. まず観察し、移動は最小限にします。2. 宣言されたコミットポイントは決して通過しません。3. 永続性のある セマンティックルートを保存し、セレクターはキャッシュします。4. 利用を通じて学習する重み付けは、ホステッドサービス側の役割です。5. マップはエビデンスを提示し、判断するのはエージェントです。5a. webnav に LLM はゼロ — 呼び出し元のエージェントに対し、呼び出しと応答のプロトコルを通じて、あらゆる推論を委ねます。6. マップはユースケースに依存しないナビゲーションの骨格であり、ゴールがシグナルへの関心を宣言します。ボット対策の壁を決して回避しません — 検出してエスカレーションします。

ステータス

現在の作業はすべて main にマージされており、テストもすべて成功しています。現在のチェックリスト、未完了の作業、既知の制限については docs/STATUS.md を、確定した設計、メンタルモデル、原則については CLAUDE.md を参照してください。設計ドキュメントは docs/superpowers/specs/ にあります。

貢献

PR を歓迎します。CONTRIBUTING.md を参照してください（確定した原則、開発環境のセットアップ、サイトマップまたはマップパックの貢献方法を記載しています。これが最も大きな効果をもたらす貢献です）。マップパックは骨格のみで、認証情報は含みません。同梱されている例は mappacks/ にあります。セキュリティ上の問題は SECURITY.md の手順に従って非公開で報告してください。互いを尊重しましょう： CODE_OF_CONDUCT.md。

ライセンス

Apache License 2.0。著作権表示と NOTICE ファイルを保持し、帰属表示を行うことを条件に、商用利用を含め、自由に使用、変更、再配布できます。明示的な特許許諾が含まれています。Copyright 2026 Dikshant Yadav.