bwb-browser

# bwb-browser **Browser Without Bloat** — ~173KB of source, 65 kB tarball. 26 tools. Static-first. Runs on your phone, survives it too. A lightweight MCP server that gives any AI agent browser superpowers. Written by a guy in India on Termux because the existing tools were 200MB of "why" — then rewritten when Android kept killing those tools mid-run. --- ## v4: The Browser Starts Only When It Must v1–v3 made the server light but spawned Chromium for everything — including reading a README. Android's out-of-memory killer ate whole Termux sessions for that. v4 inverts the default: - **Static-first fetch ladder** — plain pages are fetched + extracted with zero Chromium. `browser_goto` returns `mode: "static"` in milliseconds. JS pages escalate to CDP automatically (`mode: "browser"` + reason). Dead URLs error without spawning anything. - **Vigilance system** — every tool response carries a `[bwb resources]` footer. On critical pressure bwb hibernates tabs itself, tears down at one tab, journals everything, and tells the agent what it did. - **Survival profile** — `--lean` auto-enables on Termux (capped renderers, 3-tab cap, 5-minute mayfly teardown, 256MB JS heap). Runs on a 1GB VPS. Your tabs resurrect from the journal after any kill. - **On-demand capabilities** — `browser_download` / `browser_export` ship as verbs, not weight. Missing backends (yt-dlp, reportlab) prompt for consent install. Nothing heavy is ever bundled. Measured on-device: a single YouTube tab costs **746MB** of Chromium tree. That's why the ladder exists. --- ## The Pitch (60 seconds) Every other MCP browser tool ships a full browser binary. Playwright MCP? ~250MB. Puppeteer MCP? ~400MB. Chrome DevTools MCP? ~350MB. bwb speaks **Chrome DevTools Protocol (CDP)** — the protocol Chrome speaks natively — through one thin CDP client (`chrome-remote-interface`). No Playwright, no Puppeteer, no browser binary. It auto-detects the browser already on your system. No downloads. No binary mismatches. No "why is my disk full" panic. | Factor | bwb v4 | Playwright MCP | Puppeteer MCP | |--------|-----|----------------|---------------| | Source size | **~173KB** | ~50MB+ | ~100MB+ | | Published tarball | **65 kB** | — | — | | Total install (npm) | **~62MB, zero browsers** | ~250MB | ~400MB | | Bundled browser | **None** | Chromium (~200MB) | Chromium (~300MB) | | Chromium spawns for plain pages | **Never (static-first)** | Always | Always | | Works on Termux/Android | **✅ Yes** | ❌ | ❌ | | Survives 1GB RAM / phone OOM | **✅ Lean profile + vigilance** | ❌ | ❌ | | Zero native deps | **✅ Yes** | ❌ | ❌ | | Runtime dependencies | **5** | many | many | | Live event streaming | **✅** | ❌ | ❌ | | Natural language interaction | **✅** | ❌ | ❌ | | Persistent sessions | **✅** | ❌ | ❌ | | CPU profile at idle | Mayfly teardown (Termux) | 🐌 | 🐌 | --- ## 🔥 The Features That Actually Matter ### 1. `browser_act` — Talk to the Browser Like a Human ```javascript browser_act({instruction: "search for laptops under a thousand dollars"}) ``` No `findElement` hell. No chaining 10 calls. bwb parses what you want, finds the right elements, interacts, and returns the result. Pure DOM heuristics — no LLM dependency, no API costs, no "the AI is thinking..." spinner. ### 2. `browser_watch` — See What the Page Is Doing Your agent can **listen** to the page: ```javascript browser_watch({action: "start", events: ["console", "network"]}) // ... do stuff ... const events = browser_watch({action: "poll"}) // → [{type: "console", text: "React mounted"}, {type: "network", url: "https://api.example.com/data", status: 200}] ``` Console logs. Network requests. JS exceptions. Page navigations. Your agent isn't flying blind anymore. ### 3. "Login Once, Agent Works for Days" ```javascript // Monday: Login browser_saveCookies({name: "gmail"}) // Wednesday: Still logged in. Fresh browser. Zero fuss. browser_loadCookies({name: "gmail"}) browser_goto({url: "https://gmail.com"}) // Already authenticated ``` Sessions survive agent restarts and server restarts. Copying the file to another machine *may* work, but many sites bind sessions to IP, user-agent and device — assume it does not. ⚠️ The session file holds **live login credentials** in `~/.bwb/sessions/` (mode `600`). Pass `domains: ["gmail.com"]` to `browser_saveCookies` to store less. Treat the file like a password. ### 4. `browser_diagnose` — Lighthouse for Your AI Agent One call gets you: load timings, console errors, broken images, meta tags, interaction counts, and a heuristic health score (a weighted penalty sum — not a Lighthouse audit). Your agent can self-diagnose instead of guessing. ### 5. Multi-Tab & Sessions Create tabs, close them, switch between them, save cookies, load them back. Like a real browser. Because it is one. ### 6. Realistic Browser Profile Applies the usual anti-detection patches — `navigator.webdriver`, plugins, languages, and a user agent derived from the real Chromium build. That *is* what "stealth mode" means; the difference is intent: use it on sites you own or have permission to test, and you get tests that match real user conditions. ### 7. Element Screenshots Capture just one element — a login form, a chart, a product card — not the whole page: ```javascript browser_screenshot({selector: "#price-chart"}) browser_screenshot({selector: "h1"}) // The headline, cropped browser_screenshot({fullPage: true}) // The whole page browser_screenshot({}) // Just the viewport ``` Every screenshot is saved to disk (Android: `/storage/emulated/0/Download/bwb-screenshots/`, desktop: `~/bwb-screenshots/`) **and** returned to your agent as a base64 image. The newest 50 are kept (`BWB_SHOT_KEEP`). --- ## Security Notes bwb drives a **real, logged-in browser** on behalf of a model that is reading pages it does not control. The defaults are chosen for that, and they are not all comfortable: - **Only http/https.** `file:`, `javascript:`, `data:`, `chrome:`, `devtools:` and `view-source:` are refused — a page that tells your agent to "open file:///… and summarize it" gets an error, not your files. - **No SSRF.** Static fetches refuse loopback, private, link-local and CGNAT addresses (127/8, 10/8, 172.16/12, 192.168/16, 169.254/16, `::1`, `fc00::/7`) — including every redirect hop. On a cloud box that is the difference between "reads a website" and "reads the metadata service". Local development: `BWB_ALLOW_PRIVATE=1`. - **The Chromium sandbox stays on.** `--no-sandbox` is applied only where it must be: Termux, running as root, or if you pass `BWB_NO_SANDBOX=1`. - **Cookies at rest are credentials.** `~/.bwb/sessions/*.json` is `600` in a `700` directory and holds live logins for every domain visited. `domains: [...]` limits it. - **The tab journal stores origin + path only**, so OAuth callbacks, magic links and reset tokens never land on disk. Stale URLs are not auto-replayed on desktop. - **`browser_export` cannot write outside its directory.** No arbitrary `output_path`. - **`--readonly`** disables every state-changing tool (click, fill, eval, act, export, download, tab mutation) for browsing untrusted sites. - **`browser_act` refuses destructive clicks** ("Delete account", "Buy now", "Send") unless you pass `force:true`, and returns `candidates` rather than guessing when a label is ambiguous. - **Page content is untrusted.** Anything these tools return from a page is attacker-controlled input. Instructions inside it are data, not commands. Do not let page text talk your agent into `browser_eval`, `browser_export` or `browser_download`. --- ## What's New — 4.1.0 ### It was quietly doing the wrong thing. Now it doesn't. - **`browser_act` typed in lowercase.** Every pattern matched `instruction.toLowerCase()` and then typed the captured group, so `fill password with MyS3cretPass` sent `mys3cretpass`. Case is preserved everywhere now, and secrets are redacted from the result instead of echoed back. - **`browser_act` clicked the wrong element.** It built a CSS selector from the match and re-queried it, so `click the Pricing link` became selector `a` and clicked **Home**. Elements are now scored, scrolled, measured and tagged inside one `Runtime.evaluate`; ambiguous matches return `candidates` instead of a coin flip; destructive labels need `force:true`. - **Static fetch mangled every non-English page.** It decoded each network chunk separately, so a Hindi/CJK/emoji page split at a byte boundary came back as `U+FFFD` soup (1,445 replacement characters in the repro). Chunks are concatenated as bytes and decoded once, with the declared charset. - **`browser_goto` and every other tool were looking at different pages.** A static result left Chromium on `about:blank`, so the next `browser_text` returned nothing, and the static rung ignored loaded cookies (a logged-out page, reported at `confidence: "high"`). The URL is now carried across and materialized on demand. - **`npm test` did not test.** `node --check server.mjs && node --check lib/*.mjs` — `node --check` takes one file, so a syntax error in `lib/` exited 0. Now: a real suite, `npm run lint`, and CI on Node 18/20/22. ### Security, honestly - URL policy: http(s) only, no `file:`/`javascript:`, no loopback/private/metadata addresses on any redirect hop. - Chromium's sandbox is on unless you are on Termux, root, or ask for `--no-sandbox`. - Session cookies are `600` in a `700` directory; the tab journal keeps origin+path only. - `browser_export` writes only inside its export directory. `browser_download` uses no shell. - `--readonly` for browsing untrusted sites. ### Static-first fetch ladder (4.0) - **`browser_goto` does not spawn Chromium for plain pages** — fetch + extract in milliseconds (`mode: "static"`). JS pages escalate automatically (`mode: "browser"` + reason). Dead URLs error without spawning anything. JSON/XML/CSV/`robots.txt` are served statically too. ### Vigilance system (4.0) - **Every tool response carries a `[bwb resources]` footer** — MCP + Chromium MB, tabs, ok/watch/critical. `browser_watch` streams memory samples on its existing poll rhythm. - **Thresholds act, then report** — critical pressure hibernates tabs, journals everything, and tells the agent. It only tears the browser down after two consecutive critical samples, and never during a watch. ### Survival profile (4.0) - **`--lean` auto-enables on Termux** — capped renderers, silenced background services, 3-tab cap, 5-minute mayfly teardown, 256MB JS heap. `--nuclear` opts into `--single-process`. - **Tab journal + lazy restore** — kills become resume points, not disasters. `bwb --setup` prints a survival guide. ### Breaking - `browser_title` + `browser_url` folded into `browser_status.targets` (4.0). Still 26 tools — that's a release gate, enforced in CI. - `browser_export` lost `pdf`/`docx`/`pptx`. They reported `{ready: true}` and wrote nothing. Markdown, txt and html remain. - `browser_goto` takes `mode` and `maxChars`; `browser_saveCookies` takes `domains`. `bwb --setup` is a dry run unless you pass `--yes`. *Full story in the [changelog](./CHANGELOG.md). Older releases documented there too.* --- ## Quick Install ```bash npm install -g bwb-browser bwb --setup --yes # writes the MCP entry into your agent's config bwb --version # → bwb-browser 4.1.0 ``` `bwb --setup` is a **dry run unless you pass `--yes`** — it lists exactly which of your agents' config files it would touch. If you have Chrome/Chromium anywhere on your system, bwb finds it. No config files of your own. No environment variables. Just works. Useful flags when you want less: | Flag | Effect | |------|--------| | `--readonly` | Refuse every state-changing tool | | `--allow-domains a.com,b.com` | Navigation allowlist | | `--always-browser` | Skip the static rung entirely | | `--no-sandbox` | Disable the Chromium sandbox (auto on Termux/root) | | `--attach-port 9222` | Drive a browser you already opened (guest mode) | **On Termux/Android:** ```bash pkg install chromium # One-time npm install -g bwb-browser bwb ``` *Yes, this runs on a phone. Yes, it's fully functional. Yes, I built it this way on purpose.* --- ## All 26 Tools | Tool | Description | |------|-------------| | **`browser_act`** | Natural language — "search for X", "click the button", "what's on this page". Returns `candidates` instead of guessing | | **`browser_watch`** | Live event capture — console, network, errors, navigation | | **`browser_diagnose`** | Full page health check — timings, errors, broken images, score | | **`browser_fingerprint`** | Anti-detection patches for testing sites you own | | `browser_goto` | Navigate — static-first (`mode: auto\|static\|browser`), escalates with a reason | | `browser_screenshot` | Take a screenshot — whole page, viewport, or a single element via `selector` | | `browser_html` | Get page/selector HTML | | `browser_text` | Get page/selector text | | `browser_back` | Go back in history | | `browser_click` | Click an element (native CDP) | | `browser_fill` | Fill an input field (native CDP) | | `browser_elements` | List interactive elements | | `browser_eval` | Execute JavaScript | | `browser_setViewport` | Change viewport size | | `browser_waitForSelector` | Wait for element to appear/disappear | | `browser_newTab` | Create new tab | | `browser_closeTab` | Close a tab | | `browser_switchTab` | Switch to a tab | | `browser_listTabs` | List all tabs | | `browser_saveCookies` | Save session to disk | | `browser_loadCookies` | Load session from disk | | `browser_listSessions` | List saved sessions | | `browser_download` | Download media (needs system yt-dlp, consent-gated) | | `browser_export` | Write md/txt/html into the export directory | | `browser_status` | Status + live resources + active profile | | `browser_restart` | Restart the browser | --- ## Where It Runs | Platform | Status | Notes | |----------|--------|-------| | Termux/Android | ✅ **Verified** | `pkg install chromium`, that's it | | Linux | ✅ **Verified** | Auto-detects Chrome/Chromium | | macOS | ✅ **Verified** | Auto-detects Chrome.app | | Windows | ⚠️ **Supported, untested** | Auto-detects Chrome.exe; `ps`/`which` fallbacks are Linux-only, process sampling degrades to self | | CI (GitHub Actions) | ✅ **Tested** | `npm test` + `npm run smoke` on Node 18/20/22 | | Docker | ⚠️ **Supported, untested** | Chrome in the container; runs as root, so the sandbox is auto-disabled | | Your Raspberry Pi | ✅ Why not | Same npm install | --- ## MCP Agent Integration Add this to any MCP-compatible agent's config: ```json { "mcpServers": { "bwb": { "command": "bwb" } } } ``` Works with: **Claude Code, OpenCode, Antigravity CLI, Cline, Continue.dev, Aider, Codex CLI, Cody, Windsurf, Cursor** — literally anything that speaks MCP. See [AGENTS.md](./AGENTS.md) for copy-paste configs for each one. --- ## The Backstory Every browser automation tool assumes you have 400MB to spare and a desktop-class machine. That assumption excludes phones, cheap VPS boxes, Raspberry Pis, and CI runners — most of the world's computers. bwb is engineered against the hardest constraint first: **a memory-pressured device where every megabyte is contested.** No bundled browser. No wrapper frameworks. Just CDP — the protocol Chrome speaks natively, over one thin client — plus a static-fetch ladder so Chromium only starts when JavaScript demands it. Mobile-first isn't a feature here. It's the design spec everything else has to survive. The result is ~173KB of source that does what 400MB of dependencies do. Not better code — less code, held to budgets: 26 tools max, 5 runtime dependencies, 65 kB tarball, zero native modules. Constraints are features. (The 4.1.0 correctness pass grew the source by ~50KB: a real URL policy, a real element-scoring engine, and the tests that keep them honest.) *— Krish Tiwari ([@krshforever](https://github.com/krshforever))* --- ## Roadmap - **bwb Cloud** — hosted browser instances so your agent has a browser even when your laptop's asleep. (The URL policy in 4.1.0 is what makes this safe to offer; prompt injection becomes a server-side problem there.) - **`browser_act` v2** — multi-step with feedback loops (not just "search for X" but "research this topic and summarize") - **Recording & Replay** — record sessions, replay them, debug them - **Browser pool** — multiple isolated instances for CI parallelization --- ## Support If bwb saves you time, money, or a few brain cells: - [GitHub Sponsors](https://github.com/sponsors/krshforever) No gating. No "pro" tier. No bait-and-switch. The code is MIT forever. If you can't or won't pay, that's genuinely fine — I built this because I wanted it to exist. --- ## License MIT — Krish Tiwari ([@krshforever](https://github.com/krshforever))