navigera

navigera

[License: MIT] [CI] [Crates.io] [PyPI] [npm]

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.comnavigera -s work ax                          # the page as a tree; actionable nodes carry [ref=N]navigera -s work click 12                    # prints what the click changed, or oknavigera -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 socketnavigera -s work goto example.comnavigera -s work ax                         # page as an indented tree, [ref=N] on actionable nodesnavigera -s work click 12                   # act on a refnavigera -s work fill 31 "hello" && navigera -s work press Enternavigera -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/signupfill --label Email [email protected]select --label Plan Procheck --label "I accept the terms"click --role button --name "Create account"text --selector .welcomeEOF

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 <css>, --text "<visible 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 <command>.
• 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. Attached to your browser, tab-list shows your tabs beside the agent's and marks the one you are on, so you can say "this page" and the agent works there; quit closes the agent's own tabs and leaves yours, and quit --close-browser waits until a --profile browser's profile is free.

navigera -s me start --auto-connect   # your running browsernavigera -s me tab-select current     # the tab you are onnavigera -s me axnavigera -s me quit                   # the agent's tabs close, yours stay

Electron apps

start --electron <app> launches a desktop app built on Electron and drives its windows like tabs: the same tree, refs, clicks, waits and eval. <app> 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 <arg> passes arguments to the app.

navigera -s app start --electron ./my-app       # the window the app opens firstnavigera -s app axnavigera -s app click --role button --name "Settings"navigera -s app tab-list                        # the app's new window is a tab, and the active onenavigera -s app eval --main "({ app }) => app.getPath('userData')"   # the app's main processnavigera -s app quit                            # ends the app

Natural mode

--natural makes a headless browser look like the browser it is: no HeadlessChrome in the user agent (page, workers, request headers), and a real screen size. navigator.webdriver is false in every mode, and navigera never passes --enable-automation. It is not a CAPTCHA solver and fakes no fingerprint: it is a regular Chrome, run for you. Details: docs/navigera.md.

Parallel agents

Give each agent its own -s <name>. Sessions share one browser, each in a browser context of its own (cookies, storage, cache, tabs and downloads apart), so N agents cost one browser plus a page each, as Playwright's one driver with a context per test does, not N browsers. The browser stays on the private pipe (no DevTools port) and closes 30 s after its last session. start --own-browser gives a session a browser of its own. navigera sessions lists the sessions with their memory and idle time; sessions --clean quits the idle ones (--all: every one), and start --parent <pid> ends a session when its agent's process does. An unused session ends after 10 min.

From a program

Programs can keep one browser on a pipe instead: navigera serve reads one JSON command per stdin line, for example {"id":1,"op":"goto","url":"https://example.com"}. The session socket speaks the same protocol.

IDE agents (MCP)

navigera mcp is a Model Context Protocol server for Cline, Roo Code, Kilo Code, Continue, VS Code, Claude Desktop and Cursor, with the same tree, refs and waits as the CLI, in 13 tools (a tool list of about 8 KB; browser_more lists the rarer ones on demand). Add it as {"command": "navigera", "args": ["mcp"]}, or without installing anything as {"command": "npx", "args": ["-y", "navigera", "mcp"]}; per-client snippets are in docs/navigera.md. Agents that run shell commands (Kilo, Cline CLI, Gemini CLI, Codex) can use the CLI and the skill directly: navigera install-skill writes it to .agents/skills, where they look for it.

Decisions by a fast model (optional)

Two small decisions an agent otherwise spends a page tree and an LLM turn on, which element and did it work, can go to a System One model: TypeSafe's models (Jev, Kev, ...) when NAVIGERA_DECIDER_KEY is set (NAVIGERA_DECIDER_MODEL picks the model, the key stays the same; TYPESAFE_API_KEY still works), or any endpoint with the same API through NAVIGERA_DECIDER_URL.

navigera -s work click --find "accept the cookies"   # acts on the element the model picksnavigera -s work check "Is an error message shown?"  # {"yes":0.02,"answer":false}

find returns the ref, its probability and the runners-up; below 0.5, --find refuses and lists the candidates instead of acting. start reports "decider" when one is configured, and MCP clients get browser_find and browser_check only then. Nothing leaves the machine otherwise; typed values are sent as (filled).

Supported browsers

CI runs the full end-to-end suite on:

• the current Chrome Stable and the three milestones before it (about four months of releases, covering Extended Stable), all from Chrome for Testing;
• chrome-headless-shell;
• Chrome Beta, as a non-blocking early warning;
• the runner's own Chrome, on Linux and on Windows.

