WebNav

Browser automation via Chrome extension with JSON output for LLM-friendly control.

CLI Discovery

The CLI is located at ./scripts/webnav-cli/ relative to this SKILL.md file.

Claude Code: Use ${CLAUDE_PLUGIN_ROOT}/skills/webnav/scripts/webnav-cli/webnav.

How It Works

Every interaction follows the observe → read → act → verify loop:

1. Observe  →  webnav observe          (returns file paths to screenshot + snapshot)
2. Read     →  Read the screenshot PNG + snapshot file to understand page state
3. Act      →  Run action commands (click, fill, type, etc.)
4. Verify   →  webnav observe again to confirm the result

observe returns file paths, not inline data. Example output:

{
  "ok": true,
  "action": "observe",
  "url": "https://example.com/login",
  "title": "Login - Example",
  "screenshot": "/tmp/webnav_screenshot_abc123.png",
  "snapshot": {
    "file": "/tmp/webnav_snapshot_abc123.json",
    "nodeCount": 47,
    "tokens": 1820
  },
  "console": { "count": 0 },
  "errors": { "count": 0 },
  "network": { "count": 0 },
  "hint": "For large files use `webnav util json-search <file> [pattern]` to search; small files can be read directly"
}

You must read the screenshot and snapshot files to see what's on the page. The snapshot is a compact accessibility tree:

@e1 navigation "Main Menu"
  @e2 link "Home"
  @e3 link "About"
@e4 main
  @e5 heading "Welcome" [level=1]
  @e6 textbox "Email" [value= required=true]
  @e7 button "Submit"

Each @eN ref can be used with -r @eN on click, fill, type, key, wait-for for precise targeting.

Prerequisites

Run webnav status to check connection. If not set up, the output includes step-by-step setup instructions. Seek help from user to set up the extension.

Command Reference

Observe (read page state)

observe returns compact text snapshot by default; use -f for full JSON tree. Results are always saved to files; the response includes file paths and a tokens estimate.

Navigate (move between pages/positions)

Act (interact with elements)

Text matching (-t): substring by default, -x for exact match. When multiple matches, interactive elements are preferred. fill with -r @eN omits the label arg: fill -r @e6 "value". select requires one of -v (value) or -o (option text).

Wait (explicit waits)

Advanced (JS, debugging, dialogs)

Batch (multi-command in single round trip)

act JSON format: [{"action":"fill","label":"Email","value":"x"},{"action":"click","text":"Submit"}] act positional: 'goto "https://example.com"' 'click -t "Login"' query types: gettext, inputvalue, getattribute, isvisible, isenabled, ischecked, boundingbox

Tabs (multi-tab management)

Webnav isolates its tabs in a Chrome tab group. Tab switching is virtual — it changes which tab commands target without visually disrupting the browser. Use tab new to open additional tabs and tab switch to move between them.

Utilities

Setup

Snapshot Refs

observe and snapshot assign @e1, @e2, ... to interactive elements. These refs enable precise targeting:

• •Use with -r @eN on: click, fill, type, key, wait-for
• •Refs are assigned fresh on every observe or snapshot call
• •Refs go stale after page navigation or DOM changes — always re-run observe before using refs

Reading Output Files

observe saves screenshot, snapshot, console, errors, and network to files. How to read them:

• •Screenshot PNG — always read with the Read tool to see the page visually
• •Snapshot / console / errors / network — check the tokens field in the response:
  • •Small (tokens < 4000): read the file directly
  • •Large: use webnav util json-search <file> [pattern] to search
• •json-search supports: text pattern, --role button, --tag input, --ref @eN

Standalone elements, snapshot, console, errors, network also auto-save to files when results exceed 10 items.

Workflows

Start + navigate:

webnav status
webnav goto "https://example.com" --screenshot
webnav observe
# → Read screenshot PNG and snapshot file to understand the page

Fill and submit a form:

webnav observe
# → Read snapshot to find form fields
webnav fill "Email" "user@example.com"
webnav fill "Password" "secret123"
webnav click -t "Sign In" --wait-url "*/dashboard*" --screenshot
# → Read screenshot to verify navigation succeeded

Debug JS errors:

webnav observe
# → Check errors.count and console.count in response
# → If count > 0, read the errors/console file
webnav evaluate "document.querySelector('#app').dataset.version"

Debug network requests:

webnav observe
# → Check network.count in response
# → If count > 0, read the network file or search it:
webnav util json-search /tmp/network_*.json "api"
# Or standalone with clear:
webnav network -c

Precise targeting with refs:

webnav observe
# → Read snapshot file, find @e6 is the email textbox
webnav fill -r @e6 "user@example.com"
webnav click -r @e7

Batch actions (fewer round trips):

webnav act --json '[
  {"action":"fill","label":"Email","value":"user@example.com"},
  {"action":"fill","label":"Password","value":"secret123"},
  {"action":"click","text":"Sign In","waitUrl":"*/dashboard*","screenshot":true}
]'
# Or positional: webnav act 'fill "Email" "user@example.com"' 'click -t "Sign In"'

Tips

• •Targeting priority: prefer -r @eN (precise) > -t text (readable) > -s selector (fragile)
• •Page state: use observe for combined view; use standalone snapshot -s selector for scoped subtree, standalone console -c / errors -c / network -c to clear after reading
• •Forms: use fill over click + type — it handles focus, clear, and input events
• •Waiting: use click --wait-url / --wait-text / --wait-selector over separate click then wait-for
• •Efficiency: use --screenshot on action commands instead of a separate screenshot call; use act to batch multiple actions
• •After page changes: always re-observe — refs from the previous snapshot are stale
• •Navigation commands (goto, back, forward, reload) auto-wait for page load

Error Handling

All errors return {"ok":false, "error":"...", "code":"...", "hint":{...}}. The hint object includes summary, steps, and diagnostics.

Architecture

CLI (webnav) → Unix Socket → Native Host → Native Messaging → Chrome Extension