afnannuzulasugihartono

Navego

Updated

Navego drives your own signed-in browser from the AI you already use (MCP client), over a loopback bridge and an MV3 extension: 45 browser_* tools, 36 primitive browser methods, consent-gated commits. No cloud session, no per-site gadgets.

@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 ofgeneric 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 nodead code, not a small feature count.
  • Site-specific behavior lives in server-side Supabase workflows, which hot-updateindependently of the installed extension. No per-site logic and no free evalever live in the extension.

Boundary

  • AGENTS.md holds instructions: the rules, guidelines and requirements thatbind every task, and the map of which document answers which question.
  • README.md holds the explanation: what this is, what each directory does, howto 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 arriveshere, 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 rendersit; docs/security.md holds 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 ison the registry: npm i -g navego, or from a clone withcd 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 theprimitives 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 thatdrifts 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 asubsystem is shaped the way it is, and several of its rules are still enforced bytests/tooling/structure-gates.test.ts. The implementation plans that used to sit beside themwere execution checklists for work that has since shipped; they are deleted, and git logholds them.

Spent detail is recoverable from git history; there is no archive file.

MCP Server · Populars

MCP Server · New

    Nimbleway

    WebRouter

    WebRouter is an open source standard that connects your agent to the web

    Community Nimbleway
    frontman-ai

    frontman

    The AI agent that lives in your framework/browser

    Community frontman-ai
    Laksh-star

    Screenward

    Movie and TV discovery, watch planning, and streaming availability—for browsers and MCP clients.

    Community Laksh-star
    codescene-oss

    CodeHealth MCP Server

    The CodeScene MCP Server exposes CodeScene’s Code Health analysis as local AI-friendly tools.

    Community codescene-oss
    Poptin-LTD

    poptin-mcp

    Official Poptin MCP server. Connect your AI agent to create email campaigns, analyze popup and form performance, and build targeted audience segments.

    Community Poptin-LTD