The suite is weekly as well as on every push, so a new Chrome release is caught before agents hit it. In its first runs the matrix caught two real bugs that the runner's Chrome alone missed: Chrome 151 segfaulted with one of the automation flags (--disable-features=OptimizationHints, bisected with chrome-bisect.yml), and on Chrome 153 an Enter-submitted form returned before its redirect landed. Both are fixed.

Each run also checks CDP protocol correctness. navigera records every command it sends (NAVIGERA_CDP_TRACE), and tools/cdp_check.py validates every method, parameter and enum value against the /json/protocol that that browser serves. Deprecated or unknown usage fails the build. Edge and Brave are covered by the benchmark.

Lightpanda (--engine lightpanda) passed the same end-to-end suite up to its 1.0.2 release; it is out of CI for now (1.0.3 fails the drag test, which is being looked into). It is a different engine (one tab, no layout), so navigera fills in what its CDP leaves out: shadow roots and password fields in ax, confirm()/prompt() answers, navigations a click starts. The differences that remain are listed in docs/navigera.md.

Electron (start --electron) has its own end-to-end test on Linux, macOS and Windows: a fixture app whose form is saved through the main process over IPC and which opens a second window of its own. The test reads and fills the form, follows the new window, closes it from the page and checks that quit ends the app.

Benchmarks

Same scripted session (launch → goto listing → title/count/extract evals → fill+click filter → visible-count eval → screenshot → new tab → goto detail → title/row-count evals → close) driven against the same headless browser by each driver. Fixtures are deterministic and local (500-card listing, 1000-row detail). navigera is the static Linux binary the releases ship. Reps are interleaved across contenders. Run in CI via .github/workflows/bench.yml.

Measured 2026-11-06 on GitHub-hosted ubuntu-latest (Intel(R) Xeon(R) Platinum 8370C CPU @ 2.80GHz — 4 vCPU · Chrome 156.0.8078.79). Every driver produced byte-identical extracted data and counts (correctness gate). Session wall is best-of-N (median in brackets); cold start and the live-site rows are ranked by their median, with the best run in brackets. The ladder reruns weekly (bench.yml) against the latest contender releases. GitHub runners vary between runs, so compare rows within one run.

How driver CPU/RSS are measured. Each driver's own utime+stime, read from its zombie's /proc/<pid>/stat before reaping (waitid with WNOWAIT), and its own VmHWM. The kernel counts CPU in 10 ms ticks, so values under ~50 ms are a tie. Not wait4: its rusage is RUSAGE_BOTH and adds in every child the driver reaped. navigera, chromedp, puppeteer and playwright wait() on their Chrome, so wait4 charged them Chrome's CPU and RSS; go-rod (its leakless helper reaps Chrome) and chromiumoxide were never charged. Earlier versions of this table reported exactly that artifact ("0.82s vs 0.03s"). Browser memory is the whole browser process tree (every renderer/GPU/utility process), sampled as summed PSS every 250 ms (shared pages counted once).

Reading the table. Session wall order: nv-shell 0.30s, nv-brave 0.60s, nv-serve 0.61s, nv-edge 0.64s, gorod 0.66s, chromiumoxide 0.80s, chromey 0.94s, chromedp 0.98s, puppeteer 0.99s, playwright 1.20s. Every driver but nv-shell, nv-edge and nv-brave runs the same Google Chrome; on it, nv-serve (0.61s) is ahead of the fastest other driver, gorod (0.66s). nv-shell (0.30s) is navigera on chrome-headless-shell, a lighter build of the same browser that no other row runs, so its lead is partly the browser's. All native drivers (navigera, go-rod, chromiumoxide, chromedp) spend tens of milliseconds of their own CPU or less; the Node drivers spend hundreds and carry 80–150 MB of their own RSS.

Real-world (public internet, median of 9, same run)

example.com goto → title check: 10 of 10 pass; nv-shell 0.15s, gorod 0.38s, nv-serve 0.39s, nv-brave 0.41s, nv-edge 0.46s, chromey 0.47s, chromiumoxide 0.49s, chromedp 0.60s, puppeteer 0.71s, playwright 0.84s.

GitHub browse (awesome-list scroll + trending click-through): 10 of 10 pass; nv-shell 3.49s, gorod 3.64s, chromey 3.86s, chromiumoxide 3.89s, nv-serve 3.96s, puppeteer 4.03s, nv-brave 4.04s, nv-edge 4.04s, chromedp 4.26s, playwright 4.30s. navigera's click returns once the new page has settled; the other drivers' clicks return at once and they then poll the URL, so the browse rows do not time the same readiness. The example.com check is the title; h1 is read, not checked. Live pages change between runs, so these are informational, not part of the correctness gate. (The scroll check used to fail at random for every driver: GitHub sets CSS scroll-behavior: smooth, so scrollY was read mid-animation; contenders now scroll with behavior: 'instant'.)

