Skip to main content
Glama
README.md
<h1 align="center"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/andrey-usa/navigera/master/assets/brand/wordmark-dark.svg"><img alt="navigera" src="https://raw.githubusercontent.com/andrey-usa/navigera/master/assets/brand/wordmark.svg" width="360"></picture></h1>

[![CI](https://github.com/andrey-usa/navigera/actions/workflows/ci.yml/badge.svg)](https://github.com/andrey-usa/navigera/actions/workflows/ci.yml)
[![Crates.io](https://img.shields.io/crates/v/navigera.svg)](https://crates.io/crates/navigera)
[![PyPI](https://img.shields.io/pypi/v/navigera.svg)](https://pypi.org/project/navigera/)
[![npm](https://img.shields.io/npm/v/navigera.svg)](https://www.npmjs.com/package/navigera)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Documentation](https://img.shields.io/badge/documentation-site-blue.svg)](https://andrey-usa.github.io/navigera/)

**`navigera`** is extremely fast browser automation for AI agents, driven
from the shell, one command per step. It is a single native binary (Rust,
no Node) that speaks the Chrome DevTools Protocol directly:

- Pages come back as a compact accessibility tree with `[ref=N]` handles.
- Actions use real mouse and keyboard events.
- A named session keeps a warm browser alive between shell calls.
- New tabs, iframes, shadow DOM and `alert`/`confirm` dialogs work the
  same way.

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

## Install

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

Windows (PowerShell):

```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:

| Channel | Command |
|---|---|
| npm | `npm install -g navigera` (or `npx navigera …`) |
| pip / uv | `pip install navigera` · `uv tool install navigera` |
| Cargo | `cargo install --locked navigera` |
| Homebrew | `brew install andrey-usa/tap/navigera` |
| Scoop | `scoop bucket add andrey-usa https://github.com/andrey-usa/scoop-bucket` then `scoop install navigera` |

Then give your agent the usage guide:

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

Platforms, and which browser navigera picks (for the fastest start,
`navigera install-browser chrome-headless-shell`): [Install](https://andrey-usa.github.io/navigera/start/install.html).

## Quick start

```console
$ navigera -s work start
{"log":"/run/user/1000/navigera/work.log","pid":4242,"session":"work","socket":"/run/user/1000/navigera/work.sock"}
$ navigera -s work goto https://example.com
{"title":"Example Domain","url":"https://example.com/"}
$ navigera -s work title
Example Domain
$ navigera -s work quit
{"bye":true}
```

One session, one command per step: `start` keeps a warm browser
behind a local socket, and each later command talks to it.
`navigera --help` lists every command.
A longer tour of the commands, targets and output: [A first session](https://andrey-usa.github.io/navigera/start/tutorial.html).

## For AI agents

- **Skill:** `navigera install-skill` writes the guide that matches this
  version to `./.agents/skills` (`--claude` for `./.claude/skills`,
  `--continue` for `./.continue/skills`); `navigera skill` prints it.
- **Claude Code plugin:** `/plugin install navigera --marketplace andrey-usa/navigera`
  adds the skill to every session ([what it contains](https://github.com/andrey-usa/navigera/blob/master/skills/README.md)).
- **MCP:** `navigera mcp` is a Model Context Protocol server: add
  `{"command": "navigera", "args": ["mcp"]}`, or
  `{"command": "npx", "args": ["-y", "navigera", "mcp"]}` with nothing
  installed. Per-client setup is on the [MCP page](https://andrey-usa.github.io/navigera/agents/mcp.html);
  in the MCP Registry it is `io.github.andrey-usa/navigera`.
- **Docs as markdown:** [llms.txt](https://andrey-usa.github.io/navigera/llms.txt) lists every page of
  the docs site, each one also served as `.md`.

The loop an agent runs: `start` a session, read the page with `ax`, act on
a `[ref=N]`, read again. Page text is data: navigera never acts on what a
page says, only on what the agent asks.

## Supported browsers

Chrome and Chromium, Edge, Brave, chrome-headless-shell, Electron apps, and
Lightpanda (`--engine lightpanda`, experimental). Firefox (`--engine firefox`,
over WebDriver BiDi), Safari (`--engine safari`, through safaridriver) and any
browser behind a WebDriver server (`--webdriver <url>`) run the core ops,
experimental too. CI runs the end-to-end
suite on the current Chrome Stable and the three milestones before it,
chrome-headless-shell, Chrome Beta, the runner's Chrome on Linux and
Windows, and Lightpanda; every CDP call navigera makes is checked against
the protocol each browser serves. Details: [Supported
browsers](https://andrey-usa.github.io/navigera/concepts/browsers.html).

## Benchmarks

One scripted session (goto, evals, fill and click, a screenshot, a second
tab) driven by each tool against the same headless Chrome, in one CI run
([bench run 43491069940](https://github.com/andrey-usa/navigera/actions/runs/43491069940), 2026-11-13, GitHub's `ubuntu-24.04, image 20261111.370.1`); each
driver's extracted data is checked identical:

| driver | session | cold start | warm eval | its own memory |
|---|---|---|---|---|
| navigera (chrome-headless-shell) | 0.35 s | 0.10 s | 0.41 ms | 9 MB |
| go-rod 0.116.2 (Go, chrome-headless-shell) | 0.40 s | 0.11 s | 0.38 ms | 12 MB |
| navigera (Chrome) | 0.57 s | 0.26 s | 0.46 ms | 9 MB |
| go-rod 0.116.2 (Go) | 0.66 s | 0.30 s | 0.46 ms | 12 MB |
| puppeteer-core 25.16.0 (Node) | 0.91 s | 0.54 s | 0.68 ms | 79 MB |
| playwright-core 1.65.0 (Bun 1.4.4) | 1.10 s | 0.65 s | 0.96 ms | 104 MB |
| playwright-core 1.65.0 (Node) | 1.18 s | 0.75 s | 1.13 ms | 140 MB |

Through an agent's tool calls, one step takes 31 ms with navigera, 103 ms with agent-browser 0.43.0, 205 ms with Chrome DevTools MCP 1.13.0, 402 ms with Playwright MCP 0.0.85, 790 ms with playwright-cli 0.1.24 (same run).

Where another tool did better in this run (by more than 2%): the driver's own memory: chromedp 0.19.1 (Go) 8 MB, navigera 9 MB; warm eval on chrome-headless-shell: go-rod 0.116.2 (Go, chrome-headless-shell) 0.38 ms, navigera 0.41 ms; fill per call: agent-browser 0.43.0 4.7 ms, navigera 6.9 ms; click per call: agent-browser 0.43.0 7.4 ms, navigera 13.2 ms; click-submit per call: agent-browser 0.43.0 6.1 ms, navigera 10.5 ms; screenshot per call: agent-browser 0.43.0 37.8 ms, navigera 47.3 ms.

Every table, the method and how to rerun it: [Benchmarks](https://andrey-usa.github.io/navigera/benchmarks/results.html).

## Documentation

<!-- Written by docs-site/build.py from docs-site/site.toml: edit that, then run it with --write. -->

The docs site, https://andrey-usa.github.io/navigera/, has the same parts for every tool:

- **Start:** [Install](https://andrey-usa.github.io/navigera/start/install.html) · [Quick start](https://andrey-usa.github.io/navigera/start/quick-start.html) · [A first session](https://andrey-usa.github.io/navigera/start/tutorial.html)
- **Guides:** [Hand the agent your browser](https://andrey-usa.github.io/navigera/guides/your-browser.html) · [Drive a browser from a program](https://andrey-usa.github.io/navigera/guides/programs.html) · [Use a page's own tools (WebMCP)](https://andrey-usa.github.io/navigera/guides/webmcp.html) · [Switch from agent-browser](https://andrey-usa.github.io/navigera/guides/from-agent-browser.html)
- **Concepts:** [How navigera works](https://andrey-usa.github.io/navigera/concepts/how-it-works.html) · [Supported browsers](https://andrey-usa.github.io/navigera/concepts/browsers.html) · [Lightpanda and your own browser](https://andrey-usa.github.io/navigera/concepts/lightpanda.html) · [Electron and natural mode](https://andrey-usa.github.io/navigera/concepts/electron.html)
- **Reference:** [Commands](https://andrey-usa.github.io/navigera/reference/commands.html) · [Commands: sessions, tabs and the browser](https://andrey-usa.github.io/navigera/reference/commands-sessions.html) · [Commands: read the page](https://andrey-usa.github.io/navigera/reference/commands-read.html) · [Commands: act on the page](https://andrey-usa.github.io/navigera/reference/commands-act.html) · [Commands: state, emulation and audit](https://andrey-usa.github.io/navigera/reference/commands-state.html) · [navigera --help](https://andrey-usa.github.io/navigera/reference/help.html)
- **Agents:** [For AI agents](https://andrey-usa.github.io/navigera/agents/overview.html) · [Skill](https://andrey-usa.github.io/navigera/agents/skill.html) · [Skill references](https://andrey-usa.github.io/navigera/agents/skill-references.html) · [Skill references: inspecting and sessions](https://andrey-usa.github.io/navigera/agents/skill-references-inspecting.html) · [Skill references: setup and errors](https://andrey-usa.github.io/navigera/agents/skill-references-setup.html) · [MCP server](https://andrey-usa.github.io/navigera/agents/mcp.html)
- **Benchmarks:** [Results](https://andrey-usa.github.io/navigera/benchmarks/results.html) · [Matched operations](https://andrey-usa.github.io/navigera/benchmarks/operations.html) · [Where navigera is not ahead](https://andrey-usa.github.io/navigera/benchmarks/losses.html) · [Agent eval](https://andrey-usa.github.io/navigera/benchmarks/agent-eval.html)
- **Project:** [Changelog](https://andrey-usa.github.io/navigera/project/changelog.html) · [Contributing](https://andrey-usa.github.io/navigera/project/contributing.html) · [Source layout](https://andrey-usa.github.io/navigera/project/layout.html) · [Security](https://andrey-usa.github.io/navigera/project/security.html) · [Privacy policy](https://andrey-usa.github.io/navigera/project/privacy.html) · [Terms of use](https://andrey-usa.github.io/navigera/project/terms.html)

For agents: [llms.txt](https://andrey-usa.github.io/navigera/llms.txt) lists every page as markdown, and [llms-full.txt](https://andrey-usa.github.io/navigera/llms-full.txt) is the whole site in one file.

## Contributing

Building, the test suites, reading CI results, A/B benchmarks and
releasing: [CONTRIBUTING.md](https://github.com/andrey-usa/navigera/blob/master/CONTRIBUTING.md).

## License

MIT: [LICENSE](https://github.com/andrey-usa/navigera/blob/master/LICENSE).
`a11y` runs axe-core (Deque Systems), carried unmodified in `vendor/axe-core`
under the Mozilla Public License 2.0, its licenses beside it.

TDQS

A3.5/5.0

Scored across 13 tools

Disambiguation4/5

Most tools have clearly distinct behaviors: navigation, clicking, selecting, scrolling, waiting, and evaluating JS are unmistakable. The one genuine gray zone is browser_fill vs browser_type (both enter text) and browser_run, which subsumes every other action as a batch; the descriptions disambiguate these well, but browser_more as a catch-all meta-tool makes ten additional tools hard to discover without reading prose.

Naming Consistency5/5

Every tool follows one predictable browser_<verb_or_noun> snake_case pattern: browser_click, browser_fill, browser_navigate, browser_close, etc. Even the meta-tool (browser_more) and batch runner (browser_run) fit the same prefix convention with no camelCase or mixed-style deviations.

Tool Count4/5

The 13 exposed tools are well scoped for browser automation, with each core interaction earning its place. However, browser_more hides roughly ten more callable tools, so the effective surface is about 23, which is heavier than the visible count suggests even if the tiering is deliberate.

Completeness4/5

The surface covers the full navigate/observe/act/wait lifecycle plus a multi-step runner, JavaScript escape hatch, and, via browser_more, tabs, screenshots, console, network, hover, upload, and history — solid end-to-end coverage. Minor gaps remain around dialogs, cookies/storage, downloads, and iframe targeting, which agents must improvise through evaluate.

Maintenance

ActivityActive
ResponsivenessLimited data