Navego
Drives your own signed-in browser from any MCP client over a loopback bridge and MV3 extension: 45 browser_* tools, consent-gated commits, machine-readable navego doctor --json. No cloud session.
Tài liệu
@last-edited: 2026-11-09 UTC+7.
@related: AGENTS.md - docs/security.md - docs/api.md
Navego
A private, local-browser control bridge.
- Lets MCP clients drive the user's own browser session through a strict allowlist of generic browser primitives.
- Returns structured results; the session never moves to a cloud browser.
- The extension holds generic primitives only: receive, validate, execute, collect, return. It may grow as rich as task-based work needs — including local real-time loops — as long as every primitive stays generic. Simple means clear boundaries and no dead code, not a small feature count.
- Site-specific behavior lives in server-side Supabase workflows, which hot-update
independently of the installed extension. No per-site logic and no free
evalever live in the extension.
Boundary
AGENTS.mdholds instructions: the rules, guidelines and requirements that bind every task, and the map of which document answers which question.README.mdholds the explanation: what this is, what each directory does, how to run it, and that same map.- A rule that changes what you may do lives in
AGENTS.mdand nowhere else. CONTRIBUTING.mdsays what a change has to look like when it arrives here, and how a reviewer reads it. It repeats no rule.CHANGELOG.mdsays what each release contained, and points at the notes.SECURITY.mdis the private route for a vulnerability, where GitHub renders it;docs/security.mdholds the detail.
Contract
| Protocol | 1 |
| Browser primitives | 36 allowlisted generic methods (extension/lib/protocol.ts) plus device-local watch.*/loop.* async methods |
| Local MCP surface | 45 tools (local/mcp-server.ts) - the operator's own signed-in Chrome, no cloud hop, plus the wallet that pays for the work |
| Distribution | Signed CRX3 self-updates from the update service |
One command
npm i -g navego
navego local | the everyday browser on this machine, over the loopback bridge |
navego auth | sign in once; the token stays beside this install |
navego doctor | print what is connected and what the plan allows |
navego install | register the extension with every Chromium browser on this Windows machine |
navego uninstall | remove the keys, the Navego folder, and the package itself |
For AI agents
npm i -g navego
navego auth # sign in once
navego doctor # prints bridge, device, plan, quota — verdict yes/no and the one fix
Then point your agent at the package — see llms.txt, llms-install.md and docs/agent-friendly.md for the exact copy-paste snippets for OpenCode, Claude Code, Claude Desktop, Cursor, Windsurf and Zed. Start every session with browser_get_guide.
The local drive is metered where it happens: the local bridge calls the cloud once per session to open the meter and reads the plan from there, then enforces it locally and reports usage into the same daily count the hosted surface reads, so a command past the allowance answers PLAN_LIMIT_REACHED with the plan named. The gate lives in the bridge and in the plan's data in the database, never in readable client code. The package is
on the registry: npm i -g navego, or from a clone with
cd local && npm install -g .. The full answer: docs/agent-call.md.
Every number in that table is measured, not typed: tests/docs/readme.test.ts reads the
primitives from the protocol, the tools from the local server's tool table,
and the edge functions from the directories that hold an index.ts. A number that
drifts fails the suite instead of ageing in the file.
Layout
| Directory | Role |
|---|---|
extension/ | MV3 runtime — background worker, content scripts, popup, options |
shared/ | The one pure core both roads import — SERP parser, normalizer, VM semantics; no copy may drift, so local carries a pack-generated copy and the repo carries the source |
local/ | The local MCP server: CDP straight to the browser on this machine, plus the statement job (local/lib/ is generated by scripts/pack/pack-mcp.ts, never committed) |
hosted/functions/ | Deno edge: auth, billing, bridge, feedback, gateway, listen, runner, update, VM (9 deployed) plus _shared/ — edge-runtime modules only |
hosted/migrations/ | SQL in timestamp order, never rewritten |
scripts/ | The machines, grouped by verb: release/, pack/, verify/, dev/, bench/, proof/ |
tests/ | Fast suite is npm test; grouped by subject — local/, hosted/, extension/, landing/, vm/, billing/, release/, shared/, surface/, tooling/, docs/, search/; py gates stay at the root |
landing/ | The site Cloudflare Pages serves |
docs/proof/ | The record of real shipped runs |
docs/store/ | Generated Chrome Web Store form: scripts/release/build-store-package.py writes the manifest and the zip from extension/ |
The map of every entry, every import rule, and the rules for what may be created where: ARCHITECTURE.md, enforced by tests/tooling/architecture.test.ts.
Commands
npm test # fast suite
npm run check # runtime discovery + version pins
OA_REAL_SITE=1 py tests/real_site_smoke.py # live internet, opt-in
OA_LIVE_SITE_TESTS=1 py tests/browser_extension_test.py # drives Google Maps for real, opt-in
Local green is not acceptance. The acceptance rule is in AGENTS.md.
Which document answers what
| Question | Answer |
|---|---|
| Where is the code map for agents and reviewers? | ARCHITECTURE.md |
| What are the rules that bind every task? | AGENTS.md |
| What does a change have to look like, and how is it reviewed? | CONTRIBUTING.md |
| What is true right now, and what is next? | docs/handoff.md |
| What may I do with a credential, and where is the boundary? | docs/security.md |
| How do I report a vulnerability privately? | SECURITY.md |
| What primitives may the extension expose, and over what wire? | docs/api.md |
| What happens on a site nobody has a workflow for? | docs/unknown-site.md |
| How does this repo resist slop and silent drift? | docs/anti-drift.md |
| How much does a client-month cost, and what does a delivery claim? | docs/uec-north-star.md and the opera_price_list table (migrations under hosted/migrations/) |
| What did a release contain, and why? | CHANGELOG.md and docs/releases/ |
| What design references informed this? | docs/design-references.md |
| What is the product aiming at? | docs/uec-north-star.md |
A design spec under docs/superpowers/specs/ records why a
subsystem is shaped the way it is, and several of its rules are still enforced by
tests/tooling/structure-gates.test.ts. The implementation plans that used to sit beside them
were execution checklists for work that has since shipped; they are deleted, and git log
holds them.
Spent detail is recoverable from git history; there is no archive file.