navigera

navigera

Browser automation for AI agents. One native binary (Rust, no Node) that an agent drives from its shell, one command per step, against a warm Chrome. It reads pages as a compact accessibility tree with [ref=N] handles, acts with real mouse and keyboard events, and after each action prints what changed on the page, so the agent seldom needs a second look.

navigera -s work start                       # a warm headless browser named "work"

navigera -s work goto https://example.com navigera -s work ax # the page as a tree; actionable nodes carry [ref=N] navigera -s work click 12 # prints what the click changed, or ok navigera -s work quit

Faster software for a better planet — less energy, less compute, more time for life.

Why navigera

• Fewer tokens and turns for agents. When one model drives six browser tools through the same tasks, navigera's sessions use the fewest tokens (median 7.9K, or 5.1K with batch, against 8.0K–13.8K) at the lowest cost; all 96 of its sessions succeed.
• Fast at every step: 33 ms per command an agent sends, against 104 ms for agent-browser and 199–778 ms for the MCP servers and playwright-cli; a 1,000-row page reads in 88 ms as 41 KB.
• Light: 7 MB for navigera itself; eight agents at once in 947 MB where the other agent tools need 2.4–2.6 GB, because sessions share one browser with a private context each.
• It tells the agent what happened. A click that loads results prints the new lines (+ status: Results for: headphones), one that changes nothing prints ok, and an error says what to do next.
• The hard parts are handled: new tabs, iframes, shadow DOM, dialogs, uploads and downloads, your own signed-in browser, Electron desktop apps, and an MCP server for IDE agents.

At a glance

From one benchmark run on GitHub's runners (bench 42228718100) and the agent eval (run 42228800128), on builds with the same source; how each was measured is under Benchmarks and Agent eval.

Where navigera is not first

• Browsing GitHub, live (median of 9): 3.96 s, behind go-rod's 3.64 s, chromey's 3.86 s and chromiumoxide's 3.89 s. navigera's click returns once the new page is there, while the other drivers return at once and then poll the URL, so this row does not time the same readiness.
• One JavaScript eval, warm: 0.46 ms against go-rod's 0.44 ms. navigera is a separate process an agent's shell talks to, and go-rod a library inside its caller; the gap is 0.02 ms.
• Cold start (median of 15): go-rod is 6 ms faster, 0.294 s against navigera's 0.300 s.
• example.com, live (median of 9): 0.39 s against go-rod's 0.38 s.
• In the agent eval, navigera without batch is level with agent-browser on median tokens (7,906 against 8,035) and a little behind it on the order form (median 8.4K against 8.1K); playwright-cli and Playwright MCP finished the price table in fewer turns (median 4 against 5).
• navigera's fastest rows (nv-shell) run chrome-headless-shell, a lighter build of Chrome the other drivers here don't use; the comparisons above are all on the same Google Chrome.

Install

curl -fsSL https://raw.githubusercontent.com/andrey-usa/navigera/master/install.sh | sh

Windows (PowerShell):

irm https://raw.githubusercontent.com/andrey-usa/navigera/master/install.ps1 | iex

Or with a package manager; each one installs the same prebuilt binary:

Then give your agent the usage guide:

navigera install-skill        # -> ./.agents/skills (Gemini CLI, Codex, Cline, Kilo, …)

--claude -> ./.claude/skills, --continue -> ./.continue/skills

Linux, macOS and Windows are supported. On Windows the session socket is a loopback TCP port that only accepts clients presenting a random token from the session file in your temp directory, CDP runs over a DevTools WebSocket, and Chrome sits in a kill-on-close job object, so it still exits when navigera dies.

navigera finds Chrome on its own: $CHROME_BIN, a system Chrome, Chromium or Edge, or one it installed itself. For the fastest cold start, navigera install-browser downloads chrome-headless-shell from Google's Chrome for Testing into navigera's own cache: the same Chrome without its browser UI layer, about three times faster to start (see Benchmarks). Once it is there, headless sessions use it and headed ones the system Chrome (navigera install-browser chrome puts the full Chrome there too, for a machine with none). Set $CHROME_BIN to choose explicitly.

