@generativereality/browser-automation 0.3.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/.claude-plugin/plugin.json +9 -0
- package/README.md +127 -0
- package/dist/index.js +916 -0
- package/package.json +56 -0
- package/scripts/launch-chrome.sh +79 -0
- package/scripts/sync-plugin.sh +68 -0
- package/skills/browser/SKILL.md +201 -0
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "browser-automation",
|
|
3
|
+
"description": "Daemonless, per-tab-isolated browser automation for Claude Code via the `browser-automation` CLI. Drives one shared headed Chrome (persistent profile + extensions) over per-target CDP — many parallel sessions, no focus stealing, nothing long-lived to crash.",
|
|
4
|
+
"version": "0.3.0",
|
|
5
|
+
"author": {
|
|
6
|
+
"name": "generativereality"
|
|
7
|
+
},
|
|
8
|
+
"homepage": "https://github.com/generativereality/browser-automation"
|
|
9
|
+
}
|
package/README.md
ADDED
|
@@ -0,0 +1,127 @@
|
|
|
1
|
+
# browser-automation
|
|
2
|
+
|
|
3
|
+
A daemonless, per-tab-isolated browser automation CLI for AI agents (built for
|
|
4
|
+
Claude Code, usable anywhere). It drives **one shared headed Chrome** with a
|
|
5
|
+
**persistent profile** — cookies and browser extensions (password managers, etc.)
|
|
6
|
+
survive across runs — over **per-target Chrome DevTools Protocol**.
|
|
7
|
+
|
|
8
|
+
No MCP server, no daemon, **nothing long-lived to crash**. Every command is a
|
|
9
|
+
fresh process that connects to a single tab, acts, and exits.
|
|
10
|
+
|
|
11
|
+
## Why
|
|
12
|
+
|
|
13
|
+
Driving a shared Chrome the usual way (Playwright's `connectOverCDP`, or an MCP
|
|
14
|
+
server holding a browser object) has three recurring failures:
|
|
15
|
+
|
|
16
|
+
1. **It wedges.** `connectOverCDP` enumerates *every* target on connect; one
|
|
17
|
+
stuck iframe/worker or a pile of open tabs hangs the whole handshake.
|
|
18
|
+
2. **It can't run in parallel.** All sessions share one "active tab"; concurrent
|
|
19
|
+
agents fight over it and steal each other's (and the user's) focus.
|
|
20
|
+
3. **The process dies.** When an MCP server's connection drops or Chrome
|
|
21
|
+
restarts, the client needs a reconnect/restart.
|
|
22
|
+
|
|
23
|
+
This CLI fixes all three by talking **per-target CDP** and keeping **no
|
|
24
|
+
long-lived process**:
|
|
25
|
+
|
|
26
|
+
- Each command connects to one tab's `webSocketDebuggerUrl` — no whole-browser
|
|
27
|
+
enumeration, so target count never wedges it.
|
|
28
|
+
- Each session owns one tab by name (`-s <name>`); commands only touch that tab.
|
|
29
|
+
New tabs open in the background and the CLI never activates/foregrounds a tab,
|
|
30
|
+
so parallel sessions and the user never collide.
|
|
31
|
+
- Nothing persists but the user's Chrome and a tiny per-session file. Chrome
|
|
32
|
+
restarts? The next `goto` recreates the tab (sessions self-heal).
|
|
33
|
+
|
|
34
|
+
## Install
|
|
35
|
+
|
|
36
|
+
```bash
|
|
37
|
+
npm install -g @generativereality/browser-automation
|
|
38
|
+
browser-automation launch # start the canonical Chrome on :9223 (idempotent)
|
|
39
|
+
browser-automation doctor # verify
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
Claude Code skill (so the agent knows how to use it):
|
|
43
|
+
|
|
44
|
+
```bash
|
|
45
|
+
mkdir -p .claude/skills/browser
|
|
46
|
+
curl -fsSL https://raw.githubusercontent.com/generativereality/browser-automation/main/skills/browser/SKILL.md \
|
|
47
|
+
-o .claude/skills/browser/SKILL.md
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
…or install the plugin from the marketplace:
|
|
51
|
+
|
|
52
|
+
```bash
|
|
53
|
+
/plugin marketplace add generativereality/plugins
|
|
54
|
+
/plugin install browser-automation@generativereality
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
## Usage
|
|
58
|
+
|
|
59
|
+
Page commands pick a tab with a selector (precedence `-t` > `-m` > `-s`):
|
|
60
|
+
|
|
61
|
+
- `-m <substr>` — any open tab whose **URL or title** contains the substring
|
|
62
|
+
(errors if ambiguous; `--first` to take the first). Drives tabs the user or
|
|
63
|
+
another flow already opened — no setup.
|
|
64
|
+
- `-t <targetId>` — an exact tab (from `list`).
|
|
65
|
+
- `-s <name>` — a saved **session** bookmark (default `$BAC_SESSION`, else `default`).
|
|
66
|
+
|
|
67
|
+
Sessions are optional bookmarks, not locks — there's no one-session-one-tab rule.
|
|
68
|
+
|
|
69
|
+
```bash
|
|
70
|
+
# Session workflow (creates + remembers a tab)
|
|
71
|
+
browser-automation goto -s work https://app.example.com/login
|
|
72
|
+
browser-automation snapshot -s work # -> e1, e2, e3 … refs
|
|
73
|
+
browser-automation fill -s work e1 "user@example.com"
|
|
74
|
+
browser-automation fill -s work e2 "secret" --submit
|
|
75
|
+
browser-automation snapshot -s work # re-snapshot after the DOM changes
|
|
76
|
+
browser-automation read -s work '.account-balance'
|
|
77
|
+
|
|
78
|
+
# Drive a tab that's already open — by URL/title substring, no session needed
|
|
79
|
+
browser-automation list # see every tab: id, title, url
|
|
80
|
+
browser-automation read -m nordnet '.balance'
|
|
81
|
+
browser-automation bind -s bank -m nordnet # …or adopt it into a session
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
| Command | What it does |
|
|
85
|
+
|---|---|
|
|
86
|
+
| `launch [--status]` | Start the canonical headed Chrome on :9223 (idempotent) |
|
|
87
|
+
| `doctor` | Diagnose Node, Chrome, targets, sessions |
|
|
88
|
+
| `list` | List sessions and every open tab (id, title, url) |
|
|
89
|
+
| `new -s <s> [url]` | Open a background tab for a session |
|
|
90
|
+
| `goto (-s\|-m\|-t) <url>` | Navigate (session tab created if needed) |
|
|
91
|
+
| `bind -s <name> (-m\|-t)` | Adopt an already-open tab into a session |
|
|
92
|
+
| `snapshot (-s\|-m\|-t)` | List interactive elements with refs (`e1`, `e2`, …) |
|
|
93
|
+
| `click (-s\|-m\|-t) <ref>` | Click an element by ref |
|
|
94
|
+
| `fill (-s\|-m\|-t) <ref> <value> [--submit]` | Type into a field by ref |
|
|
95
|
+
| `read (-s\|-m\|-t) [selector]` | Print page text (or a CSS selector's text) |
|
|
96
|
+
| `eval (-s\|-m\|-t) <js>` | Evaluate a JS expression in the tab (escape hatch) |
|
|
97
|
+
| `download (-s\|-m\|-t) (--click <ref>\|--url <href>)` | Capture a file/CSV download, wait for completion, print the path |
|
|
98
|
+
| `close (-s\|-m\|-t) [--tab]` | Forget the session (tab stays open); `--tab` also closes the browser tab |
|
|
99
|
+
|
|
100
|
+
## How refs work
|
|
101
|
+
|
|
102
|
+
`snapshot` stamps `data-ba-ref="eN"` onto each interactive element and prints the
|
|
103
|
+
list. Because each invocation is a separate process with no shared memory, the
|
|
104
|
+
ref table can't live in the CLI — it lives in the page. `click e7` just does
|
|
105
|
+
`querySelector('[data-ba-ref="e7"]')`. **Re-snapshot after any DOM change**, the
|
|
106
|
+
same one-action-per-snapshot rule as Playwright refs.
|
|
107
|
+
|
|
108
|
+
## Notes & limits
|
|
109
|
+
|
|
110
|
+
- Interactions are **JS-dispatched** (`element.click()`, native value setter +
|
|
111
|
+
`input`/`change`), which works on background tabs (native CDP mouse events do
|
|
112
|
+
not reliably reach a non-foreground tab in headed Chrome). Synthetic events are
|
|
113
|
+
not `isTrusted`, so a few hard anti-bot/payment flows may reject them.
|
|
114
|
+
- `read`/`snapshot` see the page + same-origin frames, not cross-origin iframes
|
|
115
|
+
(each is its own CDP target).
|
|
116
|
+
- `launch` resolves Chrome on macOS/Linux; elsewhere start Chrome manually with
|
|
117
|
+
`--remote-debugging-port=9223 --user-data-dir="<profile>"`.
|
|
118
|
+
|
|
119
|
+
## Environment
|
|
120
|
+
|
|
121
|
+
- `BROWSER_AUTOMATION_CDP` — CDP host (default `http://localhost:9223`).
|
|
122
|
+
- `BROWSER_AUTOMATION_PROFILE` — Chrome profile dir for `launch`.
|
|
123
|
+
- `BAC_SESSION` — default session name for page commands.
|
|
124
|
+
|
|
125
|
+
## License
|
|
126
|
+
|
|
127
|
+
MIT
|