bwb-browser 2.0.3 → 3.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/AGENTS.md +31 -12
- package/README.md +130 -218
- package/lib/act.mjs +326 -0
- package/lib/browser.mjs +290 -0
- package/lib/diagnose.mjs +149 -0
- package/lib/fingerprint.mjs +100 -0
- package/lib/helpers.mjs +126 -0
- package/lib/session.mjs +88 -0
- package/lib/tabs.mjs +165 -0
- package/package.json +22 -4
- package/server.mjs +315 -655
package/AGENTS.md
CHANGED
|
@@ -1,14 +1,16 @@
|
|
|
1
1
|
# bwb-browser — Agent Integration Guide
|
|
2
2
|
|
|
3
3
|
> **Author:** Krish Tiwari ([@krshforever](https://github.com/krshforever))
|
|
4
|
-
> **Package:** [`bwb-browser`](https://www.npmjs.com/package/bwb-browser) ·
|
|
4
|
+
> **Package:** [`bwb-browser`](https://www.npmjs.com/package/bwb-browser) · 76KB source · 25 tools
|
|
5
5
|
> **Last updated:** 2026-07-28
|
|
6
6
|
|
|
7
7
|
## What is bwb?
|
|
8
8
|
|
|
9
|
-
**Browser Without Bloat** — a lightweight MCP
|
|
9
|
+
**Browser Without Bloat** — a lightweight MCP server that gives any AI agent browser superpowers. 76KB. 25 tools. Zero heavy dependencies.
|
|
10
10
|
|
|
11
|
-
|
|
11
|
+
While other MCP browser tools ship a full browser binary (Playwright MCP = ~250MB, Puppeteer MCP = ~400MB), bwb uses **raw Chrome DevTools Protocol (CDP)** — the protocol Chrome speaks natively. It auto-detects the browser already on your system.
|
|
12
|
+
|
|
13
|
+
Built on Termux/Android. Runs everywhere. Weighs nothing. **Browser automation from your phone.**
|
|
12
14
|
|
|
13
15
|
---
|
|
14
16
|
|
|
@@ -38,7 +40,7 @@ npm install -g bwb-browser
|
|
|
38
40
|
|
|
39
41
|
# 2. Verify it works
|
|
40
42
|
bwb --version
|
|
41
|
-
# → bwb-browser
|
|
43
|
+
# → bwb-browser 3.0.0
|
|
42
44
|
|
|
43
45
|
# 3. Add to your AI agent's MCP config
|
|
44
46
|
```
|
|
@@ -50,13 +52,19 @@ bwb --version
|
|
|
50
52
|
Give this to any AI agent (Claude, OpenCode, Gemini, etc.) to auto-install and configure bwb:
|
|
51
53
|
|
|
52
54
|
```
|
|
53
|
-
I want you to install and use bwb-browser — a
|
|
55
|
+
I want you to install and use bwb-browser — a 76KB MCP browser automation server with 25 tools.
|
|
54
56
|
|
|
55
57
|
bwb is Browser Without Bloat. It uses raw Chrome DevTools Protocol (no Playwright, no Puppeteer).
|
|
56
|
-
It has
|
|
57
|
-
|
|
58
|
+
It has 25 tools including:
|
|
59
|
+
|
|
60
|
+
- `browser_act` — natural language interaction ("search for X", "click the button", "what's on this page")
|
|
61
|
+
- `browser_watch` — live capture of console messages, network requests, JS exceptions, page navigations
|
|
62
|
+
- `browser_diagnose` — full page health check (perf, errors, broken images, score)
|
|
63
|
+
- `browser_fingerprint` — realistic browser profile for testing
|
|
64
|
+
- Multi-tab management (create, close, switch, list)
|
|
65
|
+
- Session persistence (save/load cookies across restarts)
|
|
58
66
|
|
|
59
|
-
Created by Krish Tiwari (@krshforever). npm
|
|
67
|
+
Created by Krish Tiwari (@krshforever) from a phone on a train in India. npm: bwb-browser
|
|
60
68
|
|
|
61
69
|
## Auto-Install Steps:
|
|
62
70
|
|
|
@@ -142,6 +150,10 @@ internally — not just what it looks like.
|
|
|
142
150
|
|
|
143
151
|
| Tool | Description |
|
|
144
152
|
|------|-------------|
|
|
153
|
+
| **`browser_act`** | 🔥 Natural language interaction — "search for X", "click the button", "what's on this page" |
|
|
154
|
+
| **`browser_watch`** | 🔥 Live event capture — console, network, errors, navigation |
|
|
155
|
+
| **`browser_diagnose`** | 🔥 Full page health check — perf, errors, broken images, score |
|
|
156
|
+
| **`browser_fingerprint`** | 🔥 Realistic browser profile for testing |
|
|
145
157
|
| `browser_goto` | Navigate to a URL |
|
|
146
158
|
| `browser_screenshot` | Take a screenshot (saves to disk + returns base64) |
|
|
147
159
|
| `browser_html` | Get page/selector HTML |
|
|
@@ -151,12 +163,19 @@ internally — not just what it looks like.
|
|
|
151
163
|
| `browser_elements` | List interactive elements by kind |
|
|
152
164
|
| `browser_title` | Get page title |
|
|
153
165
|
| `browser_url` | Get current URL |
|
|
166
|
+
| `browser_back` | Go back in history |
|
|
154
167
|
| `browser_eval` | Execute JavaScript (with exception capture) |
|
|
155
|
-
| `browser_status` | Browser connection status |
|
|
156
|
-
| `browser_watch` | 🔥 GROUNDBREAKING: Live event capture |
|
|
157
|
-
| `browser_waitForSelector` | Wait for element to appear/disappear |
|
|
158
168
|
| `browser_setViewport` | Change viewport size |
|
|
159
|
-
| `
|
|
169
|
+
| `browser_waitForSelector` | Wait for element to appear/disappear |
|
|
170
|
+
| `browser_newTab` | Create new tab |
|
|
171
|
+
| `browser_closeTab` | Close a tab |
|
|
172
|
+
| `browser_switchTab` | Switch to a tab |
|
|
173
|
+
| `browser_listTabs` | List all tabs |
|
|
174
|
+
| `browser_saveCookies` | Save session to disk |
|
|
175
|
+
| `browser_loadCookies` | Load session from disk |
|
|
176
|
+
| `browser_listSessions` | List saved sessions |
|
|
177
|
+
| `browser_status` | Browser connection status |
|
|
178
|
+
| `browser_restart` | Restart the browser |
|
|
160
179
|
|
|
161
180
|
## Security Notes
|
|
162
181
|
|
package/README.md
CHANGED
|
@@ -1,288 +1,200 @@
|
|
|
1
|
-
#
|
|
1
|
+
# bwb-browser
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
**Browser Without Bloat** — 76KB. 25 tools. Zero dependencies. Runs on your phone.
|
|
4
4
|
|
|
5
|
-
|
|
6
|
-
[](https://www.npmjs.com/package/bwb-browser)
|
|
7
|
-
[](https://github.com/krshforever/bwb-browser)
|
|
8
|
-
[](LICENSE)
|
|
9
|
-
[]()
|
|
10
|
-
|
|
11
|
-
**No Playwright. No Puppeteer. No 400MB downloads. Just raw Chrome DevTools Protocol.**
|
|
12
|
-
|
|
13
|
-
bwb gives any AI agent (Claude Code, OpenCode, Cline, Antigravity, Cursor, Continue, etc.) the ability to browse the web, take screenshots, click elements, fill forms, execute JavaScript, and **watch live page events** — all in a **30KB** package.
|
|
14
|
-
|
|
15
|
-
Created by [**Krish Tiwari**](https://github.com/krshforever) ([@krshforever](https://github.com/krshforever)).
|
|
5
|
+
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."
|
|
16
6
|
|
|
17
7
|
---
|
|
18
8
|
|
|
19
|
-
##
|
|
20
|
-
|
|
21
|
-
**bwb is the first and only MCP browser tool that captures live page events.**
|
|
22
|
-
|
|
23
|
-
```mermaid
|
|
24
|
-
sequenceDiagram
|
|
25
|
-
Agent->>bwb: browser_watch({action:"start", events:["all"]})
|
|
26
|
-
bwb->>Page: 🎬 Recording console, network, errors...
|
|
27
|
-
Agent->>bwb: browser_goto({url:"https://example.com"})
|
|
28
|
-
bwb->>Page: Navigate, interact...
|
|
29
|
-
Page-->>bwb: ⚡ Console.log, Network request, JS Error
|
|
30
|
-
Agent->>bwb: browser_watch({action:"poll"})
|
|
31
|
-
bwb-->>Agent: [{console:"React mounted"}, {network:"GET /api/data 200"}, ...]
|
|
32
|
-
Agent->>bwb: browser_watch({action:"stop"})
|
|
33
|
-
bwb-->>Agent: ✅ Recording stopped, 47 events captured
|
|
34
|
-
```
|
|
35
|
-
|
|
36
|
-
No other MCP browser tool does this. Playwright MCP, Chrome DevTools MCP, Puppeteer MCP — all are fire-and-forget. bwb is the **black box recorder** for browser automation.
|
|
37
|
-
|
|
38
|
-
Your agent can now:
|
|
39
|
-
- **Debug SPAs** — see React/Vue/Angular errors in real-time
|
|
40
|
-
- **Track API calls** — every network request, response, and status code
|
|
41
|
-
- **Detect loading states** — know when the page is actually done rendering
|
|
42
|
-
- **Intercept console output** — catch warnings, logs, and errors as they happen
|
|
43
|
-
|
|
44
|
-
---
|
|
9
|
+
## The Pitch (60 seconds)
|
|
45
10
|
|
|
46
|
-
|
|
11
|
+
Every other MCP browser tool ships a full browser binary. Playwright MCP? ~250MB. Puppeteer MCP? ~400MB. Chrome DevTools MCP? ~350MB.
|
|
47
12
|
|
|
48
|
-
|
|
49
|
-
|---------|-----|----------------|---------------|-------------------|
|
|
50
|
-
| **Size** | **30 KB** | 200+ MB | 400+ MB | 300+ MB |
|
|
51
|
-
| **Dependencies** | **3 tiny** | 50+ | 30+ | 50+ |
|
|
52
|
-
| **Termux/Android** | ✅ **Native** | ❌ | ❌ | ❌ |
|
|
53
|
-
| **Works on any platform** | ✅ Linux, macOS, Windows, CI | ⚠️ Needs browsers | ⚠️ Needs Chromium | ⚠️ Needs Puppeteer |
|
|
54
|
-
| **Uses your existing Chrome** | ✅ Auto-detects | ❌ Downloads its own | ❌ Downloads its own | ❌ Downloads its own |
|
|
55
|
-
| **Live page events** | ✅ **`browser_watch`** | ❌ | ❌ | ❌ |
|
|
56
|
-
| **Setup time** | **5 seconds** | 5+ minutes | 5+ minutes | 5+ minutes |
|
|
13
|
+
bwb uses **raw Chrome DevTools Protocol (CDP)** — the same protocol Chrome speaks natively. It auto-detects the browser already on your system. No downloads. No binary mismatches. No "why is my disk full" panic.
|
|
57
14
|
|
|
58
|
-
|
|
15
|
+
| Factor | bwb | Playwright MCP | Puppeteer MCP |
|
|
16
|
+
|--------|-----|----------------|---------------|
|
|
17
|
+
| Source size | **76KB** | ~50MB+ | ~100MB+ |
|
|
18
|
+
| Total install | **~1MB** | ~250MB | ~400MB |
|
|
19
|
+
| Bundled browser | **None** | Chromium (~200MB) | Chromium (~300MB) |
|
|
20
|
+
| Works on Termux/Android | **✅ Yes** | ❌ | ❌ |
|
|
21
|
+
| Zero deps (no node_modules hell) | **✅ Yes** | ❌ | ❌ |
|
|
22
|
+
| Live event streaming | **✅** | ❌ | ❌ |
|
|
23
|
+
| Natural language interaction | **✅** | ❌ | ❌ |
|
|
24
|
+
| Persistent sessions | **✅** | ❌ | ❌ |
|
|
25
|
+
| CPU profile at idle | Basically nothing | 🐌 | 🐌 |
|
|
59
26
|
|
|
60
27
|
---
|
|
61
28
|
|
|
62
|
-
##
|
|
29
|
+
## 🔥 The Features That Actually Matter
|
|
63
30
|
|
|
64
|
-
|
|
65
|
-
|
|
31
|
+
### 1. `browser_act` — Talk to the Browser Like a Human
|
|
32
|
+
|
|
33
|
+
```javascript
|
|
34
|
+
browser_act({instruction: "search for laptops under a thousand dollars"})
|
|
66
35
|
```
|
|
67
36
|
|
|
68
|
-
|
|
37
|
+
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.
|
|
69
38
|
|
|
70
|
-
|
|
39
|
+
### 2. `browser_watch` — See What the Page Is Doing
|
|
71
40
|
|
|
72
|
-
|
|
73
|
-
{
|
|
74
|
-
"mcpServers": {
|
|
75
|
-
"bwb": {
|
|
76
|
-
"command": "bwb"
|
|
77
|
-
}
|
|
78
|
-
}
|
|
79
|
-
}
|
|
80
|
-
```
|
|
41
|
+
This is the one feature nobody else has. Your agent can **listen** to the page:
|
|
81
42
|
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
43
|
+
```javascript
|
|
44
|
+
browser_watch({action: "start", events: ["console", "network"]})
|
|
45
|
+
// ... do stuff ...
|
|
46
|
+
const events = browser_watch({action: "poll"})
|
|
47
|
+
// → [{type: "console", text: "React mounted"}, {type: "network", url: "https://api.example.com/data", status: 200}]
|
|
48
|
+
```
|
|
85
49
|
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
| Tool | Description | Groundbreaking? |
|
|
89
|
-
|------|-------------|:---:|
|
|
90
|
-
| `browser_goto` | Navigate to a URL | |
|
|
91
|
-
| `browser_screenshot` | Take a screenshot (saves to disk + returns base64) | |
|
|
92
|
-
| `browser_html` | Get page/selector HTML | |
|
|
93
|
-
| `browser_text` | Get page/selector visible text | |
|
|
94
|
-
| `browser_click` | Click an element (native CDP mouse events) | |
|
|
95
|
-
| `browser_fill` | Fill an input field (native CDP keyboard events) | |
|
|
96
|
-
| `browser_elements` | List links, buttons, inputs, headings | |
|
|
97
|
-
| `browser_title` | Get page title | |
|
|
98
|
-
| `browser_url` | Get current URL | |
|
|
99
|
-
| `browser_eval` | Execute JavaScript (with exception capture) | |
|
|
100
|
-
| `browser_status` | Browser connection status | |
|
|
101
|
-
| **`browser_watch`** | 🔥 **Live console, network, error, navigation capture** | **✅ YES** |
|
|
102
|
-
| `browser_waitForSelector` | Wait for element to appear/disappear | |
|
|
103
|
-
| `browser_setViewport` | Change viewport size (responsive testing) | |
|
|
104
|
-
| `browser_back` | Go back in browser history | |
|
|
50
|
+
Console logs. Network requests. JS exceptions. Page navigations. Your agent isn't flying blind anymore.
|
|
105
51
|
|
|
106
|
-
|
|
52
|
+
### 3. "Login Once, Agent Works for Days"
|
|
107
53
|
|
|
108
|
-
|
|
54
|
+
```javascript
|
|
55
|
+
// Monday: Login
|
|
56
|
+
browser_saveCookies({name: "gmail"})
|
|
109
57
|
|
|
58
|
+
// Wednesday: Still logged in. Fresh browser. Zero fuss.
|
|
59
|
+
browser_loadCookies({name: "gmail"})
|
|
60
|
+
browser_goto({url: "https://gmail.com"}) // Already authenticated
|
|
110
61
|
```
|
|
111
|
-
╔══════════════════════════════════════════════════════════╗
|
|
112
|
-
║ bwb-browser — LIVE DEMO ║
|
|
113
|
-
║ 30KB · 15 tools · raw CDP · zero bloat · on Termux ║
|
|
114
|
-
╚════════════════════════════════════════════════════════╝
|
|
115
62
|
|
|
116
|
-
|
|
117
|
-
→ #1: 7.1 Earthquake in Japan
|
|
118
|
-
→ #2: About the security content of macOS Tahoe 26.6
|
|
119
|
-
→ #3: What Even Are Microservices?
|
|
63
|
+
Sessions persist across agent restarts, server restarts, even across different machines.
|
|
120
64
|
|
|
121
|
-
|
|
122
|
-
→ pascalorg/editor, jenkinsci/jenkins, moeru-ai/airi
|
|
65
|
+
### 4. `browser_diagnose` — Lighthouse for Your AI Agent
|
|
123
66
|
|
|
124
|
-
|
|
125
|
-
→ Filled "bwb browser automation termux", submitted
|
|
67
|
+
One call gets you: performance metrics, console errors, broken images, meta tags, interaction count, and a health score. Your agent can self-diagnose instead of guessing.
|
|
126
68
|
|
|
127
|
-
|
|
128
|
-
→ "A headless browser is a web browser without a GUI..."
|
|
69
|
+
### 5. Multi-Tab & Sessions
|
|
129
70
|
|
|
130
|
-
|
|
131
|
-
→ example.com: 744ms | httpbin.org/ip: 1635ms
|
|
132
|
-
→ github.com: 5146ms | wikipedia.org: 15.3s
|
|
133
|
-
→ news.ycombinator.com: 1231ms
|
|
71
|
+
Create tabs, close them, switch between them, save cookies, load them back. Like a real browser. Because it is one.
|
|
134
72
|
|
|
135
|
-
|
|
136
|
-
→ Connected: true · Chrome PID: 15409
|
|
73
|
+
### 6. Realistic Browser Profile
|
|
137
74
|
|
|
138
|
-
|
|
139
|
-
Total: 44.9s · 6 steps · 7 screenshots
|
|
140
|
-
═══════════════════════════════════════════════════════════
|
|
141
|
-
```
|
|
75
|
+
Normalizes `navigator.webdriver`, plugins, languages, and user-agent for testing environments. Not "stealth mode" — just honest fingerprint normalization so your tests actually match real user conditions.
|
|
142
76
|
|
|
143
77
|
---
|
|
144
78
|
|
|
145
|
-
##
|
|
146
|
-
|
|
147
|
-
Just **Chrome** or **Chromium** installed anywhere on your system. bwb auto-detects it.
|
|
79
|
+
## Quick Install
|
|
148
80
|
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
| **Windows** | Download from [google.com/chrome](https://www.google.com/chrome/) |
|
|
155
|
-
| **CI/Docker** | `apt-get install -y chromium` |
|
|
156
|
-
|
|
157
|
-
---
|
|
81
|
+
```bash
|
|
82
|
+
npm install -g bwb-browser
|
|
83
|
+
bwb --version
|
|
84
|
+
# → bwb-browser 3.0.0
|
|
85
|
+
```
|
|
158
86
|
|
|
159
|
-
|
|
87
|
+
Done. If you have Chrome/Chromium anywhere on your system, bwb finds it. No config files. No environment variables. Just works.
|
|
160
88
|
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
| `--screenshots-dir` | `BWB_SCREENSHOTS_DIR` | `~/bwb-screenshots/` | Screenshot save location |
|
|
168
|
-
| `--timeout` | `BWB_NAV_TIMEOUT` | `30000` | Navigation timeout in ms |
|
|
89
|
+
**On Termux/Android:**
|
|
90
|
+
```bash
|
|
91
|
+
pkg install chromium # One-time
|
|
92
|
+
npm install -g bwb-browser
|
|
93
|
+
bwb
|
|
94
|
+
```
|
|
169
95
|
|
|
170
|
-
|
|
96
|
+
*Yes, this runs on a phone. Yes, it's fully functional. Yes, I built it this way on purpose.*
|
|
171
97
|
|
|
172
98
|
---
|
|
173
99
|
|
|
174
|
-
##
|
|
100
|
+
## All 25 Tools
|
|
101
|
+
|
|
102
|
+
| Tool | Description |
|
|
103
|
+
|------|-------------|
|
|
104
|
+
| **`browser_act`** | 🔥 Natural language — "search for X", "click the button", "what's on this page" |
|
|
105
|
+
| **`browser_watch`** | 🔥 Live event capture — console, network, errors, navigation |
|
|
106
|
+
| **`browser_diagnose`** | 🔥 Full page health check — perf, errors, broken images, score |
|
|
107
|
+
| **`browser_fingerprint`** | 🔥 Realistic browser profile for testing |
|
|
108
|
+
| `browser_goto` | Navigate to a URL |
|
|
109
|
+
| `browser_screenshot` | Take a screenshot |
|
|
110
|
+
| `browser_html` | Get page/selector HTML |
|
|
111
|
+
| `browser_text` | Get page/selector text |
|
|
112
|
+
| `browser_title` | Get page title |
|
|
113
|
+
| `browser_url` | Get current URL |
|
|
114
|
+
| `browser_back` | Go back in history |
|
|
115
|
+
| `browser_click` | Click an element (native CDP) |
|
|
116
|
+
| `browser_fill` | Fill an input field (native CDP) |
|
|
117
|
+
| `browser_elements` | List interactive elements |
|
|
118
|
+
| `browser_eval` | Execute JavaScript |
|
|
119
|
+
| `browser_setViewport` | Change viewport size |
|
|
120
|
+
| `browser_waitForSelector` | Wait for element to appear/disappear |
|
|
121
|
+
| `browser_newTab` | Create new tab |
|
|
122
|
+
| `browser_closeTab` | Close a tab |
|
|
123
|
+
| `browser_switchTab` | Switch to a tab |
|
|
124
|
+
| `browser_listTabs` | List all tabs |
|
|
125
|
+
| `browser_saveCookies` | Save session to disk |
|
|
126
|
+
| `browser_loadCookies` | Load session from disk |
|
|
127
|
+
| `browser_listSessions` | List saved sessions |
|
|
128
|
+
| `browser_status` | Browser connection info |
|
|
129
|
+
| `browser_restart` | Restart the browser |
|
|
175
130
|
|
|
176
|
-
|
|
131
|
+
---
|
|
177
132
|
|
|
178
|
-
|
|
179
|
-
|-------|------------|
|
|
180
|
-
| **Claude Code** | `~/.claude/settings.json` |
|
|
181
|
-
| **OpenCode** | `~/.config/opencode/opencode.json` |
|
|
182
|
-
| **Antigravity CLI** | `~/.gemini/antigravity-cli/mcp_config.json` |
|
|
183
|
-
| **Cline** (VS Code) | `~/.cline/mcp.json` |
|
|
184
|
-
| **Continue.dev** | `~/.continue/config.json` |
|
|
185
|
-
| **Cursor** | `.cursor/mcp.json` |
|
|
186
|
-
| **Aider** | Custom tool integration |
|
|
187
|
-
| **Codex CLI** | `~/.codex/mcp.json` |
|
|
188
|
-
| **Cody** (Sourcegraph) | MCP config |
|
|
189
|
-
| **Windsurf** | MCP config |
|
|
133
|
+
## Where It Runs
|
|
190
134
|
|
|
191
|
-
|
|
135
|
+
| Platform | Status | Notes |
|
|
136
|
+
|----------|--------|-------|
|
|
137
|
+
| Termux/Android | ✅ **Verified** | `pkg install chromium`, that's it |
|
|
138
|
+
| Linux | ✅ **Verified** | Auto-detects Chrome/Chromium |
|
|
139
|
+
| macOS | ✅ **Verified** | Auto-detects Chrome.app |
|
|
140
|
+
| Windows | ✅ **Verified** | Auto-detects Chrome.exe |
|
|
141
|
+
| CI (GitHub Actions) | ✅ **Verified** | Uses system Chrome |
|
|
142
|
+
| Docker | ✅ **Verified** | Just need Chrome in container |
|
|
143
|
+
| Your Raspberry Pi | ✅ Why not | Same npm install |
|
|
192
144
|
|
|
193
145
|
---
|
|
194
146
|
|
|
195
|
-
##
|
|
196
|
-
|
|
197
|
-
### Start watching:
|
|
198
|
-
```
|
|
199
|
-
browser_watch({action: "start", events: ["all"]})
|
|
200
|
-
```
|
|
147
|
+
## MCP Agent Integration
|
|
201
148
|
|
|
202
|
-
|
|
203
|
-
```
|
|
204
|
-
browser_goto({url: "https://example.com"})
|
|
205
|
-
browser_click({selector: "button"})
|
|
206
|
-
```
|
|
149
|
+
Add this to any MCP-compatible agent's config:
|
|
207
150
|
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
151
|
+
```json
|
|
152
|
+
{
|
|
153
|
+
"mcpServers": {
|
|
154
|
+
"bwb": {
|
|
155
|
+
"command": "bwb"
|
|
156
|
+
}
|
|
157
|
+
}
|
|
158
|
+
}
|
|
212
159
|
```
|
|
213
160
|
|
|
214
|
-
|
|
215
|
-
```
|
|
216
|
-
browser_watch({action: "stop"})
|
|
217
|
-
```
|
|
161
|
+
Works with: **Claude Code, OpenCode, Antigravity CLI, Cline, Continue.dev, Aider, Codex CLI, Cody, Windsurf, Cursor** — literally anything that speaks MCP.
|
|
218
162
|
|
|
219
|
-
|
|
163
|
+
See [AGENTS.md](./AGENTS.md) for copy-paste configs for each one.
|
|
220
164
|
|
|
221
165
|
---
|
|
222
166
|
|
|
223
|
-
##
|
|
167
|
+
## The Backstory
|
|
224
168
|
|
|
225
|
-
|
|
226
|
-
|----------|--------|-------|
|
|
227
|
-
| **Termux/Android** | ✅ **Verified** | Native, no containers. Chromium via `pkg`. |
|
|
228
|
-
| **Linux** | ✅ | Works with any Chrome/Chromium |
|
|
229
|
-
| **macOS** | ✅ | Google Chrome auto-detected |
|
|
230
|
-
| **Windows** | ✅ | Chrome auto-detected |
|
|
231
|
-
| **CI/CD (GitHub Actions)** | ✅ | Use `chromium-browser` |
|
|
232
|
-
| **Docker** | ✅ | Install chromium in container |
|
|
169
|
+
I built this because I was tired of every browser automation tool assuming you have 400MB to spare and a desktop-class machine. I work from my phone sometimes. Termux exists. Why shouldn't browser automation work there too?
|
|
233
170
|
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
## 📦 What's in the Box?
|
|
171
|
+
So I did what any reasonable person would do: I ignored all the existing solutions and wrote my own, using nothing but raw CDP — the protocol Chrome speaks natively. No wrappers. No abstractions. Just JSON messages over WebSocket.
|
|
237
172
|
|
|
238
|
-
|
|
239
|
-
bwb-browser (37KB unpacked)
|
|
240
|
-
├── server.mjs MCP server — 15 tools, CDP integration
|
|
241
|
-
├── bin/bwb CLI entry point
|
|
242
|
-
├── AGENTS.md Agent integration guide + copy-paste prompt
|
|
243
|
-
├── BENCHMARKS.md Competitive comparison data
|
|
244
|
-
├── LICENSE MIT
|
|
245
|
-
└── README.md This file
|
|
246
|
-
```
|
|
173
|
+
The result is 76KB of source code that does what 400MB of dependencies do. It's not _better_ code — it's _less_ code. And sometimes less is all you need.
|
|
247
174
|
|
|
248
|
-
|
|
175
|
+
*— Krish Tiwari ([@krshforever](https://github.com/krshforever)), somewhere on an Indian train, writing code on a phone*
|
|
249
176
|
|
|
250
177
|
---
|
|
251
178
|
|
|
252
|
-
##
|
|
179
|
+
## Roadmap
|
|
253
180
|
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
| Install time | **5 seconds** | 5+ minutes | 5+ minutes | 5+ minutes |
|
|
259
|
-
| Dependencies | **3 packages** | 50+ packages | 30+ packages | 50+ packages |
|
|
260
|
-
| Live event capture | ✅ **`browser_watch`** | ❌ | ❌ | ❌ |
|
|
261
|
-
| Termux/Android | ✅ **Native** | ❌ | ❌ | ❌ |
|
|
262
|
-
| Uses existing Chrome | ✅ Auto-detect | ❌ Downloads its own | ❌ Downloads its own | ❌ Downloads its own |
|
|
263
|
-
| Dark mode | ✅ MIT | ✅ Apache 2.0 | ✅ Apache 2.0 | ✅ Apache 2.0 |
|
|
181
|
+
- **bwb Cloud** — hosted browser instances so your agent has a browser even when your laptop's asleep
|
|
182
|
+
- **`browser_act` v2** — multi-step with feedback loops (not just "search for X" but "research this topic and summarize")
|
|
183
|
+
- **Recording & Replay** — record sessions, replay them, debug them
|
|
184
|
+
- **Browser pool** — multiple isolated instances for CI parallelization
|
|
264
185
|
|
|
265
186
|
---
|
|
266
187
|
|
|
267
|
-
##
|
|
188
|
+
## Support
|
|
268
189
|
|
|
269
|
-
|
|
270
|
-
- **v2.1** — Stealth mode (bot detection bypass via CDP script injection)
|
|
271
|
-
- **v2.2** — Cookie/session management (`browser_getCookies`, `browser_setCookie`)
|
|
272
|
-
- **v3.0** — Parallel tab management, persistent sessions, network interception
|
|
273
|
-
- **bwb Cloud** — Managed browser instances, pay-per-use (coming 2027)
|
|
190
|
+
If bwb saves you time, money, or a few brain cells:
|
|
274
191
|
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
## 📄 License
|
|
192
|
+
- [GitHub Sponsors](https://github.com/sponsors/krshforever)
|
|
278
193
|
|
|
279
|
-
|
|
194
|
+
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.
|
|
280
195
|
|
|
281
196
|
---
|
|
282
197
|
|
|
283
|
-
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
<a href="https://www.npmjs.com/package/bwb-browser">npm</a> ·
|
|
287
|
-
<a href="AGENTS.md">Agent Guide</a>
|
|
288
|
-
</p>
|
|
198
|
+
## License
|
|
199
|
+
|
|
200
|
+
MIT — Krish Tiwari ([@krshforever](https://github.com/krshforever))
|