Use

navigera -s work start                      # warm headless browser behind a local socket

navigera -s work goto example.com navigera -s work ax # page as an indented tree, [ref=N] on actionable nodes navigera -s work click 12 # act on a ref navigera -s work fill 31 "hello" && navigera -s work press Enter navigera -s work wait --text "Saved" navigera -s work quit

Steps you are sure of go in one call, one model turn: batch reads one command per line (or JSON ops) and prints what the steps read and the page state once, stopping at the first failure:

navigera -s work batch <<'EOF'

goto https://example.com/signup fill --label Email ada@example.com select --label Plan Pro check --label "I accept the terms" click --role button --name "Create account" text --selector .welcome EOF

page "Checkout — Acme" http://shop.test/checkout

• main:
• heading "Checkout" [level=1]
• textbox "Full name" [ref=21]
• combobox "Country" [ref=22] value="Select…" options: "Canada", "Mexico", …
• radio "Express (1–2 days)" [checked, ref=25]
• Iframe "Card payment":
• document "Card details":
• textbox "Card number" [ref=41]
• button "Place order" [ref=30]

The commands are goto, ax, click, fill, type, press, select, hover, drag, scroll, upload, wait, eval, back/forward/reload, screenshot, pdf, the tab-* commands, dialog and quit, with get and is for one value, console and network for what the page logged and fetched, cookies, storage and state save|load (cookies and localStorage as one JSON file) for sign-ins, set for viewport, device, media, geo and the like, route to fail, answer or change requests, or replay a recorded HAR, and webmcp-list / webmcp-call for the tools a page offers agents through WebMCP (on in the browsers navigera starts; a tool that may change things needs --confirm).

• Targets: elements can be named by ref, --selector , --text " ", --role/--name, --label, --placeholder or --testid.
• Output: compact by default, for agents: an action prints what it did to the page (the new title and url, or, after an ax, the lines of that tree that are new, gone or different, with their refs; ok when nothing visible changed), a read only its value; errors go to stderr. --output json (or NAVIGERA_OUTPUT=json) prints one JSON line per command, for programs.
• Help: navigera help .
• Agent guide: the version-matched guide is skills/navigera/SKILL.md, also printed by navigera skill.
• Reference: docs/navigera.md has the full reference, and llms.txt is an index for LLMs.

Hand the agent your browser

Three ways, from most direct to most portable:

The other way round, show puts a headless session on the person's screen with the same tabs and sign-ins, for the step only they can do (a login, a 2FA prompt, a CAPTCHA), and hide takes it back; MCP clients get the same as browser_handoff.

navigera profiles lists what can be handed over: each installed browser's profiles (name, signed-in email), whether --attach reaches it right now, and navigera's own --profile browsers. --profile work without --from is a persistent browser you sign in to yourself. Either way navigera works in windows of its own, quit only disconnects, and quit --close-browser waits until the profile is free.

Electron apps

start --electron launches a desktop app built on Electron and drives its windows like tabs: the same tree, refs, clicks, waits and eval. is the app's directory or main script (navigera runs the Electron in its node_modules), a packaged app's executable, a macOS .app bundle or a command on PATH; --electron-arg passes arguments to the app.

navigera -s app start --electron ./my-app       # the window the app opens first

navigera -s app ax navigera -s app click --role button --name "Settings" navigera -s app tab-list # the app's new window is a tab, and the active one navigera -s app eval --main "({ app }) => app.getPath('userData')" # the app's main process navigera -s app quit # ends the app

How windows, the main process and attaching work

Windows the app opens later are adopted as they appear (one opened after the agent acts is the active tab; the app's own start-up windows don'