1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
|
# pi-browser-harness
Full browser control for pi agents. Navigate, click, type, screenshot, and extract data from your real Chrome — driven by your coding agent.
---
## Quick Start
```bash
# 1. Install
pi install npm:pi-browser-harness
# Or install from GitHub:
# pi install git:github.com/amankumarsingh77/pi-browser-harness
# 2. Enable Chrome remote debugging
# Open chrome://inspect/#remote-debugging in Chrome,
# tick the "Discover network targets" checkbox, click Allow.
# No Chrome relaunch needed.
# 3. Connect pi to Chrome
/browser-setup
```
That's it. Try:
```
> navigate to https://github.com and take a screenshot
```
### Requirements
- pi (latest)
- Node.js ≥ 22
- Chrome / Chromium / Edge (any recent version)
> If `chrome://inspect/#remote-debugging` isn't available, you can launch Chrome with `--remote-debugging-port=9222` instead. The harness will find it either way.
---
## What you can do
### Navigation & tabs
| Tool | What it does |
|------|--------------|
| `browser_navigate` | Go to a URL (reuses the attached tab) |
| `browser_new_tab` | Open a new tab, optionally navigate |
| `browser_open_urls` | Open many URLs in parallel tabs |
| `browser_go_back` / `browser_go_forward` | History navigation |
| `browser_reload` | Reload the current page |
| `browser_list_tabs` / `browser_current_tab` | Discover tabs |
| `browser_switch_tab` | Switch the active tab |
| `browser_page_info` | URL, title, viewport, scroll, dialog state |
### Interaction
| Tool | What it does |
|------|--------------|
| `browser_click` | Click at viewport coordinates (works through iframes / shadow DOM) |
| `browser_type` | Type into the focused element |
| `browser_press_key` | Send a key with optional modifiers |
| `browser_scroll` | Scroll by delta pixels |
| `browser_handle_dialog` | Accept or dismiss `alert` / `confirm` / `prompt` |
### Visual & data
| Tool | What it does |
|------|--------------|
| `browser_screenshot` | Capture the current page as PNG |
| `browser_execute_js` | Run JS in the page and return the result |
| `browser_http_get` | Direct HTTP GET — bypasses the browser, much faster for APIs |
| `browser_wait` / `browser_wait_for_load` | Sleep, or wait for `readyState === 'complete'` |
### Extending the harness at runtime
| Tool | What it does |
|------|--------------|
| `browser_run_script` | Execute a temporary script file with daemon access |
---
## Usage
The core pattern is **screenshot → act → screenshot → verify.** Don't assume an action worked — look.
### Navigate and screenshot
```
browser_navigate("https://github.com/browser-use/browser-harness")
browser_wait_for_load()
browser_screenshot()
```
### Fill a form
```
browser_screenshot() # see the form
browser_click(400, 200) # click the search input
browser_type("pi browser harness") # type
browser_press_key("Enter") # submit
browser_wait_for_load()
browser_screenshot() # verify
```
### Extract data
```js
// Fast: hit the API directly, no browser
browser_http_get("https://api.github.com/repos/browser-use/browser-harness")
// DOM scraping for rendered content
browser_execute_js("document.querySelector('.price').innerText")
// Structured arrays
browser_execute_js(`
JSON.stringify(
Array.from(document.querySelectorAll('.result')).map(el => ({
title: el.querySelector('h3')?.textContent,
link: el.querySelector('a')?.href,
}))
)
`)
```
### Open multiple results in parallel
```
browser_navigate("https://google.com/search?q=chrome+devtools+protocol")
browser_open_urls({ urls: [
"https://chromedevtools.github.io/devtools-protocol/",
"https://developer.chrome.com/docs/devtools",
]})
browser_list_tabs()
browser_switch_tab({ targetId: "..." })
```
### SPAs
`browser_wait_for_load` only checks `readyState`. For React/Vue/etc., poll for the actual element you want:
```js
browser_execute_js("!!document.querySelector('.loaded-content')")
```
### Keyboard modifiers
`browser_press_key` takes a modifier bitfield: `Alt=1`, `Ctrl=2`, `Meta/Cmd=4`, `Shift=8`. Combine with `|`.
```
browser_press_key("c", { modifiers: 2 }) // Ctrl+C
browser_press_key("v", { modifiers: 4 }) // Cmd+V
browser_press_key("T", { modifiers: 10 }) // Ctrl+Shift+T
```
### Writing a temporary script
When the built-ins aren't enough, write a script to disk and run it with `browser_run_script`.
```js
// 1. Write the script to disk
write("/tmp/scrape-results.js", `
const data = await daemon.evaluateJS(\`
JSON.stringify(
Array.from(document.querySelectorAll('${params.selector}'))
.map(el => el.textContent.trim())
)
\`);
return {
content: [{ type: "text", text: data }],
details: { items: JSON.parse(data) },
};
`)
// 2. Execute it
browser_run_script("/tmp/scrape-results.js", { selector: ".result" })
```
Scripts receive `params`, `daemon`, `require`, `signal`, `onUpdate`, `ctx`, plus the standard JS globals. The script is on disk — auditable and re-runnable.
---
## Commands
| Command | Description |
|---------|-------------|
| `/browser-setup` | Connect pi to Chrome (run once) |
| `/browser-status` | Show daemon health and current page |
| `/browser-reload-daemon` | Restart the connection |
---
## Troubleshooting
| Symptom | Fix |
|---------|-----|
| `DevToolsActivePort not found` | Open `chrome://inspect/#remote-debugging`, tick the checkbox, click Allow, then retry. |
| Connection fails after Chrome restart | Run `/browser-reload-daemon`. |
| Page seems loaded but content is missing | SPA — `browser_wait_for_load` isn't enough. Poll with `browser_execute_js` for the element you need. |
| A JS dialog is blocking actions | `browser_page_info` will report the dialog. Use `browser_handle_dialog` to accept or dismiss. |
---
## Security
This extension drives your real Chrome. The agent can see open tabs, read page content, submit forms, and act inside authenticated sessions. `browser_run_script` evaluates JavaScript in the pi process with full `require` access — review any temporary scripts the agent writes to `/tmp/` before executing them.
---
## License
MIT — see [LICENSE](LICENSE).
|