Browser Guide Overview

Browser Guide is the read-only sibling of the Browser Agent. Where the Browser Agent gives an AI full control of Chrome, Browser Guide is the deliberate inverse: the same evidence infrastructure with the actuation layer structurally removed. It explains the page you are on, visually points to the right control, and walks you through tasks one step at a time — you perform every action.

Install

Browser Guide is open source and currently installs from GitHub (Chrome Web Store release coming soon). It requires Chrome 116+ and Node.js 20+, on macOS 13+, Windows, or Linux; building the macOS helper from source additionally needs Swift 6.

git clone https://github.com/Crawlio-app/browser-guide.git
cd browser-guide
npm install
npm run build
npm run install:helper

Then open chrome://extensions, enable Developer mode, choose Load unpacked, and select dist/extension.

Once you have Node, the helper can also be installed or repaired with one command, npx crawlio-browser-guide init, and checked with npx crawlio-browser-guide doctor.

Connect

On first install the connect card opens automatically:

1. Grant helper access — Chrome asks once for the nativeMessaging permission so the extension can reach the local helper. Nothing leaves your Mac.
2. Connect a credential when the side panel asks: reuse your existing Codex or Claude Code sign-in with one click, or paste an OpenAI Platform API key. Credentials live in ~/.config/browser-guide/credentials.json (user-only permissions) — never in Chrome storage. Imported sign-ins stay fresh automatically by re-reading those tools' own local files.
3. Learn it safely on the practice page — an inert playground where the guide gives you a tour of itself, no credential needed. No helper yet? The panel's Try the demo first runs the same tour before any setup.
4. Open any page, click the Browser Guide toolbar icon, and ask.

Use

• Ask — explains the current page: what it is, what each section does.
• Find — locates what you describe and places a pointer-transparent beacon over it, with a dismissable on-page card.
• Walkthrough — select it and the tour starts by itself: a compass companion walks you through the page step by step. Each on-page card shows progress and a Next button; Done closes the tour. If a target is off-screen, press the arrow cue and the page scrolls to it.
• Voice — press the beacon or ⌘⇧G / ⌘⇧Space and talk. Audio streams from your Mac directly to OpenAI over WebRTC. The Speak toggle reads typed answers aloud with your computer's own voice — locally, on macOS and Windows alike, without the microphone.
• Visual — opt-in screenshots, omitted entirely whenever a visible input, code block, or likely-sensitive content is present.
• Site memory — the guide remembers your last few questions per site (locally, bounded, never uploaded) so follow-ups have context. The clock button in the panel forgets the current site in one click.
• Agent eyes (MCP) — flip the Eyes toggle (off by default; an "Eyes on" badge shows while active) and coding agents on your machine — Claude Code, Codex, any MCP client — can read the sanitized snapshot of the page you are sharing through a private local file. They see; they still cannot act. Register with claude mcp add browser-guide -- npx -y crawlio-browser-guide mcp. Toggling off deletes the snapshot.

Limits

• Chrome never grants access on internal pages (chrome://) or the Chrome Web Store.
• Canvas-drawn and virtualized interfaces (spreadsheets, design tools, maps) do not expose their inner content to the accessibility snapshot; the guide says so plainly and works with what is visible.
• Voice needs a funded OpenAI Platform key with Realtime access.

See the privacy policy for exactly what data goes where, and the GitHub repo for the full security audit.