barebrowse 0.1.0 → 0.2.0

package/README.md

@@ -1,69 +1,228 @@
 # barebrowse
 
-Vanilla JS library. CDP-direct. URL in, pruned ARIA snapshot out.
-No Playwright, no bundled browser, no build step.
+**URL in, agent-ready snapshot out.** Zero dependencies. Uses your own browser.
 
-## What It Does
+barebrowse gives autonomous agents eyes and hands on the web. It launches your installed Chromium, navigates to any page, and returns a pruned ARIA snapshot — a compact, semantic representation of what's on screen. The agent reads the snapshot, picks an element by ref, acts, and reads the next snapshot. Observe, think, act.
 
-Gives autonomous agents authenticated access to the web through the user's own Chromium browser.
+No Playwright. No bundled browser. No 200MB download. Just CDP over a WebSocket to whatever Chromium you already have.
 
-```js
-import { browse, connect } from 'barebrowse';
+## The idea
 
-// One-shot: read a page
-const snapshot = await browse('https://any-page.com');
+LLMs don't need DOM. They need to know what's on the page and what they can interact with. That's exactly what the browser's accessibility tree provides — every heading, button, link, input, and landmark, structured semantically.
+
+But raw ARIA trees are noisy. A typical page produces 50-100KB of ARIA data. Most of it is decorative wrappers, hidden elements, and structural noise. barebrowse includes a 9-step pruning pipeline (ported from [mcprune](https://github.com/nickvdyck/mcprune)) that strips 47-95% of tokens while keeping every interactive element and meaningful label. A page that costs $0.15 in tokens raw costs $0.02-0.08 pruned.
+
+The snapshot format uses `[ref=N]` markers on interactive elements. The agent says "click ref 8" and barebrowse scrolls the element into view, calculates coordinates, and dispatches real mouse events. No CSS selectors. No XPath. Just semantic refs from the ARIA tree.
+
+## Install
+
+```
+npm install barebrowse
+```
+
+Requires Node.js >= 22 and any installed Chromium-based browser (Chrome, Chromium, Brave, Edge, Vivaldi).
+
+## Quick start
+
+```javascript
+import { browse } from 'barebrowse';
+
+// One line. That's it.
+const snapshot = await browse('https://news.ycombinator.com');
+console.log(snapshot);
+```
+
+Output (pruned, ~50% smaller than raw):
+```
+- WebArea "Hacker News" [ref=1]
+  - link "Hacker News" [ref=4]
+  - link "new" [ref=7]
+  - link "past" [ref=9]
+  - link "comments" [ref=11]
+  ...
+  - link "Show HN: I built a thing" [ref=42]
+  - link "197 comments" [ref=45]
+```
+
+## Two ways to use it
+
+### 1. As a library (framework mode)
+
+Import and call directly. You control the loop.
+
+**One-shot** — read a page and get the snapshot:
+
+```javascript
+import { browse } from 'barebrowse';
+
+const snapshot = await browse('https://example.com', {
+  mode: 'headless',      // 'headless' | 'headed' | 'hybrid'
+  cookies: true,         // inject cookies from your browser
+  prune: true,           // ARIA pruning (47-95% token reduction)
+  consent: true,         // auto-dismiss cookie consent dialogs
+});
+```
+
+**Session** — navigate and interact across multiple pages:
+
+```javascript
+import { connect } from 'barebrowse';
 
-// Session: navigate, interact, observe
 const page = await connect();
