chromex-mcp 1.5.0 → 1.6.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.
Files changed (10) hide show
  1. package/README.md +370 -485
  2. package/package.json +2 -2
  3. package/plugins/chromex/skills/chromex/scripts/chromex.mjs +29 -13
  4. package/plugins/chromex/skills/chromex/scripts/lib/browser.mjs +9 -7
  5. package/plugins/chromex/skills/chromex/scripts/lib/commands/app.mjs +558 -0
  6. package/plugins/chromex/skills/chromex/scripts/lib/commands/doctor.mjs +55 -0
  7. package/plugins/chromex/skills/chromex/scripts/lib/commands/storage.mjs +8 -1
  8. package/plugins/chromex/skills/chromex/scripts/lib/daemon.mjs +20 -7
  9. package/plugins/chromex/skills/chromex/scripts/lib/launcher.mjs +14 -7
  10. package/plugins/chromex/skills/chromex/scripts/mcp-server.mjs +137 -3
package/README.md CHANGED
@@ -1,657 +1,542 @@
1
1
  # Chromex
2
2
 
3
- Zero-dependency Chrome DevTools Protocol toolkit for AI agents. 56 typed MCP tools + CLI. Connects directly to Chrome, Brave, Edge, or Chromium via WebSocket. No Puppeteer, no bloat.
4
-
5
- Designed from the ground up for token efficiency: incremental diffs, query-filtered snapshots, ref-based selection, and a plain-text output format that consistently beats JSON and YAML-style structured alternatives by 25% to 126% in head-to-head token measurements (see [Token Efficiency](#token-efficiency) below).
6
-
7
- ## Features
8
-
9
- - **56 MCP tools** -- typed JSON Schema, annotations (`readOnlyHint`, `destructiveHint`), inline screenshots (base64)
10
- - **Zero dependencies** -- uses only Node.js 22+ built-in modules (WebSocket, fs, net, crypto)
11
- - **Ref-based selection** -- `snap --refs` assigns `@e1`, `@e2`... to interactive elements, then `click @e5` or `fill @e3 "value"`. No fragile CSS selectors
12
- - **Incremental snapshots** -- second snapshot returns only changed nodes (diff), reducing output from thousands of lines to just what changed
13
- - **Query-filtered snapshots** -- `snap --query=login` returns only matching nodes and their ancestors, cutting output by 95% to 99% on large pages like GitHub, Jira, or Gmail
14
- - **Auto-snapshot** -- interactive commands (click, fill, nav, etc.) automatically append an incremental snapshot with refs, so the agent sees the page state in a single round-trip
15
- - **Contextual hints** -- after each action, chromex appends up to 3 `help[]` next-step suggestions picked from the current ref map, eliminating the "what do I do next" turn. Opt-out with `--no-hints`
16
- - **Pre-computed aggregates** -- `net` and `console` outputs embed counters (`network[47] errors:3 pending:0 ok:44`, `console[12] errors:2 warnings:4 info:6`) so the agent never needs a follow-up count
17
- - **Scroll detection** -- snapshots report scrollable containers with remaining distance (`[scroll: page: down:1200px | sidebar: up:300px]`)
18
- - **Per-tab persistent daemons** -- each tab gets a background process connected via Unix socket. Chrome's "Allow debugging" modal fires once, not on every command
19
- - **Security hardened** -- domain filtering (allow/blocklist), CDP method blocklist, token-authenticated sockets, full audit log
20
- - **Multi-browser** -- auto-detects Brave, Chrome, Chrome Canary, Chromium, Edge, Vivaldi (macOS + Linux)
21
- - **Network control** -- throttle to 3G/offline, intercept & mock requests, record HAR files
22
- - **Form filling** -- fill inputs, select dropdowns, toggle checkboxes, upload files, batch fill entire forms. Works with React/Vue/Angular
23
- - **Browser launcher** -- launch browser with remote debugging pre-enabled (skips the "Allow debugging" modal entirely)
24
- - **CLI included** -- same commands available from the terminal for scripts and CI/CD
3
+ [![npm version](https://img.shields.io/npm/v/chromex-mcp.svg)](https://www.npmjs.com/package/chromex-mcp)
4
+ [![Node.js 22+](https://img.shields.io/badge/node-%3E%3D22.0.0-brightgreen.svg)](https://nodejs.org/)
5
+ [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
25
6
 
26
- ## Requirements
7
+ Chromex is a zero-dependency Chrome DevTools Protocol toolkit for AI agents. It connects directly to Chrome, Brave, Edge, Chromium, and Vivaldi through CDP, exposing a token-efficient CLI and an optional MCP server with 73 typed tools.
27
8
 
28
- - Node.js 22+ (for built-in WebSocket)
29
- - Any Chromium-based browser
9
+ Use Chromex when an agent needs to inspect pages, take screenshots, navigate, click, fill forms, read console/network activity, emulate devices, throttle network/CPU, export PDFs, or run browser diagnostics without pulling in Puppeteer or Playwright.
30
10
 
31
- ## Installation
11
+ ## Why Chromex
32
12
 
33
- ```bash
34
- # Add to Claude Code (global -- all projects)
35
- claude mcp add chromex -s user npx chromex-mcp@latest
13
+ - **CLI-first for lower token usage**: terminal commands return compact plain text and avoid MCP tool-schema overhead.
14
+ - **Optional MCP server**: 73 typed tools for Claude Code and other MCP clients when tool discovery, typed parameters, and inline screenshots matter more than token budget.
15
+ - **No runtime dependencies**: Node.js 22+ built-ins only, including native WebSocket support.
16
+ - **Agent-friendly page model**: accessibility snapshots, `@eN` refs, incremental diffs, query filters, auto-snapshots, and contextual hints.
17
+ - **Persistent per-tab daemons**: one CDP session per tab, held open through an authenticated Unix socket.
18
+ - **Security controls**: domain allow/block lists, CDP method blocklist, socket auth, command timeouts, and audit logs.
19
+ - **Local by default**: no hosted service, no telemetry client, no bundled browser download, and session stats stay on your machine.
36
20
 
37
- # Or project-only
38
- claude mcp add chromex npx chromex-mcp@latest
39
- ```
21
+ ## What You Can Do Today
40
22
 
41
- ### Auto-Approve (recommended)
23
+ - Inspect and automate real logged-in browser sessions, not only fresh headless test contexts.
24
+ - Read page state through compact accessibility snapshots, filtered snapshots, DOM snapshots, HTML, screenshots, and highlighted elements.
25
+ - Act on UI through refs, CSS selectors, coordinates, keyboard input, forms, uploads, drag and drop, touch gestures, dialogs, and load-more loops.
26
+ - Debug production behavior with console history, network request details, response bodies, HAR export, request blocking, API mocking, throttling, and offline mode.
27
+ - Test browser conditions with device presets, viewport resizing, DPR, geolocation, timezone, locale, CPU throttling, incognito contexts, proxies, and custom Chrome flags.
28
+ - Diagnose performance and quality with Core Web Vitals, transfer size, DOM/memory counters, Lighthouse audits, JS/CSS coverage, Chrome traces, and heap snapshots.
29
+ - Validate modern browser flows such as passkey/WebAuthn registration and login, downloads, cookies, storage, PDF export, and isolated profiles.
30
+ - Inspect Application panel state from the terminal: origin quota, storage usage breakdown, Cache Storage entries/bodies, IndexedDB schemas/rows, and Service Worker registrations.
42
31
 
43
- Add to `~/.claude/settings.json`:
32
+ ## Positioning
44
33
 
45
- ```json
46
- {
47
- "permissions": {
48
- "allow": ["mcp__chromex"]
49
- }
50
- }
51
- ```
34
+ Chromex is a direct CDP layer for coding agents. It sits between raw Chrome DevTools Protocol and heavier browser automation frameworks.
52
35
 
53
- This approves all 56 MCP tools at once. For granular control, approve individual tools:
36
+ | Alternative | Trade-off | Chromex angle |
37
+ |-------------|-----------|---------------|
38
+ | Raw CDP WebSocket | Maximum browser power, but too verbose for agents. | Compact commands, refs, snapshots, and safety defaults. |
39
+ | Puppeteer or Playwright libraries | Excellent automation frameworks, but they add dependencies and framework-level abstractions. | Zero-runtime-dependency CLI/MCP that talks to your existing Chromium browser. |
40
+ | Browser MCP only | Easy tool discovery, but tool schemas and structured responses add token cost. | CLI-first for cheap agent loops, MCP when typed tools are worth the overhead. |
41
+ | Manual DevTools | Great for humans, not scriptable enough for agents. | DevTools-grade inspection exposed as terminal and MCP commands. |
54
42
 
55
- ```json
56
- {
57
- "permissions": {
58
- "allow": [
59
- "mcp__chromex__chromex_list",
60
- "mcp__chromex__chromex_snapshot",
61
- "mcp__chromex__chromex_screenshot",
62
- "mcp__chromex__chromex_perf"
63
- ]
64
- }
65
- }
66
- ```
43
+ ## Requirements
67
44
 
68
- ### Global install (optional)
45
+ - Node.js 22 or newer.
46
+ - macOS or Linux.
47
+ - A Chromium-based browser: Chrome, Brave, Edge, Chromium, Chrome Canary, or Vivaldi.
69
48
 
70
- ```bash
71
- npm install -g chromex-mcp
72
- ```
49
+ ## Zero-Dependency Boundary
73
50
 
74
- This installs three binaries:
51
+ The core runtime uses only Node.js built-in modules. Chromex does not install Puppeteer, Playwright, Selenium, browser drivers, telemetry SDKs, update checkers, or bundled browsers.
75
52
 
76
- | Binary | Purpose |
77
- |--------|---------|
78
- | `chromex` | CLI -- the main command for terminal usage |
79
- | `chromex-cli` | Alias for `chromex` |
80
- | `chromex-mcp` | MCP server (stdio JSON-RPC) -- used by `claude mcp add`, not run directly |
53
+ The only exception is the optional `audit` command: it shells out to Lighthouse with `npx --yes lighthouse` when you explicitly run an audit. All other CLI and MCP commands run through Chromex's own CDP client.
81
54
 
82
- ```bash
83
- chromex list # List open tabs
84
- chromex launch --url https://example.com # Launch browser
85
- chromex snap 6BE8 --refs # Snapshot with refs
86
- chromex click 6BE8 @e3 # Click by ref
87
- ```
55
+ Development dependencies are used only for tests and token benchmarks.
56
+
57
+ ## Browser Setup
58
+
59
+ Chromex needs Chrome DevTools Protocol access to your browser. Choose one of the two connection modes below before using the CLI or MCP server.
88
60
 
89
- ## Connect to Your Browser
61
+ ### Option A: Launch a Browser with Chromex
90
62
 
91
- **Option A: Launch a new browser** (recommended -- no setup needed)
63
+ This is the recommended first-time setup. Chromex starts a new browser process with remote debugging already enabled, so there is no manual browser configuration and no "Allow debugging" prompt.
92
64
 
93
65
  ```bash
94
66
  chromex launch --url https://example.com
95
67
  ```
96
68
 
97
- This starts Chrome/Brave/Edge with remote debugging pre-enabled. No manual configuration required.
69
+ Useful launch variants:
98
70
 
99
- **Option B: Connect to an already-running browser**
71
+ ```bash
72
+ chromex launch --browser brave --url https://example.com
73
+ chromex launch --profile testing --url https://example.com
74
+ chromex launch --incognito --browser chrome
75
+ chromex launch --headless --url https://example.com
76
+ chromex launch --browser-path "/Applications/Google Chrome Canary.app/Contents/MacOS/Google Chrome Canary"
77
+ ```
100
78
 
101
- 1. Open your browser (Chrome, Brave, Edge, etc.)
102
- 2. Navigate to `chrome://inspect/#remote-debugging`
103
- 3. **Toggle the switch ON** to enable remote debugging
104
- 4. Run `chromex list` to verify the connection
79
+ Named profiles are stored under `~/.chromex/profiles/` and keep test sessions isolated from your daily browser profile.
105
80
 
106
- > **Important:** Without step 3, chromex cannot connect to your browser. This is a one-time setup -- the setting persists across browser restarts.
81
+ Chrome for Testing also works well with Chromex. Download it manually from Google's official Chrome for Testing channel, then point Chromex at the executable with `--browser-path` or `CHROMEX_BROWSER_PATH`. Chromex does not download or bundle a browser.
107
82
 
108
- > **Note:** With Option B, Chrome will show an "Allow debugging" dialog the first time you access each tab. Click "Allow" once per tab -- the daemon keeps the session alive after that.
83
+ ### Option B: Connect to an Already-Running Browser
109
84
 
110
- ## Quick Start
85
+ Use this when you want Chromex to inspect tabs that are already open in your normal browser.
86
+
87
+ 1. Open Chrome, Brave, Edge, Chromium, or Vivaldi.
88
+ 2. Go to `chrome://inspect/#remote-debugging`.
89
+ 3. Enable the remote debugging switch.
90
+ 4. Run `chromex list` to verify that tabs are visible.
111
91
 
112
92
  ```bash
113
- # List open tabs
114
93
  chromex list
115
- # Output: 6BE827FA Example Domain https://example.com
116
-
117
- # Take a screenshot
118
- chromex shot 6BE8 /tmp/page.png
119
-
120
- # Get the accessibility tree with interactive refs
121
- chromex snap 6BE8 --refs
122
- # Output:
123
- # @e1 [textbox] Email
124
- # @e2 [textbox] Password
125
- # @e3 [button] Sign in
126
-
127
- # Fill a form using refs (no CSS selectors needed!)
128
- chromex fill 6BE8 @e1 "user@example.com"
129
- chromex fill 6BE8 @e2 "secret123"
130
- chromex click 6BE8 @e3
131
-
132
- # Check Core Web Vitals
133
- chromex perf 6BE8
134
94
  ```
135
95
 
136
- ## Commands
96
+ Important notes:
137
97
 
138
- `<target>` is a unique prefix of the targetId shown by `list` (e.g. `6BE827FA`).
98
+ - Without remote debugging enabled, Chromex cannot discover or control your open tabs.
99
+ - The browser setting is usually persistent across restarts.
100
+ - The first command that attaches to a tab may show an "Allow debugging" prompt. Accept it once for that tab; Chromex keeps the daemon session alive after that.
139
101
 
140
- ### Pages & Browser
102
+ If your browser uses a custom profile or a non-standard `DevToolsActivePort` location, set:
141
103
 
142
104
  ```bash
143
- chromex list # List open pages
144
- chromex open "https://example.com" # Open new tab
145
- chromex close <target> # Close tab
146
- chromex focus <target> # Activate/focus tab
147
- chromex launch # Launch browser with debugging
148
- chromex launch --incognito --browser brave # Launch Brave in incognito
149
- chromex launch --headless --url https://example.com # Headless mode for CI/CD
150
- chromex launch --proxy socks5://localhost:1080 # Launch with proxy
151
- chromex launch --insecure # Ignore certificate errors
152
- chromex launch --chrome-arg --disable-web-security # Pass custom Chrome flag
153
- chromex launch --profile testing --url https://... # Isolated profile + URL
154
- chromex incognito https://example.com # Isolated context (no relaunch)
155
- chromex stop # Stop all daemons
105
+ export CDP_PORT_FILE=/path/to/DevToolsActivePort
156
106
  ```
157
107
 
158
- ### Inspect
108
+ If your Chromium executable is installed in a non-standard location, either pass `--browser-path` to `chromex launch` or set:
159
109
 
160
110
  ```bash
161
- chromex snap <target> # Accessibility tree snapshot (compact)
162
- chromex snap <target> --refs # With interactive refs (@e1, @e2...)
163
- chromex snap <target> --depth=3 # Limit tree depth
164
- chromex snap <target> --full # Force full snapshot (skip diff)
165
- chromex snap <target> --query=login # Filter to matching nodes + ancestors (hierarchy preserved)
166
- chromex html <target> "#main" # Element HTML by selector
167
- chromex shot <target> /tmp/page.png # Viewport screenshot
168
- chromex shot <target> /tmp/full.png --full # Full page screenshot
169
- chromex shot <target> --format=jpeg --quality=80 # JPEG/WebP with quality control
170
- chromex shot <target> @e5 # Screenshot of specific element by ref
171
- chromex net <target> # List network requests (CDP tracked)
172
- chromex net <target> <requestId> # Request detail: headers, timing, body
173
- chromex perf <target> # Core Web Vitals + memory + DOM stats
174
- chromex console <target> 5000 # Capture console.log/error for 5s
175
- chromex console <target> list # Show stored messages since daemon start
176
- chromex console <target> detail <id> # Message detail with stack trace
177
- chromex domsnapshot <target> # Structured DOM with bounding rects
178
- chromex domsnapshot <target> --styles # Include computed styles
179
- chromex highlight <target> "h1" # Highlight element with overlay
180
- chromex highlight <target> clear # Remove highlight
111
+ export CHROMEX_BROWSER_PATH=/path/to/chrome
181
112
  ```
182
113
 
183
- ### Evaluate
114
+ Run the local diagnostic command whenever browser discovery or CDP connection fails:
184
115
 
185
116
  ```bash
186
- chromex eval <target> "document.title" # Run JS
187
- chromex eval <target> "document.querySelectorAll('a').length" # Count links
188
- chromex evalraw <target> "DOM.getDocument" # Raw CDP command
189
- chromex evalraw <target> "Page.getLayoutMetrics" # Layout info
117
+ chromex doctor
190
118
  ```
191
119
 
192
- ### Navigate & Wait
120
+ ## Install the CLI
193
121
 
194
- ```bash
195
- chromex nav <target> "https://example.com" # Navigate + wait for load
196
- chromex nav <target> back # Go back in history
197
- chromex nav <target> forward # Go forward in history
198
- chromex nav <target> reload # Reload page
199
- chromex nav <target> reload-hard # Reload ignoring cache
200
- chromex waitfor <target> ".results" 10000 # Wait for CSS selector (10s)
201
- chromex wait <target> networkidle # Wait for network idle
202
- chromex wait <target> load # Wait for page load
203
- chromex wait <target> domready # Wait for DOMContentLoaded
204
- chromex wait <target> fcp # Wait for First Contentful Paint
205
- chromex scroll <target> down 500 # Scroll down 500px
206
- chromex scroll <target> up 300 # Scroll up 300px
207
- chromex scroll <target> top # Scroll to top
208
- chromex scroll <target> bottom # Scroll to bottom
209
- chromex scroll <target> to "#footer" # Scroll to element
210
- ```
211
-
212
- ### Interact
122
+ Install the package globally to get the `chromex` command.
213
123
 
214
124
  ```bash
215
- chromex click <target> "button.submit" # Click by CSS selector
216
- chromex click <target> @e5 # Click by ref (from snap --refs)
217
- chromex click <target> @e5 --dbl # Double-click
218
- chromex clickxy <target> 100 200 # Click at CSS pixel coords
219
- chromex clickxy <target> 100 200 --dbl # Double-click at coords
220
- chromex key <target> Enter # Press key
221
- chromex key <target> "Control+A" # Key combination
222
- chromex key <target> "Control+Shift+R" # Multi-modifier combo
223
- chromex type <target> "hello world" # Type text (works cross-origin)
224
- chromex hover <target> @e12 # Hover element by ref
225
- chromex drag <target> "#source" "#dest" # Drag & drop by selector
226
- chromex drag <target> 100,200 400,500 # Drag & drop by coordinates
227
- chromex touch <target> tap 200 300 # Touch tap
228
- chromex touch <target> swipe 200,400 200,100 # Swipe gesture
229
- chromex touch <target> pinch 200 300 2.0 # Pinch zoom in
230
- chromex touch <target> longpress 200 300 1000 # Long press (1s)
231
- chromex dialog <target> accept # Accept alert/confirm
232
- chromex dialog <target> dismiss # Dismiss dialog
233
- chromex dialog <target> auto # Auto-accept all dialogs
234
- chromex loadall <target> ".load-more" 500 # Click until element disappears
235
- ```
236
-
237
- ### Forms
125
+ # npm
126
+ npm install -g chromex-mcp
238
127
 
239
- ```bash
240
- chromex fill <target> "#email" "user@test.com" # Fill input/textarea
241
- chromex fill <target> @e1 "user@test.com" # Fill by ref
242
- chromex clear <target> "#search" # Clear field
243
- chromex select <target> "#country" "BR" # Select dropdown option
244
- chromex check <target> "#terms" # Check checkbox
245
- chromex check <target> "#newsletter" false # Uncheck checkbox
246
- chromex upload <target> "#avatar" /tmp/photo.png # Upload file
247
-
248
- # Batch fill entire form
249
- chromex form <target> '{"#name":"John","#email":"john@test.com","#terms":true}'
128
+ # Bun
129
+ bun add -g chromex-mcp
250
130
  ```
251
131
 
252
- ### Data
132
+ The package installs three binaries:
253
133
 
254
- ```bash
255
- chromex cookies <target> # List cookies
256
- chromex cookies <target> set '{"name":"x","value":"y"}' # Set cookie
257
- chromex cookies <target> clear # Clear all cookies
258
- chromex storage <target> local # Dump localStorage
259
- chromex storage <target> session # Dump sessionStorage
260
- chromex storage <target> clear # Clear both
261
- chromex pdf <target> /tmp/page.pdf # Export as PDF
262
- ```
134
+ | Binary | Purpose |
135
+ |--------|---------|
136
+ | `chromex` | Main CLI for terminal, scripts, CI, and token-sensitive agent sessions. |
137
+ | `chromex-cli` | Alias for `chromex`. |
138
+ | `chromex-mcp` | MCP server over stdio JSON-RPC. Usually launched by an MCP client. |
263
139
 
264
- ### Network
140
+ ## CLI Quick Start
141
+
142
+ The CLI is the recommended interface when token budget matters. It has no MCP schema overhead, works well in scripts, and returns compact plain-text output designed for LLM agents.
265
143
 
266
144
  ```bash
267
- chromex throttle <target> 3g # Throttle to 3G
268
- chromex throttle <target> slow-3g # Throttle to slow 3G
269
- chromex throttle <target> 4g # Throttle to 4G
270
- chromex throttle <target> offline # Go offline
271
- chromex throttle <target> custom 200 1000 500 # Custom: latency, down, up (kbps)
272
- chromex throttle <target> reset # Remove throttling
273
-
274
- chromex intercept <target> block "*.analytics.*" # Block matching requests
275
- chromex intercept <target> mock "/api/user" '{"name":"test"}' # Mock response
276
- chromex intercept <target> rules # List active rules
277
- chromex intercept <target> off # Disable interception
278
-
279
- chromex har <target> start # Start recording
280
- chromex har <target> stop /tmp/trace.har # Save HAR file
281
- ```
145
+ # 1. Launch or connect to a browser.
146
+ chromex launch --url https://github.com/login
282
147
 
283
- ### Emulate
148
+ # 2. List tabs and copy a target prefix.
149
+ chromex list
150
+ # 6BE827FA Sign in to GitHub https://github.com/login
284
151
 
285
- ```bash
286
- chromex emulate <target> iphone-14 # 390x844 @3x mobile
287
- chromex emulate <target> iphone-15-pro # 393x852 @3x mobile
288
- chromex emulate <target> ipad-pro # 1024x1366 @2x tablet
289
- chromex emulate <target> pixel-7 # 412x915 @2.625x mobile
290
- chromex emulate <target> galaxy-s23 # 360x780 @3x mobile
291
- chromex emulate <target> macbook-air # 1440x900 @2x laptop
292
- chromex emulate <target> desktop-1080p # 1920x1080 @1x
293
- chromex emulate <target> desktop-4k # 3840x2160 @1x
294
- chromex emulate <target> reset # Reset to default
295
- chromex resize <target> 1280 720 # Custom viewport dimensions
296
- chromex resize <target> 1440 900 2 # Custom with DPR (retina)
297
- chromex geo <target> -23.55 -46.63 # Set geolocation (Sao Paulo)
298
- chromex geo <target> reset # Clear geolocation
299
- chromex timezone <target> "America/Sao_Paulo" # Set timezone
300
- chromex locale <target> "pt-BR" # Set locale
301
- chromex cpu <target> 4 # CPU 4x slower
302
- chromex cpu <target> reset # Reset CPU speed
303
- ```
152
+ # 3. Read the page through the accessibility tree and assign refs.
153
+ chromex snap 6BE8 --refs
154
+ # @e1 [textbox] Username or email address
155
+ # @e2 [textbox] Password
156
+ # @e3 [button] Sign in
304
157
 
305
- ### Advanced
158
+ # 4. Interact by ref instead of fragile CSS selectors.
159
+ chromex fill 6BE8 @e1 "user@example.com"
160
+ chromex fill 6BE8 @e2 "secret"
161
+ chromex click 6BE8 @e3
306
162
 
307
- ```bash
308
- chromex inject <target> "window.DEBUG=true" # Inject JS on every page load
309
- chromex inject <target> --file /tmp/preload.js # Inject from file
310
- chromex inject <target> --list # List injected scripts
311
- chromex inject <target> --remove <id> # Remove injected script
312
- chromex download <target> allow /tmp/downloads # Auto-accept downloads
313
- chromex download <target> deny # Block downloads
314
- chromex coverage <target> start # Start code coverage
315
- chromex coverage <target> stop # Coverage report (JS + CSS %)
316
- chromex trace <target> start # Start performance trace
317
- chromex trace <target> stop /tmp/trace.json # Save trace (chrome://tracing)
318
- chromex heap <target> snapshot /tmp/heap.hs # Heap snapshot (memory analysis)
319
- chromex webauthn <target> enable # Virtual authenticator (passkeys)
320
- chromex webauthn <target> creds # List stored credentials
321
- chromex webauthn <target> disable # Remove authenticator
163
+ # 5. Inspect browser state.
164
+ chromex console 6BE8 list
165
+ chromex net 6BE8
166
+ chromex shot 6BE8 /tmp/page.png
167
+ chromex app 6BE8
322
168
  ```
323
169
 
324
- ### Audit & Analytics
170
+ `<target>` is a unique prefix of the tab target ID returned by `chromex list`. If a prefix is ambiguous, Chromex rejects it and asks for more characters.
325
171
 
326
- ```bash
327
- chromex audit <target> # Full Lighthouse audit (all categories)
328
- chromex audit <target> performance,seo # Specific categories
329
- chromex audit <target> accessibility desktop # Accessibility on desktop
330
- chromex stats <target> # Session analytics (command counts, timing)
331
- chromex stats <target> --full # Full action timeline
332
- chromex stats <target> --reset # Reset counters
333
- chromex stats <target> --export=/tmp/stats.json # Export as JSON
334
- ```
172
+ ## Token-Efficient Agent Workflow
335
173
 
336
- ## Ref-Based Selection
174
+ Chromex is optimized for agents that need to act on browser state without wasting context.
337
175
 
338
- The killer feature for AI agents. Instead of fragile CSS selectors, use numbered refs:
176
+ 1. Start with `chromex list`.
177
+ 2. Prefer `chromex snap <target> --refs` over raw HTML.
178
+ 3. Use `@eN` refs for `click`, `fill`, `hover`, and element screenshots.
179
+ 4. On large pages, use `--query` before reading a full snapshot.
180
+ 5. Let auto-snapshot show post-action state after interactive commands.
181
+ 6. Add `--no-snap` only for fast scripted batches where you do not need immediate page state.
182
+ 7. Add `--no-hints` when another program parses output strictly.
183
+
184
+ Examples:
339
185
 
340
186
  ```bash
341
- # 1. Get interactive elements with refs
342
- chromex snap <target> --refs
343
- # Output:
344
- # @e1 [textbox] Username
345
- # @e2 [textbox] Password
346
- # @e3 [checkbox] Remember me
347
- # @e4 [button] Sign in
348
- # @e5 [link] Forgot password?
349
-
350
- # 2. Interact using refs
351
- chromex fill <target> @e1 "admin"
352
- chromex fill <target> @e2 "secret123"
353
- chromex click <target> @e3
354
- chromex click <target> @e4
187
+ chromex snap 6BE8 --query=login --refs
188
+ chromex click 6BE8 @e4
189
+ chromex wait 6BE8 networkidle
190
+ chromex snap 6BE8 --query=error
355
191
  ```
356
192
 
357
- Refs are assigned to all interactive elements (buttons, links, inputs, checkboxes, radios, dropdowns, tabs, switches, sliders, search boxes). They persist until the next `snap --refs` call.
193
+ ## MCP Server
358
194
 
359
- Supported ref commands: `click @eN`, `fill @eN "value"`, `hover @eN`.
195
+ Use MCP when you want Claude Code or another MCP client to discover typed browser tools directly. MCP is convenient, but it costs more tokens than CLI usage because tool schemas, JSON-RPC framing, and structured tool results add overhead.
360
196
 
361
- ## Snapshot Optimizations
197
+ ### Add to Claude Code
362
198
 
363
- Chromex snapshots are designed to minimize token usage for AI agents.
199
+ Global, available in all projects:
364
200
 
365
- ### Incremental Diff
366
-
367
- The first snapshot returns the full accessibility tree. Subsequent snapshots return only nodes that changed:
201
+ ```bash
202
+ # npm
203
+ claude mcp add chromex -s user npx chromex-mcp@latest
368
204
 
205
+ # Bun
206
+ claude mcp add chromex -s user bunx chromex-mcp@latest
369
207
  ```
370
- [incremental: 2 changed, 45 unchanged]
371
- *[textbox] Email = "user@example.com"
372
- *[button] Submit
373
- ```
374
-
375
- - Changed/new nodes are marked with `*`
376
- - Unchanged subtrees are collapsed entirely
377
- - Use `--full` to force a full snapshot (skips diff)
378
- - Navigation (`nav`) resets the diff baseline automatically
379
208
 
380
- ### Depth Limiting
381
-
382
- Limit tree depth for large pages:
209
+ Project-only:
383
210
 
384
211
  ```bash
385
- chromex snap <target> --depth=3 # Only 3 levels deep
212
+ # npm
213
+ claude mcp add chromex npx chromex-mcp@latest
214
+
215
+ # Bun
216
+ claude mcp add chromex bunx chromex-mcp@latest
386
217
  ```
387
218
 
388
- Nodes at the depth limit render as leaves (children are not expanded).
219
+ After setup, the MCP client can call tools such as `chromex_list`, `chromex_snapshot`, `chromex_click`, `chromex_fill`, `chromex_screenshot`, `chromex_console`, `chromex_network`, `chromex_app_summary`, `chromex_cache_entries`, and `chromex_indexeddb_rows`.
389
220
 
390
- ### Query Filter
221
+ ### Claude Code Auto-Approve
391
222
 
392
- On large pages, a full accessibility tree can be tens of kilobytes. Use `--query` to keep only the nodes you care about, with their ancestors preserved so the hierarchy stays intact:
223
+ To approve all Chromex MCP tools at once, add this to `~/.claude/settings.json`:
393
224
 
394
- ```bash
395
- chromex snap <target> --query=login # Substring match (case-insensitive)
396
- chromex snap <target> --query=issues # role/name/value all searched
225
+ ```json
226
+ {
227
+ "permissions": {
228
+ "allow": ["mcp__chromex"]
229
+ }
230
+ }
397
231
  ```
398
232
 
399
- Matched nodes are prefixed with `>` in the output, so the agent can spot them at a glance. Ancestor chains are included from the match up to the root, so the agent still understands the surrounding structure.
233
+ For CLI usage inside Claude Code, approve the shell command instead:
400
234
 
401
- `@eN` refs stay stable across filtered and unfiltered calls because the ref map is always computed against the full tree. A filtered `snap --query=login` followed by a plain `snap --refs` returns the same ref numbering. Fingerprints for incremental diff are also computed on the full tree, so the next non-query snapshot still produces a correct diff against the previous state.
235
+ ```json
236
+ {
237
+ "permissions": {
238
+ "allow": [
239
+ "Bash(chromex *)",
240
+ "Bash(chromex-cli *)"
241
+ ]
242
+ }
243
+ }
244
+ ```
402
245
 
403
- Measured reduction on a real 65 KB GitHub repo page snapshot:
246
+ Review these permissions before enabling them. Chromex security settings still apply, and every command is audit-logged when `auditLog` is enabled.
404
247
 
405
- | Query | Output bytes | Reduction |
406
- |-------|-------------:|----------:|
407
- | `snap --full` (baseline) | 65,455 | -- |
408
- | `snap --query=issues` | 317 | **-99.5%** |
409
- | `snap --query=star` | 1,490 | **-97.7%** |
410
- | `snap --query=readme` | 936 | **-98.6%** |
248
+ ## CLI vs MCP
411
249
 
412
- When no node matches, chromex returns the explicit empty state `snap: no matches for query "X"` so the agent never confuses an empty filter with a silent failure.
250
+ Both interfaces use the same CDP core and the same per-tab daemons. Choose based on the workflow.
413
251
 
414
- ### Scroll Detection
252
+ | Use case | Prefer CLI | Prefer MCP |
253
+ |----------|------------|------------|
254
+ | Token-sensitive agent sessions | Yes | No |
255
+ | Terminal scripts and CI | Yes | No |
256
+ | Quick one-off browser inspection | Yes | Optional |
257
+ | Typed tool discovery in Claude Code | No | Yes |
258
+ | Inline screenshots returned to the client | No, screenshots are files | Yes |
259
+ | Granular per-tool permissions | Shell pattern only | Yes |
260
+ | Lowest setup friction for MCP users | Optional | Yes |
415
261
 
416
- Snapshots automatically detect scrollable containers and report remaining scroll distance:
262
+ You can remove MCP at any time and keep using the CLI:
417
263
 
264
+ ```bash
265
+ claude mcp remove chromex
418
266
  ```
419
- [scroll: page: down:1200px | sidebar: up:300px, down:800px]
420
- ```
421
-
422
- ### Visibility Filtering
423
267
 
424
- - Ignored/hidden accessibility nodes are automatically omitted
425
- - Disabled interactive elements are shown but not assigned refs (can't be interacted with)
426
- - Generic wrapper nodes (`div`, `span` with no semantic role) are collapsed -- their children inherit the parent's depth
427
- - Names longer than 200 characters are truncated with `...`
268
+ ## Command Overview
428
269
 
429
- ## Auto-Snapshot
430
-
431
- Interactive commands automatically append an incremental snapshot with refs after execution. This lets the AI agent see the updated page state without a separate `snap` call:
270
+ ### Pages and Browser
432
271
 
433
272
  ```bash
434
- chromex click <target> @e3
435
- # Output:
436
- # Clicked @e3 [button] "Submit"
437
- #
438
- # [incremental: 5 changed, 40 unchanged]
439
- # @e1 [heading] Thank you!
440
- # @e2 [link] Back to home
441
- # ...
273
+ chromex list
274
+ chromex open "https://example.com"
275
+ chromex close <target>
276
+ chromex focus <target>
277
+ chromex launch --url https://example.com
278
+ chromex launch --browser brave --incognito
279
+ chromex launch --headless --url https://example.com
280
+ chromex launch --browser-path /path/to/chrome --url https://example.com
281
+ chromex doctor
282
+ chromex incognito https://example.com
283
+ chromex stop
442
284
  ```
443
285
 
444
- Commands that trigger auto-snapshot: `click`, `clickxy`, `type`, `key`, `fill`, `clear`, `select`, `check`, `form`, `nav`, `dialog`, `loadall`, `drag`, `touch`, `upload`.
445
-
446
- Suppress with `--no-snap` for scripts doing rapid sequential actions:
286
+ ### Inspect
447
287
 
448
288
  ```bash
449
- chromex fill <target> @e1 "user@test.com" --no-snap
450
- chromex fill <target> @e2 "secret123" --no-snap
451
- chromex click <target> @e3 # Only this one triggers snapshot
289
+ chromex snap <target> --refs
290
+ chromex snap <target> --query=login
291
+ chromex html <target> "#main"
292
+ chromex shot <target> /tmp/page.png
293
+ chromex shot <target> /tmp/full.png --full
294
+ chromex shot <target> @e5
295
+ chromex console <target> list
296
+ chromex net <target>
297
+ chromex perf <target>
298
+ chromex domsnapshot <target> --styles
452
299
  ```
453
300
 
454
- ## Contextual Hints
455
-
456
- After any action that produces a fresh ref map (auto-snap on interactive commands, or an explicit `snap --refs`), chromex appends a `help[N]:` block with up to 3 next-step suggestions picked heuristically from the current elements and the last command:
301
+ ### Navigate and Wait
457
302
 
303
+ ```bash
304
+ chromex nav <target> "https://example.com"
305
+ chromex nav <target> back
306
+ chromex nav <target> reload-hard
307
+ chromex waitfor <target> ".results" 10000
308
+ chromex wait <target> networkidle
309
+ chromex scroll <target> bottom
458
310
  ```
459
- Navigated to https://github.com/login
460
311
 
461
- RootWebArea "Sign in to GitHub"
462
- @e1 [textbox] Username or email address
463
- @e2 [textbox] Password
464
- @e3 [button] Sign in
465
- @e4 [link] Forgot password?
312
+ ### Interact
466
313
 
467
- help[3]:
468
- chromex fill <t> @e1 "<value>" # textbox "Username or email address"
469
- chromex click <t> @e3 # button "Sign in"
470
- chromex click <t> @e4 # link "Forgot password?"
314
+ ```bash
315
+ chromex click <target> @e5
316
+ chromex clickxy <target> 100 200
317
+ chromex key <target> Enter
318
+ chromex type <target> "hello world"
319
+ chromex hover <target> @e12
320
+ chromex drag <target> "#source" "#dest"
321
+ chromex dialog <target> accept
471
322
  ```
472
323
 
473
- The agent gets the most probable next commands inline, eliminating the "decide what to click" turn. Heuristic rules:
474
-
475
- - **After `fill`** -- priority is a matching submit button (label matches `login`, `submit`, `send`, `search`, `go`, `continue`, ...) or `key Enter` fallback, then the next unfilled input.
476
- - **After `nav`** -- first input (highest priority), then first submit button, then first link.
477
- - **After `snap --refs`** (or any default) -- top interactive elements with non-empty names.
478
- - **Maximum 3 hints per response.**
479
-
480
- ### Staleness Guard
324
+ ### Forms
481
325
 
482
- Hints are only emitted when chromex can guarantee the ref map matches the DOM that was just rendered. This prevents the agent from clicking `@eN` coordinates that no longer exist on screen:
326
+ ```bash
327
+ chromex fill <target> @e1 "user@example.com"
328
+ chromex clear <target> "#search"
329
+ chromex select <target> "#country" "BR"
330
+ chromex check <target> "#terms" true
331
+ chromex upload <target> "#avatar" /tmp/photo.png
332
+ chromex form <target> '{"#name":"John","#email":"john@example.com","#terms":true}'
333
+ ```
483
334
 
484
- | Command | Hints? | Why |
485
- |---------|--------|-----|
486
- | `click`, `fill`, `nav`, `type`, ... (default) | Yes | auto-snap just ran with refs |
487
- | `click @e1 --no-snap`, `fill ... --no-snap` | **No** | ref map may be stale |
488
- | `snap --refs` | Yes | ref map populated by this call |
489
- | `snap --refs` on a page with zero interactive elements | **No** | nothing to suggest, avoids a `snap --refs` loop |
490
- | Bare `snap` (no `--refs`) | **No** | ref map was not refreshed |
335
+ ### Data
491
336
 
492
- Navigation (URL, back, forward, reload) always clears the ref map before dispatching, so post-nav hints always reflect the new page.
337
+ ```bash
338
+ chromex cookies <target>
339
+ chromex cookies <target> set '{"name":"token","value":"abc"}'
340
+ chromex storage <target> local
341
+ chromex storage <target> session
342
+ chromex storage <target> usage
343
+ chromex app <target> summary
344
+ chromex sw <target>
345
+ chromex cache <target> list
346
+ chromex cache <target> entries <cacheId> --query=/api
347
+ chromex idb <target> list
348
+ chromex idb <target> schema <databaseName>
349
+ chromex idb <target> rows <databaseName> <objectStoreName> --limit=20
350
+ chromex pdf <target> /tmp/page.pdf
351
+ ```
352
+
353
+ ### Network, Emulation, and Diagnostics
493
354
 
494
- Opt out explicitly with `--no-hints` (CLI) or `noHints: true` (MCP) for scripts that parse output strictly.
355
+ ```bash
356
+ chromex throttle <target> 3g
357
+ chromex intercept <target> block "*.analytics.*"
358
+ chromex har <target> start
359
+ chromex har <target> stop /tmp/trace.har
360
+ chromex emulate <target> iphone-15-pro
361
+ chromex resize <target> 1280 720
362
+ chromex geo <target> -23.55 -46.63
363
+ chromex timezone <target> "America/Sao_Paulo"
364
+ chromex cpu <target> 4
365
+ chromex audit <target> performance,accessibility desktop
366
+ chromex stats <target> --full
367
+ ```
495
368
 
496
- ## Token Efficiency
369
+ ### Advanced
497
370
 
498
- Chromex outputs are designed to be read by LLM agents, not humans. Every format decision -- plain text, refs over CSS selectors, incremental diffs, query filters -- was made to minimize tokens while preserving the information the agent actually needs to act.
371
+ ```bash
372
+ chromex eval <target> "document.title"
373
+ chromex evalraw <target> "Page.getLayoutMetrics"
374
+ chromex inject <target> "window.DEBUG=true"
375
+ chromex download <target> allow /tmp/downloads
376
+ chromex coverage <target> start
377
+ chromex trace <target> start
378
+ chromex heap <target> snapshot /tmp/heap.heapsnapshot
379
+ chromex webauthn <target> enable
380
+ ```
499
381
 
500
- ### Measured against common alternatives
382
+ Run `chromex --help` for the full command reference.
501
383
 
502
- We measured the current plain-text output against three structured format candidates often proposed for agent interfaces: minified JSON, pretty-printed JSON, and a TOON-style compact encoder (a zero-dependency 60-line implementation of the YAML-inline compact style). Five representative chromex outputs were encoded in each format and tokenized with `tiktoken` (`cl100k_base`). Lower token counts are better.
384
+ ## Agent-Focused Features
503
385
 
504
- #### Case by case
386
+ ### Ref-Based Selection
505
387
 
506
- | Case | text-free | json-min | json-pretty | toon-compact |
507
- |--------------------------------|-----------:|---------------:|----------------:|----------------:|
508
- | `snap-login-small` | **130** | 178 (+37%) | 301 (+132%) | 212 (+63%) |
509
- | `snap-repo-large` (65 KB real) | **19,702** | 34,315 (+74%) | 63,232 (+221%) | 44,613 (+126%) |
510
- | `net-list-50` | **454** | 574 (+26%) | 921 (+103%) | 706 (+56%) |
511
- | `console-list-12` | **273** | 363 (+33%) | 576 (+111%) | 453 (+66%) |
512
- | `fill-action-small` | **99** | 127 (+28%) | 221 (+123%) | 146 (+48%) |
388
+ `chromex snap --refs` assigns stable refs to interactive elements:
513
389
 
514
- The five cases cover the most common outputs an agent sees during a real session: a small accessibility snapshot with refs (a login form), a large accessibility snapshot of a real GitHub repository page, a network list with 50 tracked requests, a console list with a mix of `log`, `warn` and `error` entries, and a post-action result (fill + incremental diff + hints).
390
+ ```bash
391
+ chromex snap <target> --refs
392
+ # @e1 [textbox] Email
393
+ # @e2 [textbox] Password
394
+ # @e3 [button] Sign in
515
395
 
516
- #### Aggregate (5 cases combined)
396
+ chromex fill <target> @e1 "user@example.com"
397
+ chromex click <target> @e3
398
+ ```
517
399
 
518
- | Format | tokens | vs text-free |
519
- |------------------------|----------:|-------------:|
520
- | **text-free (current)**| **20,658**| -- |
521
- | json-min | 35,557 | +72.1% |
522
- | json-pretty | 65,251 | +215.9% |
523
- | toon-compact (custom) | 46,130 | +123.3% |
400
+ Refs are shorter and more robust than CSS selectors for most agent workflows.
524
401
 
525
- The current plain-text output is the most token-efficient in every single case. Every structured alternative costs more tokens, not less, because JSON and YAML-style encodings add syntactic overhead (`{`, `}`, `"`, `:`, `,`, indentation) that the chromex plain-text format omits entirely. The chromex format is already dense: short refs (`@e5`), unquoted labels, no wrapping, no redundancy. Structured formats have nothing to optimize away.
402
+ ### Incremental Snapshots
526
403
 
527
- ### Why this matters
404
+ The first snapshot returns the page tree. Later snapshots return only changed nodes unless you pass `--full`.
528
405
 
529
- - **No structured-output refactor is planned.** Chromex keeps the current plain-text format because the data shows it wins.
530
- - **`@eN` refs beat CSS selectors** not just for reliability (accessibility tree is stable across SPA re-renders) but also for token count -- `@e5` is one token, `document.querySelector('#login-form > div.field input[name="email"]')` is around fifteen.
531
- - **`--query` and incremental diff** are where the real token savings live. A filtered snapshot on a large page drops output by 95% to 99%, and an incremental diff after an action drops it by 90% or more. These are multiplicative with the already-dense base format.
406
+ ```bash
407
+ chromex snap <target> --refs
408
+ chromex click <target> @e3
409
+ # The click response includes a fresh incremental snapshot with refs.
410
+ ```
532
411
 
533
- ### Reproducing the benchmark
412
+ ### Query-Filtered Snapshots
534
413
 
535
- The comparison script is checked into the repo and runs standalone:
414
+ Use `--query` to keep output small on large pages:
536
415
 
537
416
  ```bash
538
- node tests/benchmarks/token-format-comparison.mjs
417
+ chromex snap <target> --query=issues --refs
418
+ chromex snap <target> --query="sign in" --refs
539
419
  ```
540
420
 
541
- It uses `js-tiktoken` (devDependency) with `cl100k_base`, the GPT-4 tokenizer. Claude uses its own BPE tokenizer with a different vocabulary, so absolute numbers would shift by a few percent -- but both are byte-pair encoders over similar corpora, and the direction of the comparison (which format wins) is consistent across BPE tokenizers. Nothing in the results is a rounding error: the gaps are 25% to 220%.
421
+ Chromex preserves ancestor nodes so the filtered output still has usable context.
542
422
 
543
- ## MCP vs CLI
423
+ ### Contextual Hints
544
424
 
545
- Both interfaces call the same core, same daemons, same commands. The difference is how they integrate with Claude Code.
425
+ After actions that refresh refs, Chromex can append a `help[N]:` block with likely next commands:
546
426
 
547
- | | CLI (`chromex-cli`) | MCP Server (`chromex-mcp`) |
548
- |---|---|---|
549
- | Token overhead | Zero schema cost | ~500 tokens per tool used (deferred loading) |
550
- | Auto-approve | Glob pattern in settings | `"mcp__chromex"` -- one line |
551
- | Permissions | All-or-nothing | Per-tool granularity |
552
- | Parameters | Positional string args | Typed JSON Schema |
553
- | Screenshots | File path (needs `Read` to view) | Inline image (base64, no extra call) |
554
- | Best for | Terminal, scripts, CI/CD, token-sensitive sessions | Plug-and-play automation, users who want zero-config |
427
+ ```text
428
+ help[3]:
429
+ chromex fill <t> @e1 "<value>" # textbox "Email"
430
+ chromex click <t> @e3 # button "Sign in"
431
+ chromex click <t> @e4 # link "Forgot password?"
432
+ ```
555
433
 
556
- ### Switching Between MCP and CLI
434
+ Disable hints with `--no-hints`.
557
435
 
558
- You can enable and disable the MCP server at any time. The CLI always works regardless.
436
+ ## Application State Suite
559
437
 
560
- **Disable MCP** (saves ~3-5k tokens per session):
438
+ Chromex exposes browser Application panel state without Puppeteer, Playwright, or extra packages. This is useful for debugging PWAs, offline behavior, stale caches, local database migrations, authentication state, and quota issues from the same logged-in browser session an agent is already using.
561
439
 
562
440
  ```bash
563
- claude mcp remove chromex
564
- ```
441
+ # One-line overview for the current origin
442
+ chromex app <target> summary
565
443
 
566
- The CLI (`chromex-cli`) continues working normally -- same commands, same daemons, no change.
444
+ # Origin quota and per-storage-type usage
445
+ chromex storage <target> usage
567
446
 
568
- **Re-enable MCP:**
447
+ # Service Worker registrations and versions
448
+ chromex sw <target>
449
+ chromex sw <target> update https://example.com/
450
+ chromex sw <target> skip-waiting https://example.com/
569
451
 
570
- ```bash
571
- # Global (all projects)
572
- claude mcp add chromex -s user npx chromex-mcp@latest
452
+ # Cache Storage
453
+ chromex cache <target> list
454
+ chromex cache <target> entries <cacheId> --query=/api
455
+ chromex cache <target> body <cacheId> https://example.com/app.js
573
456
 
574
- # Project-only
575
- claude mcp add chromex npx chromex-mcp@latest
457
+ # IndexedDB
458
+ chromex idb <target> list
459
+ chromex idb <target> schema app-db
460
+ chromex idb <target> rows app-db users --limit=20
576
461
  ```
577
462
 
578
- **When to disable MCP:**
579
- - Token-sensitive sessions where every token counts
580
- - You only need occasional commands (`list`, `snap`, `shot`)
581
- - You're already comfortable with the CLI syntax
582
- - You're using chromex from terminal/scripts, not from Claude Code
583
-
584
- **When to keep MCP enabled:**
585
- - Automating multi-step browser workflows (snap -> click -> fill -> snap)
586
- - You want per-tool auto-approve without glob patterns
587
- - You want inline screenshots without a separate `Read` call
588
- - First time using chromex (discovery via tool schema)
589
-
590
- ### CLI Auto-Approve
463
+ `chromex app <target> summary` includes origin, quota, localStorage key count, sessionStorage key count, cookie count, Cache Storage cache/entry counts, IndexedDB database count, active/waiting Service Worker counts, storage bucket count, and manifest status.
591
464
 
592
- If you prefer the CLI interface, add this to `~/.claude/settings.json`:
593
-
594
- ```json
595
- {
596
- "permissions": {
597
- "allow": [
598
- "Bash(chromex-cli *)"
599
- ]
600
- }
601
- }
602
- ```
465
+ Destructive Application commands are explicit: `storage clear-site-data`, `sw unregister`, `cache delete-entry`, `cache delete`, and `idb clear`.
603
466
 
604
467
  ## Security
605
468
 
606
- Config at `~/.chromex/config.json` (auto-created on first run):
469
+ Chromex creates `~/.chromex/config.json` on first run:
607
470
 
608
471
  ```json
609
472
  {
610
- "blockedDomains": ["mail.google.com", "bank.example.com"],
473
+ "commandTimeout": 15000,
474
+ "navigationTimeout": 30000,
475
+ "idleTimeout": 1200000,
611
476
  "allowedDomains": [],
612
- "blockedCdpMethods": ["Browser.close", "Storage.getCookies", "..."],
613
- "socketAuth": true,
614
- "auditLog": true
477
+ "blockedDomains": [],
478
+ "blockedCdpMethods": ["Browser.close", "Storage.getCookies"],
479
+ "auditLog": true,
480
+ "socketAuth": true
615
481
  }
616
482
  ```
617
483
 
618
- - **Domain filtering**: block sensitive sites or restrict to a whitelist
619
- - **CDP blocklist**: dangerous methods blocked by default in `evalraw`
620
- - **Socket auth**: 32-byte random token per session (mode 0600)
621
- - **Audit log**: every command logged with timestamp and status
484
+ Recommended security practices:
622
485
 
623
- See [docs/security.md](docs/security.md) for full details.
486
+ - Add sensitive sites to `blockedDomains`, such as email, banking, password managers, and admin panels.
487
+ - Use `allowedDomains` in restricted environments where the agent should access only specific hosts.
488
+ - Keep `socketAuth` enabled.
489
+ - Keep `auditLog` enabled and review `~/.chromex/audit.log` when needed.
490
+ - Prefer `chromex launch --profile testing` for isolated browser state.
624
491
 
625
- ## How It Works
492
+ See [docs/security.md](docs/security.md) for the full security model.
626
493
 
627
- 1. **Browser detection** -- scans ~30 paths for `DevToolsActivePort` (or use `CDP_PORT_FILE` env var)
628
- 2. **Daemon spawn** -- first command to a tab spawns a background Node.js process connected via CDP WebSocket
629
- 3. **Session persistence** -- daemon holds the session open; Chrome's "Allow" modal fires once per daemon
630
- 4. **Unix sockets** -- CLI/MCP communicates with daemon via authenticated Unix sockets
631
- 5. **Auto-exit** -- daemons shut down after 20 minutes of inactivity (configurable)
494
+ ## How It Works
632
495
 
496
+ ```text
497
+ CLI or MCP client -> authenticated Unix socket -> per-tab daemon -> CDP WebSocket -> browser
633
498
  ```
634
- CLI Client ──Unix Socket + Auth──> Per-Tab Daemon ──CDP WebSocket──> Chrome
635
- MCP Server ──Unix Socket + Auth──> (same) ──CDP WebSocket──> Chrome
636
- ```
637
499
 
638
- See [docs/architecture.md](docs/architecture.md) for the full deep dive.
500
+ 1. Chromex finds the browser DevTools endpoint from `DevToolsActivePort` or `CDP_PORT_FILE`.
501
+ 2. The first tab command starts a detached daemon for that tab.
502
+ 3. The daemon attaches once through CDP and keeps the session open.
503
+ 4. CLI and MCP commands talk to the daemon through an authenticated Unix socket.
504
+ 5. Daemons exit after the configured idle timeout.
505
+
506
+ See [docs/architecture.md](docs/architecture.md) for implementation details.
639
507
 
640
508
  ## Documentation
641
509
 
642
510
  | Guide | Description |
643
511
  |-------|-------------|
644
- | [Getting Started](docs/getting-started.md) | Installation, connection methods, first commands |
645
- | [Inspect & Debug](docs/inspect.md) | Screenshots, accessibility tree, refs, HTML, eval, network, performance, console |
646
- | [Navigate & Interact](docs/navigate.md) | Navigation, clicking, typing, scrolling, drag & drop, touch, dialogs |
647
- | [Form Filling](docs/forms.md) | Fill, clear, select, check, upload, batch fill with examples |
648
- | [Data Access](docs/data.md) | Cookies, localStorage, sessionStorage, PDF export |
649
- | [Network Control](docs/network.md) | Throttling, interception, mocking, HAR recording |
650
- | [Device Emulation](docs/emulation.md) | Responsive testing, geolocation, timezone, CPU throttling |
651
- | [Security](docs/security.md) | Domain filtering, CDP blocklist, audit log, best practices |
652
- | [Advanced](docs/advanced.md) | Script injection, code coverage, tracing, heap snapshots, WebAuthn |
653
- | [Architecture](docs/architecture.md) | How it works: daemon model, connection modes, file layout |
512
+ | [Getting Started](docs/getting-started.md) | Installation, browser setup, first commands. |
513
+ | [Inspect and Debug](docs/inspect.md) | Screenshots, accessibility tree, refs, HTML, eval, network, performance, console. |
514
+ | [Navigate and Interact](docs/navigate.md) | Navigation, clicking, typing, scrolling, drag and drop, touch, dialogs. |
515
+ | [Form Filling](docs/forms.md) | Fill, clear, select, check, upload, batch form examples. |
516
+ | [Data Access](docs/data.md) | Cookies, localStorage, sessionStorage, Application state, Cache Storage, IndexedDB, Service Workers, PDF export. |
517
+ | [Network Control](docs/network.md) | Throttling, interception, mocking, HAR recording. |
518
+ | [Device Emulation](docs/emulation.md) | Responsive testing, geolocation, timezone, CPU throttling. |
519
+ | [Security](docs/security.md) | Domain filtering, CDP blocklist, audit log, best practices. |
520
+ | [Advanced](docs/advanced.md) | Script injection, code coverage, tracing, heap snapshots, WebAuthn. |
521
+ | [Architecture](docs/architecture.md) | Daemon model, connection modes, and file layout. |
522
+
523
+ ## Development
524
+
525
+ ```bash
526
+ git clone https://github.com/whallysson/chromex.git
527
+ cd chromex
528
+ bun install
529
+ bun run test
530
+ ```
531
+
532
+ The runtime package has no dependencies. Development dependencies are used only for tests and token benchmarks.
533
+
534
+ To reproduce the token-format comparison:
535
+
536
+ ```bash
537
+ bun tests/benchmarks/token-format-comparison.mjs
538
+ ```
654
539
 
655
540
  ## License
656
541
 
657
- MIT
542
+ MIT. See [LICENSE](LICENSE).