~~~~~~~~~~~~~~~~~~~~
  ~~~ .---------. ~~~
  ~~~ | · clear | ~~~
  ~~~ | · focus | ~~~
  ~~~ '---------' ~~~
  ~~~~~~~~~~~~~~~~~~~~

  barebrowse

Your agent browses like you do -- same browser, same logins, same cookies. Prunes pages down to what matters. 40-90% fewer tokens, zero wasted context.

What this is

barebrowse gives your AI agent a real browser. Navigate, read, interact, move on.

It uses the browser you already have -- your sessions, your cookies. Pages come back stripped to what matters -- 40-90% fewer tokens than raw output.

No Playwright. Zero dependencies. No bundled browser. No 200MB download.

Install

npm install barebrowse

Requires Node.js >= 22 and any installed Chromium-based browser.

Three ways to use it

1. CLI session -- for coding agents and quick testing

barebrowse open https://example.com    # Start session + navigate
barebrowse snapshot                    # ARIA snapshot → .barebrowse/page-*.yml
barebrowse click 8                     # Click element
barebrowse close                       # End session

Outputs go to .barebrowse/ as files -- agents read them with their file tools, no token waste in tool responses.

Teach your agent the commands by installing the skill file (a markdown reference the agent reads as context). The CLI tool itself still needs npm install barebrowse -- the skill just teaches the agent how to use it.

Claude Code: Copy commands/barebrowse/SKILL.md to .claude/skills/barebrowse/SKILL.md (project) or run barebrowse install --skill (global).

Other agents: Copy commands/barebrowse.md to your agent's command/skill directory.

For writing your own skill files for other CLI tools: docs/skill-template.md.

2. MCP server -- for Claude Desktop, Cursor, and other MCP clients

Claude Code:

claude mcp add barebrowse -- npx barebrowse mcp

Claude Desktop / Cursor:

npx barebrowse install

Or manually add to your config (claude_desktop_config.json, .cursor/mcp.json):

{
  "mcpServers": {
    "barebrowse": {
      "command": "npx",
      "args": ["barebrowse", "mcp"]
    }
  }
}

VS Code (.vscode/mcp.json):

{
  "servers": {
    "barebrowse": {
      "command": "npx",
      "args": ["barebrowse", "mcp"]
    }
  }
}

18 tools: browse, goto, snapshot, click, type, press, scroll, hover, select, back, forward, reload, drag, upload, pdf, screenshot, wait_for, tabs. Plus assess (privacy scan) if wearehere is installed. Plus opt-in eval (BAREBROWSE_MCP_EVAL=1) — runs JS in the authenticated session, off by default because it can read cookies/localStorage. Session runs in hybrid mode with automatic cookie injection. Per-tool timeouts (goto/reload/wait_for 60s, back/forward 30s, interactive ops 15s, pdf/screenshot/upload 45s) with auto-retry on transient failures (idempotent only — mutating tools fail loudly to avoid double-submits).

browse and snapshot accept pruneMode: 'act'|'read' (v0.9.1). act (default) keeps interactive elements — best for clicking/filling. read keeps paragraphs, headings, and long text — best for articles, docs, and content extraction. If act-mode collapses a content-heavy page near-totally, the snapshot includes a hint: … line suggesting pruneMode='read' so the agent doesn't bail to a separate HTTP fetch.

Troubleshooting MCP setup: npx barebrowse doctor scans every known config location and flags scope conflicts. npx barebrowse install --force overwrites an existing entry pointing at a different endpoint.

3. Library -- for agentic automation

Import barebrowse in your agent code. One-shot reads, interactive sessions, full observe-think-act loops. Works with any LLM orchestration library. Ships with a ready-made adapter for bareagent (17 tools, auto-snapshot after every action).

For code examples, API reference, and wiring instructions, see barebrowse.context.md -- the full integration guide.

Three modes