-await page.goto('https://any-page.com');
-console.log(await page.snapshot());
-await page.click('8');      // ref from snapshot
-await page.type('3', 'hello');
-await page.scroll(500);
+await page.goto('https://duckduckgo.com');
+
+let snap = await page.snapshot();
+// Agent sees: combobox "Search" [ref=5]
+
+await page.type('5', 'barebrowse github');
+await page.press('Enter');
+await page.waitForNavigation();
+
+snap = await page.snapshot();
+// Agent sees search results with clickable refs
+
+await page.click('12');  // click first result
 await page.close();
 ```
 
-## Features
+### 2. As an MCP server
 
-- **CDP direct** — no Playwright, no 200MB download, uses your installed Chromium
-- **ARIA snapshots** — semantic, token-efficient output for LLMs
-- **Built-in pruning** — 47-95% token reduction via 9-step pipeline
-- **Cookie extraction** — authenticated browsing from your existing sessions (Chromium + Firefox)
-- **Interactions** — click, type, scroll via CDP Input domain
-- **Three modes** — headless (default), headed (connect to running browser), hybrid (planned)
-
-## Architecture
+For Claude Desktop, Cursor, Windsurf, or any MCP client.
 
+```bash
+npm install -g barebrowse
+npx barebrowse install
 ```
-URL → chromium.js (find/launch browser)
-    → cdp.js (WebSocket CDP client)
-    → auth.js (extract cookies → inject via CDP)
-    → Page.navigate
-    → aria.js (Accessibility.getFullAXTree → nested tree)
-    → prune.js (9-step role-based pruning)
-    → interact.js (click/type/scroll via Input domain)
-    → agent-ready snapshot
+
+That's it. `install` auto-detects Claude Desktop, Cursor, and Claude Code, and writes the MCP config for you. No manual JSON editing.
+
+If you prefer manual setup, add this to your MCP config:
+```json
+{
+  "mcpServers": {
+    "barebrowse": {
+      "command": "npx",
+      "args": ["barebrowse", "mcp"]
+    }
+  }
+}
 ```
 
-Seven modules, ~1,400 lines, zero required dependencies.
+This exposes 7 tools: `browse`, `goto`, `snapshot`, `click`, `type`, `press`, `scroll`. The LLM calls `goto` to navigate, `snapshot` to observe, and action tools to interact. Action tools return `'ok'` -- the LLM calls `snapshot` explicitly to see what changed.
+
+**Same package, two entry points.** `npm install barebrowse` gives you both the library (`import { browse } from 'barebrowse'`) and the MCP server (`npx barebrowse mcp`). Pick whichever fits your setup.
+
+## Three modes
+
+| Mode | Flag | What happens | Use for |
+|------|------|-------------|---------|
+| **Headless** | `mode: 'headless'` (default) | Launches a fresh Chromium, no UI | Scraping, reading, fast automation |
+| **Headed** | `mode: 'headed'` | Connects to your running browser via CDP port | Bot-detected sites, visual debugging |
+| **Hybrid** | `mode: 'hybrid'` | Tries headless first, falls back to headed if bot-blocked | General-purpose agent browsing |
+
+Headed mode requires your browser running with `--remote-debugging-port=9222`.
+
+## What it handles automatically
+
+You don't need to write code for any of this:
+
+- **Cookie consent dialogs** — ARIA scan + jsClick across 7 languages (EN, NL, DE, FR, ES, IT, PT). Tested on 16+ sites.
+- **Permission prompts** — notifications, geolocation, camera, mic all auto-denied via CDP
+- **Login walls** — cookies extracted from your Firefox or Chromium profile, injected via CDP
+- **Off-screen elements** — scrolled into view before every click
+- **Bot detection** — stealth patches in headless (navigator.webdriver, plugins, chrome object)
+- **Profile locking** — unique temp dir per headless instance
+- **ARIA noise** — 9-step pruning pipeline strips decorative wrappers, hidden nodes, structural noise
+
+## connect() API reference
+
+| Method | Description |
+|--------|-------------|
+| `goto(url)` | Navigate + wait for load + dismiss consent |
+| `snapshot()` | Pruned ARIA tree with `[ref=N]` markers |
+| `click(ref)` | Scroll into view + mouse click at element center |
+| `type(ref, text, opts?)` | Focus + insert text. `{ clear: true }` replaces existing. |
+| `press(key)` | Special key: Enter, Tab, Escape, Backspace, Delete, arrows, Space |
+| `scroll(deltaY)` | Mouse wheel. Positive = down, negative = up. |
+| `hover(ref)` | Move mouse to element center |
+| `select(ref, value)` | Set `<select>` value or click custom dropdown option |
+| `screenshot(opts?)` | Returns base64 PNG/JPEG/WebP |
+| `waitForNavigation()` | Wait for page load (SPA-aware) |
+| `waitForNetworkIdle()` | Wait until no pending requests for 500ms |
+| `injectCookies(url)` | Extract + inject cookies from your browser |
+| `cdp` | Raw CDP session escape hatch |
+| `close()` | Clean up everything |
+
+## bareagent integration
+
+barebrowse ships a tool adapter for [bareagent](https://github.com/nickvdyck/bareagent):
+
+```javascript
+import { Loop } from 'bare-agent';
+import { Anthropic } from 'bare-agent/providers';
+import { createBrowseTools } from 'barebrowse/bareagent';
+
+const provider = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });
+const loop = new Loop({ provider });
+
+const { tools, close } = createBrowseTools();
+try {
+  const result = await loop.run(
+    [{ role: 'user', content: 'Find the top story on Hacker News' }],
+    tools
+  );
+  console.log(result.text);
+} finally {
+  await close();
+}
+```
 
-## Requirements
+`createBrowseTools(opts)` returns 9 tools: browse, goto, snapshot, click, type, press, scroll, select, screenshot. Action tools auto-return a fresh snapshot after each action so the LLM always sees the result.
 
-- Node.js >= 22
-- Any installed Chromium-based browser (Chrome, Chromium, Brave, Edge, Vivaldi, Arc, Opera)
+You can pass any `connect()` options to `createBrowseTools()` — mode, port, cookies, consent.
 
-## Ecosystem
+## How it works
 
 ```
