chrome-agent 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Stephane Derosiaux
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,339 @@
+# chrome-agent
+
+Browser automation for AI agents. Single Rust binary, zero runtime dependencies, talks CDP directly to Chrome.
+
+## Why
+
+Existing tools (Playwright, Puppeteer, Selenium) carry heavy runtimes and weren't designed for agents. Agents need:
+- **Minimum tokens** — a11y tree snapshots instead of raw HTML (~50 tokens vs ~2000)
+- **Minimum round-trips** — `--inspect` returns updated page state with every action
+- **Zero setup** — single binary, headless by default, no npm/Node required
+- **Persistent sessions** — login once, stay logged in across invocations
+- **Stable UIDs** — element identifiers based on `backendNodeId`, survive between inspects
+- **3 targeting modes** — uid from accessibility tree, CSS selectors, or coordinates
+
+## Install
+
+### For AI agents (recommended)
+
+```bash
+# Install the skill — your agent learns chrome-agent automatically
+npx skills add sderosiaux/chrome-agent
+```
+
+This installs a `SKILL.md` that teaches your agent (Claude Code, Cursor, Copilot, etc.) how to use chrome-agent, including the workflow, commands, and best practices.
+
+### CLI binary
+
+```bash
+# npm (downloads prebuilt binary)
+npm install -g chrome-agent
+
+# or with npx (no install needed)
+npx chrome-agent --help
+
+# or with Cargo (builds from source)
+cargo install chrome-agent
+```
+
+## Quick Start
+
+```bash
+# Navigate and inspect the page in one call
+chrome-agent goto https://example.com --inspect
+# → https://example.com — Example Domain
+# → uid=n1 RootWebArea "Example Domain"
+# →   uid=n9 heading "Example Domain" level=1
+# →   uid=n10 paragraph "This domain is for..."
+# →   uid=n12 link "Learn more"
+
+# Click by uid, get updated page state
+chrome-agent click n12 --inspect
+
+# Fill a form field
+chrome-agent fill --uid n20 "user@test.com"
+
+# Or target by CSS selector (when uids aren't practical)
+chrome-agent click --selector "button.submit"
+chrome-agent fill --selector "input[name=email]" "hello@test.com"
+
+# Extract article content (Mozilla Readability — reader mode)
+chrome-agent read
+
+# Extract full visible text (use --selector to scope, --truncate to cap)
+chrome-agent text --selector "main" --truncate 500
+
+# Evaluate JavaScript
+chrome-agent eval "document.title"
+
+# Screenshot (returns file path, not binary data)
+chrome-agent screenshot
+```
+
+## How It Works
+
+```
+chrome-agent v0.2.0 (Rust, ~5.3K lines, 2.9 MB binary)
+    │
+    │ WebSocket (Chrome DevTools Protocol)
+    ▼
+Chrome / Chromium (headless by default)
+```
+
+No Node.js. No Playwright. No daemon required. Headless by default — `--headed` for debugging.
+
+UIDs are stable across inspects (based on Chrome's `backendNodeId`). The agent inspects, picks a uid, acts — even minutes later. When a11y tree isn't practical, CSS selectors and coordinates work as fallbacks. Click auto-falls back to JS `.click()` when the element has no box model.
+
+## Commands
+
+| Command | Description |
+|---------|------------|
+| `goto <url> [--inspect] [--max-depth N]` | Navigate to URL |
+| `inspect [--verbose] [--max-depth N] [--uid nN] [--filter "role,role"]` | Accessibility tree with stable uids |
+| `click <uid> [--inspect] [--max-depth N]` | Click by uid (JS fallback if no box model) |
+| `click --selector "css" [--inspect]` | Click by CSS selector |
+| `click --xy 100,200` | Click by coordinates |
+| `fill --uid <uid> <value> [--inspect]` | Fill input by uid |
+| `fill --selector "css" <value>` | Fill by CSS selector |
+| `fill-form <uid=val>...` | Batch fill multiple fields |
+| `read [--html] [--truncate N]` | Extract main content (Mozilla Readability) |
+| `text [uid] [--selector "css"] [--truncate N]` | Extract visible text (page or element) |
+| `eval <expression> [--selector "css"]` | Run JS in page context (`el` = matched element) |
+| `network [--filter "pattern"] [--body] [--live N]` | Capture network requests / API responses |
+| `console [--level error] [--clear]` | Show captured console.log/warn/error + JS exceptions |
+| `pipe` | Persistent connection: JSON stdin → JSON stdout |
+| `wait <text\|url\|selector> <pattern>` | Wait for condition |
+| `type <text> [--selector "css"]` | Type into focused/selected element |
+| `press <key>` | Press Enter, Tab, Escape, etc. |
+| `scroll <down\|up\|uid>` | Scroll page or element into view |
+| `hover <uid>` | Hover over element |
+| `back` | Navigate back in history |
+| `screenshot [--filename name]` | Capture screenshot → file path |
+| `tabs` | List open browser tabs |
+| `close [--purge]` | Close browser (--purge deletes profile/cookies) |
+| `status` | Show session info |
+| `stop` | Stop background daemon |
+
+## Global Flags
+
+```
+--browser <name>         Named browser profile (default: "default")
+--page <name>            Named page/tab (default: "default")
+--connect [url]          Connect to running Chrome (auto or explicit)
+--headed                 Show browser window (default is headless)
+--stealth                Bypass bot detection (Cloudflare, Turnstile)
+--timeout <seconds>      Command timeout (default: 30)
+--max-depth <N>          Limit inspect tree depth (works with --inspect on any command)
+--ignore-https-errors    Accept self-signed certificates
+--json                   Structured JSON output for all commands
+```
+
+## The Inspect → Act → Inspect Loop
+
+```bash
+# 1. Navigate and inspect
+chrome-agent goto https://app.com/login --inspect
+# → uid=n47 heading "Login" level=1
+#   uid=n52 textbox "Email" focusable
+#   uid=n58 textbox "Password" focusable
+#   uid=n63 button "Sign In" focusable
+
+# 2. Act
+chrome-agent fill --uid n52 "user@test.com"
+chrome-agent fill --uid n58 "password123"
+
+# 3. Click with --inspect to get result + new state in one call
+chrome-agent click n63 --inspect
+# → Clicked uid=n63
+# → uid=n101 heading "Dashboard" level=1
+# → uid=n105 navigation "Main menu"
+```
+
+UIDs (n47, n52, etc.) are stable — they won't change between inspects as long as the DOM node exists.
+
+## Network Capture
+
+Extract API data directly instead of DOM scraping:
+
+```bash
+# Show resources loaded by the page (stealth-safe, uses Performance API)
+chrome-agent network --filter "api"
+
+# Capture live traffic with response bodies (5 seconds)
+chrome-agent network --live 5 --body --filter "graphql"
+
+# JSON output for structured extraction
+chrome-agent --json network --body --filter "api" --limit 10
+```
+
+## Console Capture
+
+See what the page logs — useful for debugging and error detection:
+
+```bash
+chrome-agent console                    # all messages
+chrome-agent console --level error      # errors + exceptions only
+chrome-agent console --clear            # read and clear buffer
+```
+
+Stealth-safe: uses injected interceptor, not `Runtime.enable`.
+
+## Pipe Mode
+
+Persistent connection for high-performance agent workflows:
+
+```bash
+# Start pipe (one connection, reads JSON from stdin)
+echo '{"cmd":"goto","url":"https://example.com","inspect":true}
+{"cmd":"click","uid":"n12","inspect":true}
+{"cmd":"read"}' | chrome-agent pipe
+```
+
+Each command returns one JSON line: `{"ok":true,...}` or `{"ok":false,"error":"..."}`. 10x faster than spawning chrome-agent per command.
+
+## Content Extraction
+
+```bash
+# Article content (Readability — like Firefox Reader Mode)
+chrome-agent read
+# → # Article Title
+# → Clean article text without nav, footer, sidebar...
+
+# Full page text (scoped by selector)
+chrome-agent text --selector "[role=main]" --truncate 1000
+
+# Structured data via JS
+chrome-agent eval "JSON.stringify([...document.querySelectorAll('h2')].map(e => e.textContent))"
+```
+
+## Stealth Mode
+
+Many sites (Cloudflare, Turnstile) block headless Chrome. `--stealth` patches 7 automation fingerprints via CDP:
+
+```bash
+chrome-agent --stealth goto https://protected-site.com --inspect
+```
+
+What it patches:
+- `navigator.webdriver` → `undefined`
+- `chrome.runtime` → mocked (headless doesn't have it)
+- Permissions API → consistent with real browser
+- WebGL renderer → masks ANGLE/headless fingerprint
+- User-Agent → removes "HeadlessChrome"
+- Input `screenX`/`pageX` leak → random offset added
+- `Runtime.enable` → skipped (the #1 CDP detection vector)
+
+All patches are CDP-level (`Page.addScriptToEvaluateOnNewDocument`). No fake Chrome flags.
+
+### Heavy bot protection (DataDome, Kasada)
+
+Some sites (Leboncoin, etc.) use advanced fingerprinting that detects bundled Chromium regardless of CDP patches. For these, connect to your real installed Chrome instead:
+
+```bash
+# Launch your real Chrome with debugging enabled
+google-chrome --remote-debugging-port=9222 &
+
+# Connect chrome-agent to it
+chrome-agent --connect http://127.0.0.1:9222 goto https://www.leboncoin.fr --inspect
+```
+
+Real Chrome has genuine canvas/audio/codec fingerprints that Chromium lacks.
+
+| Protection Level | Solution |
+|---|---|
+| None | `chrome-agent goto ...` |
+| Cloudflare/Turnstile | `chrome-agent --stealth goto ...` |
+| DataDome/Kasada | `chrome-agent --connect` to real Chrome |
+
+## JSON Mode
+
+```bash
+chrome-agent --json goto https://example.com --inspect
+# → {"ok":true,"url":"...","title":"...","snapshot":"uid=n1 heading..."}
+
+chrome-agent --json eval "1+1"
+# → {"ok":true,"result":2}
+
+chrome-agent --json read
+# → {"ok":true,"title":"...","text":"...","excerpt":"...","byline":"..."}
+
+# Errors also structured (exit 0 for agent parsing):
+chrome-agent --json click n99
+# → {"ok":false,"error":"Element uid=n99 not found.","hint":"Run 'chrome-agent inspect'"}
+```
+
+## Multi-Tab
+
+```bash
+chrome-agent --page main goto https://app.com
+chrome-agent --page docs goto https://docs.app.com
+chrome-agent --page main eval "document.title"   # → "App"
+chrome-agent --page docs eval "document.title"   # → "Docs"
+```
+
+### Parallel Agents
+
+Multiple agents sharing the same browser corrupt each other's sessions. Isolate with `--browser`:
+
+```bash
+# Agent 1
+chrome-agent --browser agent1 goto https://example.com
+
+# Agent 2 (separate Chrome instance)
+chrome-agent --browser agent2 goto https://other.com
+```
+
+## Using with AI Agents
+
+### Skill (recommended)
+
+```bash
+npx skills add sderosiaux/chrome-agent
+```
+
+This installs a SKILL.md that teaches your agent the full chrome-agent workflow, commands, and tips. Works with Claude Code, Cursor, Copilot, and any agent that reads skill files.
+
+### Manual
+
+Tell your agent to run `chrome-agent --help` — the help output includes a complete LLM usage guide.
+
+### Claude Code permissions
+
+```json
+{
+  "permissions": {
+    "allow": ["Bash(chrome-agent *)"]
+  }
+}
+```
+
+### Connect to Your Browser
+
+```bash
+chrome-agent --connect inspect    # auto-discover Chrome with debugging
+google-chrome --remote-debugging-port=9222  # or launch manually
+```
+
+## Comparison
+
+| | chrome-agent | dev-browser | chrome-devtools-mcp | Playwright MCP |
+|---|---|---|---|---|
+| Language | Rust | Rust + Node.js | TypeScript | TypeScript |
+| Runtime deps | none | Node.js + npm + Playwright + QuickJS | Node.js + Puppeteer | Node.js + Playwright |
+| Binary size | ~3 MB | ~3 MB (CLI) + ~200 MB (daemon + deps) | npm package | npm package |
+| CLI startup (reuse session) | ~10ms | ~500ms (daemon check) | N/A (MCP server) | N/A (MCP server) |
+| Element targeting | uid + CSS selector + coordinates | CSS selectors + snapshotForAI | uid (sequential) | CSS selectors |
+| UID stability | backendNodeId (stable across inspects) | N/A | sequential (reassigned each snapshot) | N/A |
+| Action + observe | `--inspect` flag (1 call) | 1 script (batched) | 1 MCP call per action | 1 MCP call per action |
+| Script batching | No (atomic commands + eval) | Full JS scripts in QuickJS sandbox | No | No |
+| Stealth mode | 7 CDP patches + Runtime.enable skip | No | No | No |
+| Reader mode | `read` (Mozilla Readability) | No | No | No |
+| Sandbox | Chrome sandbox | QuickJS WASM sandbox | Chrome sandbox | No |
+| Network capture | Retroactive + live | No | No | Metadata only (no bodies) |
+| Console capture | Stealth-safe interceptor | No | Console messages | No |
+| Pipe mode | JSON stdin/stdout | No | No | No |
+| Code | ~5.3K lines | ~76K lines (69K Playwright fork) | ~12K lines | Playwright |
+
+## License
+
+MIT

package/bin/chrome-agent.js

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+
+import { spawn } from 'child_process';
+import { accessSync, chmodSync, constants, existsSync, readFileSync } from 'fs';
+import { arch, platform } from 'os';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const packageJson = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8'));
+const version = packageJson.version;
+const repoSlug = 'sderosiaux/chrome-agent';
+
+const supportedTargets = Object.freeze({
+  'darwin-arm64': 'chrome-agent-darwin-arm64',
+  'darwin-x64': 'chrome-agent-darwin-x64',
+  'linux-arm64': 'chrome-agent-linux-arm64',
+  'linux-x64': 'chrome-agent-linux-x64',
+  'win32-x64': 'chrome-agent-windows-x64.exe',
+});
+
+function getTargetKey() {
+  const p = platform();
+  const a = arch();
+  if (p === 'darwin') return a === 'arm64' ? 'darwin-arm64' : a === 'x64' ? 'darwin-x64' : null;
+  if (p === 'linux') return a === 'x64' ? 'linux-x64' : a === 'arm64' ? 'linux-arm64' : null;
+  if (p === 'win32') return a === 'x64' ? 'win32-x64' : null;
+  return null;
+}
+
+function main() {
+  const targetKey = getTargetKey();
+  const binaryName = targetKey ? supportedTargets[targetKey] : null;
+
+  if (!binaryName) {
+    console.error(`Error: Unsupported platform: ${platform()}-${arch()}`);
+    console.error(`Supported: ${Object.keys(supportedTargets).join(', ')}`);
+    process.exit(1);
+  }
+
+  const binaryPath = join(__dirname, binaryName);
+
+  if (!existsSync(binaryPath)) {
+    const url = `https://github.com/${repoSlug}/releases/download/v${version}/${binaryName}`;
+    console.error(`Error: Native binary not found at ${binaryPath}`);
+    console.error('The postinstall step downloads it from GitHub releases.');
+    console.error(`Reinstall the package, or download manually from: ${url}`);
+    process.exit(1);
+  }
+
+  if (platform() !== 'win32') {
+    try { accessSync(binaryPath, constants.X_OK); } catch { chmodSync(binaryPath, 0o755); }
+  }
+
+  const child = spawn(binaryPath, process.argv.slice(2), {
+    stdio: 'inherit',
+    windowsHide: false,
+  });
+
+  child.on('error', (error) => {
+    console.error(`Error: ${error.message}`);
+    process.exit(1);
+  });
+
+  child.on('exit', (code, signal) => {
+    if (signal) { process.kill(process.pid, signal); return; }
+    process.exit(code ?? 1);
+  });
+}
+
+main();

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "chrome-agent",
+  "version": "0.3.0",
+  "description": "Browser automation for AI agents. Single binary, zero dependencies, CDP direct.",
+  "type": "module",
+  "bin": {
+    "chrome-agent": "./bin/chrome-agent.js"
+  },
+  "scripts": {
+    "postinstall": "node scripts/postinstall.js"
+  },
+  "files": [
+    "bin/",
+    "scripts/",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "browser",
+    "automation",
+    "ai",
+    "agent",
+    "cdp",
+    "chrome",
+    "headless",
+    "cli"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sderosiaux/chrome-agent.git"
+  },
+  "author": "Stephane Derosiaux"
+}

package/scripts/postinstall.js

@@ -0,0 +1,100 @@
+#!/usr/bin/env node
+
+import { chmodSync, createWriteStream, existsSync, mkdirSync, readFileSync, renameSync, rmSync } from 'fs';
+import { get } from 'https';
+import { arch, platform } from 'os';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const projectRoot = join(__dirname, '..');
+const binDir = join(projectRoot, 'bin');
+const packageJson = JSON.parse(readFileSync(join(projectRoot, 'package.json'), 'utf8'));
+const version = packageJson.version;
+const repoSlug = 'sderosiaux/chrome-agent';
+
+const supportedTargets = Object.freeze({
+  'darwin-arm64': 'chrome-agent-darwin-arm64',
+  'darwin-x64': 'chrome-agent-darwin-x64',
+  'linux-arm64': 'chrome-agent-linux-arm64',
+  'linux-x64': 'chrome-agent-linux-x64',
+  'win32-x64': 'chrome-agent-windows-x64.exe',
+});
+
+function getTargetKey() {
+  const p = platform();
+  const a = arch();
+  if (p === 'darwin') return a === 'arm64' ? 'darwin-arm64' : a === 'x64' ? 'darwin-x64' : null;
+  if (p === 'linux') return a === 'x64' ? 'linux-x64' : a === 'arm64' ? 'linux-arm64' : null;
+  if (p === 'win32') return a === 'x64' ? 'win32-x64' : null;
+  return null;
+}
+
+async function downloadFile(url, destination) {
+  const tempPath = `${destination}.download`;
+  rmSync(tempPath, { force: true });
+
+  return new Promise((resolve, reject) => {
+    const request = (currentUrl, redirects = 10) => {
+      get(currentUrl, {
+        headers: { Accept: 'application/octet-stream', 'User-Agent': `chrome-agent/${version}` },
+      }, (response) => {
+        if (response.statusCode >= 300 && response.statusCode < 400 && response.headers.location) {
+          response.resume();
+          if (redirects === 0) { reject(new Error('Too many redirects')); return; }
+          request(new URL(response.headers.location, currentUrl), redirects - 1);
+          return;
+        }
+        if (response.statusCode !== 200) {
+          response.resume();
+          reject(new Error(`HTTP ${response.statusCode} from ${currentUrl}`));
+          return;
+        }
+        const file = createWriteStream(tempPath);
+        response.pipe(file);
+        file.on('finish', () => file.close(() => {
+          try { renameSync(tempPath, destination); resolve(); }
+          catch (e) { reject(e); }
+        }));
+        file.on('error', reject);
+        response.on('error', reject);
+      }).on('error', reject).setTimeout(30_000, function() { this.destroy(new Error('Timeout')); });
+    };
+    request(url);
+  }).catch((error) => { rmSync(tempPath, { force: true }); throw error; });
+}
+
+async function main() {
+  const targetKey = getTargetKey();
+  const binaryName = targetKey ? supportedTargets[targetKey] : null;
+
+  if (!binaryName) {
+    // Not a fatal error during local dev
+    if (existsSync(join(projectRoot, '.git'))) {
+      console.warn(`Warning: No prebuilt binary for ${platform()}-${arch()}. Build from source with: cargo build --release`);
+      return;
+    }
+    throw new Error(`Unsupported platform: ${platform()}-${arch()}. Supported: ${Object.keys(supportedTargets).join(', ')}`);
+  }
+
+  mkdirSync(binDir, { recursive: true });
+  const binaryPath = join(binDir, binaryName);
+
+  if (existsSync(binaryPath)) {
+    if (platform() !== 'win32') chmodSync(binaryPath, 0o755);
+    console.log(`chrome-agent: native binary already present (${binaryName})`);
+    return;
+  }
+
+  const url = `https://github.com/${repoSlug}/releases/download/v${version}/${binaryName}`;
+  console.log(`chrome-agent: downloading native binary for ${platform()}-${arch()}...`);
+
+  await downloadFile(url, binaryPath);
+  if (platform() !== 'win32') chmodSync(binaryPath, 0o755);
+  console.log(`chrome-agent: installed ${binaryName}`);
+}
+
+main().catch((error) => {
+  console.error(`chrome-agent postinstall failed: ${error.message}`);
+  process.exitCode = 1;
+});