| Mode | What happens | Best for | |------|-------------|----------| | Headless (default) | Launches a fresh Chromium, no UI | Fast automation, scraping, reading pages | | Headed | Auto-launches a visible Chromium window | Bot-detected sites, visual debugging, CAPTCHAs | | Hybrid | Tries headless first, auto-launches headed if blocked | General-purpose agent browsing |

Attach to your already-running browser

Start Chromium yourself with a debug port, then drive your real logged-in session:

chromium --remote-debugging-port=9222

import { connect } from 'barebrowse';
const page = await connect({ port: 9222 });
await page.goto('https://your-logged-in-app.example.com');
const snap = await page.snapshot();
await page.close(); // closes only the tab barebrowse opened — your browser keeps running

No clone profile, no fresh cookies — the agent sees what you see.

What it handles automatically

Cookie consent walls (29 languages, with real mouse click fallback for stubborn CMPs), login walls (cookie extraction from your browsers), bot detection (ARIA node count heuristic + stealth patches + automatic headed fallback — snapshot shows [BOT CHALLENGE DETECTED] warning when blocked), permission prompts, SPA navigation, JS dialogs, off-screen elements, pre-filled inputs, ARIA noise, and profile locking. The agent doesn't think about any of it.

Safe by default (v0.11.0)

barebrowse hands an autonomous — and therefore prompt-injectable — agent an authenticated browser, so the defaults are calibrated for that threat:

• Local-resource schemes blocked. file:, view-source:, chrome:, etc. are rejected by default (a confirmed local-file-read vector); http/https/data stay allowed. Override with allowLocalUrls: true.
• Cookie injection scoped to a precise RFC-6265 domain match — browsing one site can't pull look-alike or unrelated cookies into the session.
• CLI daemon authenticated with a per-session token (loopback alone isn't an authorization boundary); snapshots and saved state are written owner-only (0600).
• Opt-in hardening for stricter deployments: blockPrivateNetwork (SSRF guard for loopback/RFC-1918/cloud-metadata) and uploadDir (confine upload() to one directory). Both available on the library, MCP, bareagent, and CLI (--block-private-network, --upload-dir).

See barebrowse.context.md and the PRD's "Security Model & Safe Defaults" for the full rationale.

What the agent sees

Raw ARIA output from a page is noisy -- decorative wrappers, hidden elements, structural junk. The pruning pipeline (ported from mcprune) strips it down to what matters.

| Page | Raw | Pruned | Reduction | |------|-----|--------|-----------| | example.com | 377 chars | 45 chars | 88% | | Hacker News | 51,726 chars | 27,197 chars | 47% | | Wikipedia (article) | 109,479 chars | 40,566 chars | 63% | | DuckDuckGo | 42,254 chars | 5,407 chars | 87% |

Two pruning modes: act (default) keeps interactive elements and visible labels -- for clicking, typing, navigating. read keeps all text content -- for reading articles and extracting information.

Actions

Everything the agent can do through barebrowse:

| Action | What it does | |--------|-------------| | Navigate | Load a URL, wait for page load, auto-dismiss consent | | Back / Forward | Browser history navigation | | Snapshot | Pruned ARIA tree with [ref=N] markers. Two modes: act (buttons, links, inputs) and read (full text). 40-90% token reduction. | | Click | Scroll into view + mouse click at element center, JS fallback for hidden elements | | Type | Focus + insert text, with option to clear existing content first | | Press | Special keys: Enter, Tab, Escape, Backspace, Delete, arrows, Space | | Scroll | Mouse wheel up or down (accepts direction or pixels) | | Hover | Move mouse to element center (triggers tooltips, hover states) | | Select | Set dropdown value (native select or custom dropdown) | | Drag | Drag one element to another (Kanban boards, sliders) | | Upload | Set files on a file input element | | Screenshot | Page capture as base64 PNG/JPEG/WebP | | PDF | Export page as PDF | | Assess | Privacy scan: score (0-100), risk level, 10-category breakdown. Tries headless first, falls back to headed if bot-blocked. Consent auto-dismissed before scan. Max 3 concurrent, 30s timeout, tabs cleaned up. Requires npm install wearehere. | | Tabs | List open tabs, switch between them | | Wait for content | Poll for text or CSS selector to appear on page | | Wait for navigation | SPA-aware: works for full page loads and pushState | | Wait for network idle | Resolve when no pending requests for 500ms | | Dialog handling | Auto-dismiss JS alert/confirm/prompt dialogs | | Save state | Export cookies + localStorage to JSON | | Inject cookies | Extract from Firefox/Chromium and inject via CDP | | Raw CDP | Escape hatch for any Chrome DevTools Protocol command |

Tested against

16+ sites across 8 countries, all consent dialogs dismissed, all interactions working:

Google, YouTube, BBC, Wikipedia, GitHub, DuckDuckGo, Hacker News, Amazon DE, The Guardian, Spiegel, Le Monde, El Pais, Corriere, NOS, Bild, Nu.nl, Booking, NYT, Stack Overflow, CNN, Reddit

Context file

barebrowse.context.md is the full integration guide. Feed it to an AI assistant or read it yourself -- it covers the complete API, snapshot format, interaction loop, auth options, bareagent wiring, MCP setup, and gotchas. Everything you need to wire barebrowse into a project.

How it works

URL -> find/launch browser (chromium.js)
    -> WebSocket CDP connection (cdp.js)
    -> stealth patches before page scripts (stealth.js, headless only)
    -> suppress all permission prompts (Browser.setPermission)
    -> extract + inject cookies from your browser (auth.js)
    -> navigate to URL, wait for load
    -> detect + dismiss cookie consent dialogs (consent.js)
    -> get full ARIA accessibility tree (aria.js)
    -> 9-step pruning pipeline from mcprune (prune.js)
    -> dispatch real input events: click/type/scroll (interact.js)
    -> agent-ready snapshot with [ref=N] markers

11 modules, 2,400 lines, zero required dependencies.

Requirements

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

The bare ecosystem

Four vanilla JS modules. Zero deps where possible (bareguard has one). Same API patterns.

| | bareagent | barebrowse | baremobile | bareguard | |---|---|---|---|---| | Does | Gives agents a think→act loop | Gives agents a real browser | Gives agents an Android device | Gates everything an agent does | | How | Goal in → coordinated actions out | URL in → pruned snapshot out | Screen in → pruned snapshot out | Action in → allow / deny / human-asked out | | Replaces | LangChain, CrewAI, AutoGen | Playwright, Selenium, Puppeteer | Appium, Espresso, UIAutomator2 | Hand-rolled allowlists, scattered policy code | | Interfaces | Library · CLI · subprocess | Library · CLI · MCP | Library · CLI · MCP | Library | | Solo or together | Orchestrates the others as tools | Works standalone | Works standalone | Embedded in bareagent's loop; usable by any runner |

Reach 50+ messengers with one Docker container via beeperbox — a headless Beeper Desktop that exposes WhatsApp, iMessage, Signal, Telegram, Slack, Discord, RCS, SMS and more as a single MCP server. Wire it through bareagent's MCP bridge; bareguard policies the invocations like any other tool (per-chat allowlists, ask patterns on destructive sends, all the usual layered defense).

What you can build:

• Headless automation — scrape sites, fill forms, extract data, monitor pages on a schedule
• QA & testing — automated test suites for web and Android apps without heavyweight frameworks
• Personal AI assistants — chatbots that browse the web or control your phone on your behalf
• Remote device control — manage Android devices over WiFi, including on-device via Termux
• Agentic workflows — multi-step tasks where an AI plans, browses, and acts across web and mobile

Why this exists: Most automation stacks ship 200MB of opinions before you write a line of code. These don't. Install, import, go.

License

Apache-2.0 — see LICENSE.