convez.ai
MCP ServerIntegração & APIsIntermediário
hamr0

BareBrowse

hamr0/barebrowse

Navegador real para agentes com 40-90% menos tokens

Ver no GitHub
BomPluginScore · de 0 a 100

MCP server que fornece a agentes IA um navegador real com suporte a sessões autenticadas, cookies e logins. Extrai snapshots ARIA e texto legível de páginas, reduzindo tokens em 40-90% comparado a saídas brutas. Substitui Playwright, Selenium e Puppeteer com zero dependências pesadas.

Instalação

$npx convez-ai hamr0/barebrowse

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
46
Forks
2
Acompanhando
0
Saúde
42%
Último commit
há 1 dia
Versão
v0.11.0
Issues abertas
0
Contribuidores
1

Casos de uso

  • Agentes navegando sites com autenticação mantida
  • Extração de conteúdo legível de páginas web
  • Interação automatizada (cliques, digitação, scroll) em navegador real
  • Testes de UI e captura de estado de páginas
  • Redução drástica de consumo de tokens em tarefas web

Veredito

Solução pragmática e minimalista para agentes navegarem a web. Resolve gargalo real (tokens desperdiçados em HTML bruto) com arquitetura limpa e zero dependências desnecessárias — recomendado para projetos que precisam de navegação autenticada robusta.

README

A tradução para o português deste README ainda está na fila.

  ~~~~~~~~~~~~~~~~~~~~
  ~~~ .---------. ~~~
  ~~~ | · 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. No bundled browser. No 200MB download. Two tiny dependencies (ws + Mozilla Readability).

Install

npm install barebrowse

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

Ships with TypeScript types (generated from JSDoc) — autocomplete and type-checking work out of the box, no @types/barebrowse needed. The library is vanilla JS with no build step.

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 readable                    # Clean article text → .barebrowse/article-*.txt
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"]
    }
  }
}

19 tools: browse, goto, snapshot, readable, 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 (18 tools, auto-snapshot after every action).

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

Three modes

ModeWhat happensBest for
Headless (default)Launches a fresh Chromium, no UIFast automation, scraping, reading pages
HeadedAuto-launches a visible Chromium windowBot-detected sites, visual debugging, CAPTCHAs
HybridTries headless first, auto-launches headed if blockedGeneral-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.

PageRawPrunedReduction
example.com377 chars45 chars88%
Hacker News51,726 chars27,197 chars47%
Wikipedia (article)109,479 chars40,566 chars63%
DuckDuckGo42,254 chars5,407 chars87%

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:

ActionWhat it does
NavigateLoad a URL, wait for page load, auto-dismiss consent
Back / ForwardBrowser history navigation
SnapshotPruned ARIA tree with [ref=N] markers. Two modes: act (buttons, links, inputs) and read (full text). 40-90% token reduction.
ReadableClean article text (title + body, chrome stripped — Reader-View engine). For reading article-like pages, not interacting. Advisory confidence; falls back to snapshot on non-articles.
ClickScroll into view + mouse click at element center, JS fallback for hidden elements
TypeFocus + insert text, with option to clear existing content first
PressSpecial keys: Enter, Tab, Escape, Backspace, Delete, arrows, Space
ScrollMouse wheel up or down (accepts direction or pixels)
HoverMove mouse to element center (triggers tooltips, hover states)
SelectSet dropdown value (native select or custom dropdown)
DragDrag one element to another (Kanban boards, sliders)
UploadSet files on a file input element
ScreenshotPage capture as base64 PNG/JPEG/WebP
PDFExport page as PDF
AssessPrivacy 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.
TabsList open tabs, switch between them
Wait for contentPoll for text or CSS selector to appear on page
Wait for navigationSPA-aware: works for full page loads and pushState
Wait for network idleResolve when no pending requests for 500ms
Dialog handlingAuto-dismiss JS alert/confirm/prompt dialogs
Save stateExport cookies + localStorage to JSON
Inject cookiesExtract from Firefox/Chromium and inject via CDP
Raw CDPEscape 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

14 modules, ~3,000 lines, two small dependencies (ws, @mozilla/readability).

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

Local-first, composable agent infrastructure. Same API patterns throughout — mix and match, each module works standalone.

Core — the brain, the gate, the memory.

  • bareagent — the think→act→observe loop. Goal in → coordinated actions out. Replaces LangChain, CrewAI, AutoGen.
  • bareguard — the single gate every action passes through. Action in → allow / deny / ask-a-human out. Replaces hand-rolled allowlists and scattered policy code.
  • litectx — tree-sitter code + memory graph with activation decay, plus lightweight context engineering (write · select · compress · isolate). Query in → ranked context out.

Optional reach — give the agent hands.

  • barebrowse — a real browser for agents. URL in → pruned snapshot out. Replaces Playwright, Selenium, Puppeteer.
  • baremobile — Android + iOS device control. Screen in → pruned snapshot out. Replaces Appium, Espresso, XCUITest.
  • beeperbox — 50+ messaging networks via one MCP server (headless Beeper Desktop in Docker). Chat in → unified message stream out. Replaces Twilio, per-platform bot APIs.

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.

Ver o original no GitHub

Bom para

Relacionados