-bareagent  = the brain  (orchestration, LLM loop, memory, retries)
-barebrowse = the eyes + hands  (browse, read, interact with the web)
+URL -> chromium.js     find/launch browser, permission-suppressing flags
+    -> cdp.js          WebSocket CDP client, flattened sessions
+    -> stealth.js      navigator.webdriver patches (headless only)
+    -> Browser.setPermission    suppress all prompts
+    -> auth.js         extract cookies from Firefox/Chromium -> inject via CDP
+    -> Page.navigate   go to URL, wait for load
+    -> consent.js      detect + dismiss cookie consent dialogs
+    -> aria.js         Accessibility.getFullAXTree -> nested tree
+    -> prune.js        9-step pruning: wrappers, noise, landmarks
+    -> interact.js     click/type/scroll/hover/select via CDP Input domain
+    -> snapshot        agent-ready ARIA text with [ref=N] markers
 ```
 
-barebrowse is a library. bareagent imports it as a capability.
+11 modules, 2,400 lines, zero dependencies.
+
+## Token savings
+
+Real-world measurements on the pruning pipeline:
+
+| Page | Raw ARIA | Pruned (act) | Reduction | Est. cost saved |
+|------|----------|-------------|-----------|----------------|
+| Hacker News | 52K chars | 27K chars | 47% | ~$0.04/call |
+| Wikipedia article | 180K chars | 12K chars | 93% | ~$0.25/call |
+| Amazon product | 95K chars | 8K chars | 92% | ~$0.13/call |
+| Google results | 45K chars | 5K chars | 89% | ~$0.06/call |
 
-## Status
+Two pruning modes:
+- **act** (default) — keeps interactive elements + visible labels. For clicking, typing, navigating.
+- **read** — keeps all text content. For reading articles, extracting information.
+
+## Context file
+
+`barebrowse.context.md` in the repo root is an LLM-consumable integration guide. Feed it to an AI assistant that needs to wire barebrowse into a project — it covers the full API, snapshot format, interaction loop, auth options, and gotchas.
+
+## Requirements
 
-Early development. API may change.
+- Node.js >= 22 (built-in WebSocket, built-in SQLite)
+- Any Chromium-based browser installed (Chrome, Chromium, Brave, Edge, Vivaldi)
+- Linux tested (Fedora/KDE). macOS/Windows cookie paths exist but untested.
 
 ## License
 

package/barebrowse.context.md

@@ -0,0 +1,261 @@
+# barebrowse -- Integration Guide
+
+> For AI assistants and developers wiring barebrowse into a project.
+> v0.1.0 | Node.js >= 22 | 0 required deps | MIT
+
+## What this is
+
+barebrowse is a CDP-direct browsing library for autonomous agents (~1,800 lines). URL in, pruned ARIA snapshot out. It launches the user's installed Chromium browser, navigates, handles consent/permissions/cookies, and returns a token-efficient ARIA tree with `[ref=N]` markers for interaction.
+
+No Playwright. No bundled browser. No build step. Vanilla JS, ES modules.
+
+```
+npm install barebrowse
+```
+
+Two entry points:
+- `import { browse } from 'barebrowse'` -- one-shot: URL in, snapshot out
+- `import { connect } from 'barebrowse'` -- session: navigate, interact, observe
+
+## Which mode do I need?
+
+| Mode | What it does | When to use |
+|---|---|---|
+| `headless` (default) | Launches a fresh Chromium, no UI | Scraping, reading, fast automation |
+| `headed` | Connects to user's running browser on CDP port | Bot-detected sites, debugging, visual tasks |
+| `hybrid` | Tries headless first, falls back to headed if blocked | General-purpose agent browsing |
+
+Headed mode requires the browser to be launched with `--remote-debugging-port=9222`.
+
+## Minimal usage: one-shot browse
+
+```javascript
+import { browse } from 'barebrowse';
+
+// Defaults: headless, cookies injected, pruned, consent dismissed
+const snapshot = await browse('https://example.com');
+
+// All options
+const snapshot = await browse('https://example.com', {
+  mode: 'headless',      // 'headless' | 'headed' | 'hybrid'
+  cookies: true,         // inject user's browser cookies
+  browser: 'firefox',    // cookie source: 'firefox' | 'chromium' (auto-detected)
+  prune: true,           // apply ARIA pruning (47-95% token reduction)
+  pruneMode: 'act',      // 'act' (interactive elements) | 'read' (all content)
+  consent: true,         // auto-dismiss cookie consent dialogs
+  timeout: 30000,        // navigation timeout in ms
+  port: 9222,            // CDP port for headed/hybrid mode
+});
+```
+
+## connect() API
+
+`connect(opts)` returns a page handle for interactive sessions. Same opts as `browse()` for mode/port.
+
+| Method | Args | Returns | Notes |
+|---|---|---|---|
+| `goto(url, timeout?)` | url: string, timeout: number (default 30000) | void | Navigate + wait for load + dismiss consent |
+| `snapshot(pruneOpts?)` | false or { mode: 'act'\|'read' } | string | ARIA tree with `[ref=N]` markers. Pass `false` for raw. |
+| `click(ref)` | ref: string | void | Scroll into view + mouse press+release at center |
+| `type(ref, text, opts?)` | ref: string, text: string, opts: { clear?, keyEvents? } | void | Focus + insert text. `clear: true` replaces existing. |
+| `press(key)` | key: string | void | Special key: Enter, Tab, Escape, Backspace, Delete, arrows, Home, End, PageUp, PageDown, Space |
+| `scroll(deltaY)` | deltaY: number | void | Mouse wheel. Positive = down, negative = up. |
+| `hover(ref)` | ref: string | void | Move mouse to element center |
+| `select(ref, value)` | ref: string, value: string | void | Set `<select>` value or click custom dropdown option |
+| `screenshot(opts?)` | { format?: 'png'\|'jpeg'\|'webp', quality?: number } | string (base64) | Page screenshot |
+| `waitForNavigation(timeout?)` | timeout: number (default 30000) | void | Wait for page load or frame navigation |
+| `waitForNetworkIdle(opts?)` | { timeout?: number, idle?: number } | void | Wait until no pending requests for `idle` ms (default 500) |
+| `injectCookies(url, opts?)` | url: string, { browser?: string } | void | Extract cookies from user's browser and inject via CDP |
+| `cdp` | -- | object | Raw CDP session for escape hatch: `page.cdp.send(method, params)` |
+| `close()` | -- | void | Close page, disconnect CDP, kill browser (if headless) |
+
+## Snapshot format
+
+The snapshot is a YAML-like ARIA tree. Each line is one node:
+
+```
+- WebArea "Example Domain" [ref=1]
+  - heading "Example Domain" [level=1] [ref=3]
+  - paragraph [ref=5]
+    - StaticText "This domain is for use in illustrative examples." [ref=6]
+  - link "More information..." [ref=8]
+```
+
+Key rules:
+- `[ref=N]` markers appear on interactive and named elements
+- Refs are **ephemeral** -- they change on every `snapshot()` call
+- Always call `snapshot()` to get fresh refs before interacting
+- `click(ref)` / `type(ref, text)` / `hover(ref)` / `select(ref, value)` use these ref strings
+- Pruning removes noise (~47-95% token reduction) while keeping all interactive elements
+
+## Interaction loop: observe, think, act
+
+```javascript
+import { connect } from 'barebrowse';
+
+const page = await connect();
+await page.goto('https://example.com');
+
+// 1. Observe
+let snap = await page.snapshot();
+
+// 2. Think (LLM decides what to do based on snapshot)
+// 3. Act
+await page.click('8');         // click the "More information..." link
+await page.waitForNavigation();
+
+// 4. Observe again (refs are now different)
+snap = await page.snapshot();
+
+// ... repeat until goal is achieved
+
+await page.close();
+```
+
+## Auth / cookie options
+
+barebrowse can inject cookies from the user's real browser sessions, bypassing login walls.
+
+| Source | How | Notes |
+|---|---|---|
+| Firefox (default) | SQLite `cookies.sqlite`, plaintext | Works on Linux. Auto-detected default profile. |
+| Chromium | SQLite `Cookies` + AES decryption via keyring | Linux: KWallet or GNOME Keyring. Profile must not be locked. |
+| Manual | `page.injectCookies(url, { browser: 'firefox' })` | Explicit injection on connect() sessions |
+| Disabled | `{ cookies: false }` | No cookie injection |
+
+`browse()` auto-injects cookies before navigation. `connect()` exposes `injectCookies()` for manual control.
+
+## Obstacle course -- what barebrowse handles automatically
+
+| Obstacle | How | Mode |
+|---|---|---|
+| Cookie consent (GDPR) | ARIA scan + jsClick accept button, 7 languages | Both |
+| Consent behind iframes | JS `.click()` via DOM.resolveNode bypasses overlays | Both |
+| Permission prompts | Launch flags + CDP Browser.setPermission auto-deny | Both |
+| Media autoplay blocked | `--autoplay-policy=no-user-gesture-required` | Both |
+| Login walls | Cookie extraction from Firefox/Chromium + CDP injection | Both |
+| Pre-filled form inputs | `type({ clear: true })` selects all + deletes first | Both |
+| Off-screen elements | `DOM.scrollIntoViewIfNeeded` before every click | Both |
+| Form submission | `press('Enter')` triggers onsubmit | Both |
+| SPA navigation | `waitForNavigation()` uses loadEventFired + frameNavigated | Both |
+| Bot detection | Headed mode with real cookies bypasses most checks | Headed |
+| `navigator.webdriver` | Stealth patches in headless (webdriver, plugins, chrome obj) | Headless |
+| Profile locking | Unique temp dir per headless instance | Headless |
+| ARIA noise | 9-step pruning: wrapper collapse, noise removal, landmark promotion | Both |
+
+## bareagent wiring
+
+barebrowse provides a tool adapter for bareagent's Loop:
+
+```javascript
+import { Loop } from 'bare-agent';
+import { Anthropic } from 'bare-agent/providers';
+import { createBrowseTools } from 'barebrowse/src/bareagent.js';
+
+const provider = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });
+const loop = new Loop({ provider });
+
+const { tools, close } = createBrowseTools();
+
+try {
+  const result = await loop.run(
+    [{ role: 'user', content: 'Search for "barebrowse" on DuckDuckGo and tell me the first result' }],
+    tools
+  );
+  console.log(result.text);
+} finally {
+  await close();
+}
+```
+
+`createBrowseTools(opts)` returns:
+- `tools` -- array of bareagent-compatible tool objects (browse, goto, snapshot, click, type, press, scroll, select, screenshot)
+- `close()` -- cleanup function, call when done
+
+Action tools (click, type, press, scroll, goto) auto-return a fresh snapshot so the LLM always sees the result. 300ms settle delay after actions for DOM updates.
+
+## MCP wrapper
+
+barebrowse ships an MCP server for direct use with Claude Desktop, Cursor, or any MCP client.
+
+```bash
+npm install barebrowse       # or npm install -g barebrowse
+```
+
+Add to your MCP client config (`.mcp.json`, `claude_desktop_config.json`, etc.):
+```json
+{
+  "mcpServers": {
+    "barebrowse": {
+      "command": "npx",
+      "args": ["barebrowse", "mcp"]
+    }
+  }
+}
+```
+
+7 tools exposed: `browse` (one-shot), `goto`, `snapshot`, `click`, `type`, `press`, `scroll`.
+
+Action tools return `'ok'` -- the agent calls `snapshot` explicitly to observe. This avoids double-token output since MCP tool calls are cheap to chain.
+
+Session tools (goto, snapshot, click, type, press, scroll) share a singleton page, lazy-created on first use.
+
+## Architecture
+
+```
+URL -> chromium.js (find/launch browser, permission flags)
+    -> cdp.js (WebSocket CDP client)
+    -> stealth.js (navigator.webdriver patches, headless only)
+    -> Browser.setPermission (suppress prompts)
+    -> auth.js (extract cookies -> inject via CDP)
+    -> Page.navigate
+    -> consent.js (detect + dismiss cookie dialogs)
+    -> aria.js (Accessibility.getFullAXTree -> nested tree)
+    -> prune.js (9-step role-based pruning)
+    -> interact.js (click/type/scroll/hover/select via Input domain)
+    -> agent-ready snapshot
+```
+
+| Module | Lines | Purpose |
+|---|---|---|
+| `src/index.js` | ~370 | Public API: `browse()`, `connect()`, screenshot, network idle, hybrid |
+| `src/cdp.js` | 148 | WebSocket CDP client, flattened sessions |
+| `src/chromium.js` | 148 | Find/launch Chromium browsers, permission-suppressing flags |
+| `src/aria.js` | 69 | Format ARIA tree as text |
+| `src/auth.js` | 279 | Cookie extraction (Chromium AES + keyring, Firefox), CDP injection |
+| `src/prune.js` | 472 | ARIA pruning pipeline (ported from mcprune) |
+| `src/interact.js` | ~170 | Click, type, press, scroll, hover, select |
+| `src/consent.js` | 200 | Auto-dismiss cookie consent dialogs across languages |
+| `src/stealth.js` | ~40 | Navigator patches for headless anti-detection |
+| `src/bareagent.js` | ~120 | Tool adapter for bareagent Loop |
+| `mcp-server.js` | ~170 | MCP server (JSON-RPC over stdio) |
+
+## Gotchas
+
+1. **Refs are ephemeral.** Every `snapshot()` call generates new refs. Always snapshot before interacting. Never cache refs across snapshots.
+
+2. **SPA navigation has no loadEventFired.** For single-page apps (React, YouTube, GitHub), use `waitForNetworkIdle()` or a timed wait after click instead of `waitForNavigation()`.
+
+3. **Pruning modes matter.** `act` mode (default) keeps interactive elements + visible labels. `read` mode keeps all text content. Use `read` for content extraction, `act` for form filling and navigation.
+
+4. **Headed mode requires manual browser launch.** Start your browser with `--remote-debugging-port=9222`. barebrowse connects to it -- it does not launch it.
+
+5. **Cookie extraction needs unlocked profile.** Chromium cookies are AES-encrypted with a keyring key. If Chromium is running, the profile may be locked. Firefox cookies are plaintext and always accessible.
+
+6. **Hybrid mode kills and relaunches.** If headless is bot-blocked, hybrid mode kills the headless browser and connects to headed on port 9222. The headed browser must already be running.
+
+7. **One page per connect().** Each `connect()` call creates one page. For multiple tabs, call `connect()` multiple times.
+
+8. **Consent dismiss is best-effort.** It handles 16+ tested sites across 7 languages but novel consent implementations may need manual handling. Disable with `{ consent: false }`.
+
+9. **Screenshot returns base64.** Write to file with `fs.writeFileSync('shot.png', Buffer.from(base64, 'base64'))` or pass directly to a vision model.
+
+10. **Chromium-only.** CDP protocol limits us to Chrome, Chromium, Edge, Brave, Vivaldi (~80% desktop share). Firefox support via WebDriver BiDi is not yet implemented.
+
+## Constraints
+
+- **Node >= 22** -- built-in WebSocket, built-in SQLite
+- **Chromium-only** -- CDP protocol
+- **Linux first** -- tested on Fedora/KDE, macOS/Windows cookie paths exist but untested
+- **Not a server** -- library that agents import. Wrap as MCP (included) or HTTP if needed.
+- **Zero required deps** -- everything uses Node stdlib

package/cli.js

@@ -0,0 +1,156 @@
+#!/usr/bin/env node
+/**
+ * cli.js -- barebrowse CLI entry point.
+ *
+ * Usage:
+ *   npx barebrowse mcp            Start the MCP server (JSON-RPC over stdio)
+ *   npx barebrowse install        Auto-configure MCP in Claude Desktop / Cursor / Claude Code
+ *   npx barebrowse browse <url>   One-shot browse, print snapshot to stdout
+ */
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir, platform } from 'node:os';
+
+const cmd = process.argv[2];
+
+if (cmd === 'mcp') {
+  await import('./mcp-server.js');
+
+} else if (cmd === 'install') {
+  install();
+
+} else if (cmd === 'browse' && process.argv[3]) {
+  const { browse } = await import('./src/index.js');
+  const url = process.argv[3];
+  const mode = process.argv[4] || 'headless';
+  try {
+    const snapshot = await browse(url, { mode });
+    process.stdout.write(snapshot + '\n');
+    process.exit(0);
+  } catch (err) {
+    process.stderr.write(`Error: ${err.message}\n`);
+    process.exit(1);
+  }
+
+} else {
+  process.stdout.write(`barebrowse -- CDP-direct browsing for autonomous agents
+
+Usage:
+  barebrowse mcp                Start MCP server (JSON-RPC over stdio)
+  barebrowse install            Auto-configure MCP for Claude Desktop / Cursor / Claude Code
+  barebrowse browse <url>       One-shot browse, print ARIA snapshot
+
+As a library:
+  import { browse, connect } from 'barebrowse';
+
+As bareagent tools:
+  import { createBrowseTools } from 'barebrowse/bareagent';
+
+More: see README.md or barebrowse.context.md
+`);
+}
+
+// --- MCP auto-installer ---
+
+function install() {
+  const mcpEntry = {
+    command: 'npx',
+    args: ['barebrowse', 'mcp'],
+  };
+
+  const targets = detectTargets();
+
+  if (targets.length === 0) {
+    console.log('No MCP clients detected. You can manually add this to your MCP config:\n');
+    console.log(JSON.stringify({ mcpServers: { barebrowse: mcpEntry } }, null, 2));
+    console.log('\nSupported clients: Claude Desktop, Cursor, Claude Code');
+    return;
+  }
+
+  let installed = 0;
+
+  for (const target of targets) {
+    try {
+      const config = readJsonOrEmpty(target.path);
+      if (!config.mcpServers) config.mcpServers = {};
+
+      if (config.mcpServers.barebrowse) {
+        console.log(`  ${target.name}: already configured`);
+        installed++;
+        continue;
+      }
+
+      config.mcpServers.barebrowse = mcpEntry;
+
+      // Ensure parent dir exists
+      const dir = join(target.path, '..');
+      mkdirSync(dir, { recursive: true });
+
+      writeFileSync(target.path, JSON.stringify(config, null, 2) + '\n');
+      console.log(`  ${target.name}: installed -> ${target.path}`);
+      installed++;
+    } catch (err) {
+      console.log(`  ${target.name}: failed (${err.message})`);
+    }
+  }
+
+  if (installed > 0) {
+    console.log(`\nDone. Restart your MCP client to pick up the new server.`);
+    console.log('Tools available: browse, goto, snapshot, click, type, press, scroll');
+  }
+}
+
+function detectTargets() {
+  const home = homedir();
+  const os = platform();
+  const targets = [];
+
+  // Claude Desktop
+  let claudeDesktop;
+  if (os === 'darwin') {
+    claudeDesktop = join(home, 'Library', 'Application Support', 'Claude', 'claude_desktop_config.json');
+  } else if (os === 'linux') {
+    claudeDesktop = join(home, '.config', 'Claude', 'claude_desktop_config.json');
+  } else if (os === 'win32') {
+    claudeDesktop = join(home, 'AppData', 'Roaming', 'Claude', 'claude_desktop_config.json');
+  }
+  if (claudeDesktop) {
+    // Check if Claude Desktop dir exists (even if config doesn't yet)
+    const dir = join(claudeDesktop, '..');
+    if (existsSync(dir)) {
+      targets.push({ name: 'Claude Desktop', path: claudeDesktop });
+    }
+  }
+
+  // Cursor
+  let cursorDir;
+  if (os === 'darwin') {
+    cursorDir = join(home, '.cursor');
+  } else if (os === 'linux') {
+    cursorDir = join(home, '.cursor');
+  } else if (os === 'win32') {
+    cursorDir = join(home, '.cursor');
+  }
+  if (cursorDir && existsSync(cursorDir)) {
+    targets.push({ name: 'Cursor', path: join(cursorDir, 'mcp.json') });
+  }
+
+  // Claude Code (project-level .mcp.json in cwd)
+  const cwd = process.cwd();
+  const claudeCodePath = join(cwd, '.mcp.json');
+  // Only suggest if we're in a project directory (has package.json or .git)
+  if (existsSync(join(cwd, 'package.json')) || existsSync(join(cwd, '.git'))) {
+    targets.push({ name: 'Claude Code (this project)', path: claudeCodePath });
+  }
+
+  return targets;
+}
+
+function readJsonOrEmpty(path) {
+  try {
+    return JSON.parse(readFileSync(path, 'utf8'));
+  } catch {
+    return {};
+  }
+}