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.

Documentação

@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 eval ever live in the extension.

Boundary

  • AGENTS.md holds instructions: the rules, guidelines and requirements that bind every task, and the map of which document answers which question.
  • README.md holds 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.md and nowhere else.
  • CONTRIBUTING.md says what a change has to look like when it arrives here, and how a reviewer reads it. It repeats no rule.
  • CHANGELOG.md says what each release contained, and points at the notes.
  • SECURITY.md is the private route for a vulnerability, where GitHub renders it; docs/security.md holds the detail.

Contract

Protocol1
Browser primitives36 allowlisted generic methods (extension/lib/protocol.ts) plus device-local watch.*/loop.* async methods
Local MCP surface45 tools (local/mcp-server.ts) - the operator's own signed-in Chrome, no cloud hop, plus the wallet that pays for the work
DistributionSigned CRX3 self-updates from the update service

One command

npm i -g navego
navego localthe everyday browser on this machine, over the loopback bridge
navego authsign in once; the token stays beside this install
navego doctorprint what is connected and what the plan allows
navego installregister the extension with every Chromium browser on this Windows machine
navego uninstallremove 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

DirectoryRole
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

QuestionAnswer
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.