chrome-headless-shell (the same Chrome build without its browser UI layer): cold start 0.30s → 0.09s (medians), session 0.61s → 0.30s, browser memory 354 MB → 243 MB.

CDP transport A/B (same build and run): --remote-debugging-pipe (default on Linux/macOS) vs a DevTools WebSocket port: cold start 0.30s vs 0.29s (medians), session 0.61s vs 0.62s. No speed difference: the WebSocket handshake itself is ~10 ms. The pipe is the default for two other reasons: it opens no TCP port that another local process could attach to, and Chrome exits when navigera dies (EOF on its command pipe), so a killed agent leaks no browser (tests/edge_cases.rs: over a WebSocket port the browser outlives its driver). Windows has no pipe transport here and uses the WebSocket, with a kill-on-close job object giving the same guarantee (killed_session_server_takes_its_browser_down runs there too).

This build vs navigera 0.8.0, same machine and run (nv-baseline, built the same way by the ladder's baseline_ref A/B): session 0.62s → 0.61s (-2%), cold start 0.30s → 0.30s median (+1%), browser CPU per session 1.16s → 1.15s.

Where navigera's cold start goes (NAVIGERA_TIMINGS, best run): browser up 161 ms, first page 101 ms, close 2 ms.

Agent tools (scripted, warm session, best of 3)

How an agent's tool calls drive a browser: CLI tools run one process per step (a shell tool), MCP servers get one tools/call per step over a persistent connection. Same canonical session plus one page snapshot. Snapshot sizes are each tool's default output, what the agent reads. Outside the session's total, each tool also snapshots the 1000-row page, and navigera starts a second agent's session while the first one's browser is up (sessions share one browser, a context each).

Per-call time includes process start (CLI) or JSON-RPC (MCP), the hop to the daemon, and the CDP work. playwright-cli and Playwright MCP share Playwright's tool backend, which waits a fixed 500 ms after every action (timeouts.settle); playwright-cli also starts a Node process per step. batch saves calls, which are an agent's turns, not time: its row runs the same steps in fewer, longer calls.

Parallel agents (memory, same run)

N agents, each with a session of its own (navigera -s <name>, agent-browser and playwright-cli sessions, one MCP server each), all open at once on the listing after a snapshot. Memory is every process the tool started (browsers, daemons, servers), summed as PSS.

Lightpanda (experimental) passes the same correctness gate in 0.18s with ~11 MB of browser memory. It has no rendering engine and one tab (the session opens the second page in the same tab), so it is listed apart from the Chrome-family ranking.

Agent eval: how a generic agent copes with each tool

One model, six tools

DeepSeek-V4.1-Flash drives each tool through one shell function on a local shop the harness serves: a search, an order form, a price table and a catalog that loads in pages. Success is judged from what the site recorded (the search run, the order placed) and from the final answer, never from the agent's claim; the table and the catalog are drawn per session, so no file holds an answer. CLI tools run without a shell (the command must start with the tool, one per call), MCP servers get one tools/call per call, and every tool starts on the home page. Four tasks, 12 reps each, the tools at their latest npm releases; medians over each tool's 48 sessions (llm-bench.yml, run 42228800128). Cost is the harness's estimate at SiliconFlow's list prices (per million tokens: $0.15 uncached input, $0.003 cached input, $0.60 output), not a bill:

Per task, the lowest median tokens: navigera with batch in all four (search 3.9K, form 5.1K, table 4.5K, catalog 12.7K). The best other tool is agent-browser on search (6.2K) and form (8.1K, under navigera without batch at 8.4K), playwright-cli on the table (5.4K; navigera without batch 5.9K) and Playwright MCP on the catalog (22.0K; navigera without batch 13.5K).

What navigera lost: without batch its median is only 1.6% under agent-browser's (7,906 against 8,035, inside each other's IQR), it is behind agent-browser on the order form, and playwright-cli and Playwright MCP finished the table in fewer turns (median 4 against 5). A tool's catalog cost varies two to six times between its reps (playwright-cli 12.2K–73.3K, navigera 6.6K–31.9K), so close rows can swap places between runs; the 6-rep run of the same build (run 42177759665) had playwright-cli ahead of agent-browser by mean, and the 12 reps put it behind. Earlier runs of the same harness: 8,705 tokens a session without batch and 11,689 with it on 2026-11-03 (run 41579693623); 16,661 and 12,755 against navigera 0.7.1 (run 41568863979). Since 0.7.1 an action says what it changed on the page, so the agent sees the result of a click without another look, and a list item is one line of the tree instead of three.

Contributing

See CONTRIBUTING.md for building, the test suites, reading CI results, A/B benchmarks and releasing.

Layout