@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.
@@ -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