Skip to content
Back to search

Browser4

Browser4 — an AI-native browser engine for autonomous agents, intelligent extraction, and large-scale web automation.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/platonai/Browser4 with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/platonai/Browser4'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/platonai--browser4/badge.svg)](/listings/platonai--browser4)

HTML

<a href="/listings/platonai--browser4"><img src="/api/listings/platonai--browser4/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Paste the following instruction to your favorite AI agent like dsh, claude, codex, workbuddy or openclaw and run it:

Read https://browser4.io/SKILL.md, install or upgrade browser4-cli for browser automation, perform the following task:

1. Open the browser in headed mode (`open --headed`) so the window is visible — this is a human-facing demo
2. go to amazon.com
3. search for pens to draw on whiteboards
4. compare the first 4 ones
5. write the result to a markdown file

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 926 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # 🤖 Browser4
  2. <p align="center">
  3. <a href="https://github.com/platonai/Browser4/actions/workflows/ci.yml"><img alt="CI build" src="https://img.shields.io/github/actions/workflow/status/platonai/Browser4/ci.yml?branch=main&style=flat-square"></a>
  4. <a href="https://github.com/platonai/Browser4/releases"><img alt="Release" src="https://img.shields.io/github/v/release/platonai/Browser4?style=flat-square"></a>
  5. <a href="https://github.com/platonai/Browser4"><img alt="Stars" src="https://img.shields.io/github/stars/platonai/Browser4?style=flat-square"></a>
  6. <a href="https://central.sonatype.com/artifact/ai.platon.pulsar/browser4-core"><img alt="Maven Central" src="https://img.shields.io/maven-central/v/ai.platon.pulsar/browser4-core?style=flat-square"></a>
  7. <a href="https://www.npmjs.com/package/browser4-cli"><img alt="npm" src="https://img.shields.io/npm/v/browser4-cli?style=flat-square"></a>
  8. <a href="https://browser4.io"><img alt="Website" src="https://img.shields.io/website?url=https%3A%2F%2Fbrowser4.io&style=flat-square"></a>
  9. <a href="https://github.com/platonai/Browser4"><img alt="Top language" src="https://img.shields.io/github/languages/top/platonai/Browser4?style=flat-square"></a>
  10. <a href="https://github.com/platonai/Browser4/blob/main/LICENSE"><img alt="License" src="https://img.shields.io/badge/license-APACHE2-green?style=flat-square"></a>
  11. </p>
  12. ---
  13. English | [简体中文](README.zh.md) | [中国镜像](https://gitee.com/platonai_galaxyeye/Browser4)
  14. > ⭐ **Finding Browser4 useful?** Run `browser4-cli star` — with the GitHub CLI signed in it stars this repository as you after a single confirmation (`--gh` skips the prompt); otherwise it opens the repository in the browser you are already logged into and leaves the click to you.
  15. <!-- TOC -->
  16. **Table of Contents**
  17. - [🤖 Browser4](#-browser4)
  18. - [🌟 Introduction](#-introduction)
  19. - [✨ Key Capabilities](#-key-capabilities)
  20. - [Quick Start](#quick-start)
  21. - [DeepSeek Harness integration](#deepseek-harness-integration)
  22. - [🧭 Tool Selection Guide](#-tool-selection-guide)
  23. - [How to Interact with a Page](#how-to-interact-with-a-page)
  24. - [How to Extract Data](#how-to-extract-data)
  25. - [How to Process at Scale](#how-to-process-at-scale)
  26. - [How to Turn HTML into Spreadsheets — Zero LLM Tokens](#how-to-turn-html-into-spreadsheets--zero-llm-tokens)
  27. - [📦 Installation](#-installation)
  28. - [💡 CLI Guide for Humans](#-cli-guide-for-humans)
  29. - [Quick start](#quick-start-1)
  30. - [Mental model](#mental-model)
  31. - [Global options](#global-options)
  32. - [Key concepts before the command list](#key-concepts-before-the-command-list)
  33. - [Complete command reference](#complete-command-reference)
  34. - [Timeout environment variables](#timeout-environment-variables)
  35. - [State persistence](#state-persistence)
  36. - [🚀 Build from Source](#-build-from-source)
  37. - [Architecture](#architecture)
  38. - [📦 Modules Overview](#-modules-overview)
  39. - [🧩 Programming-Agent Kernel (browser4-coding)](#-programming-agent-kernel-browser4-coding)
  40. - [🧪 Test Fixture Server (MockSite)](#-test-fixture-server-mocksite)
  41. - [🤝 Support & Community](#-support--community)
  42. - [📜 Documentation](#-documentation)
  43. - [🔧 Proxy Configuration](#-proxy-configuration---unblock-website-access)
  44. - [License](#license)
  45. - [Links](#links)
  46. <!-- /TOC -->
  47. ## 🌟 Introduction
  48. 💖 **Browser4 — an AI-native browser engine for autonomous agents, intelligent extraction, and large-scale web automation.** 💖
  49. ### ✨ Key Capabilities
  50. * 🤖 **Agent Browser** — AI agents and humans drive real browsers via a Rust CLI, MCP, and an agentic backend: navigate, click, fill, snapshot, batch, and loop.
  51. * 🧬 **Zero-Token Extraction** — X-SQL + CSS selectors for deterministic extraction from live pages or stored HTML snapshots; WebMiner ML clustering turns HTML corpora into spreadsheet and report views with no LLM tokens.
  52. * 🧠 **Hybrid Intelligence** — Combine LLM extraction, ML clustering, X-SQL, and a progressive experience store that reuses learned selectors and blockers.
  53. * ⚡ **High-Performance Runtime** — Coroutine-safe, CDP-native engine designed for 100k–200k complex page visits per machine per day via swarm/crawl scale-out.
  54. * 📦 **Enterprise-Scale Automation** — Swarm crawling, batch/loop jobs, stateful sessions, plugins, runtime skills, browser extension, and an opt-in MCP-over-HTTP endpoint.
  55. * 🛠️ **Programming-Agent Kernel** — 50+ `coding.*` tools (sandboxed shell/fs, scaffolding, validation, self-development) for agents building Browser4 artifacts — or Browser4 itself.
  56. ## Quick Start
  57. Paste the following instruction to your favorite AI agent like dsh, claude, codex, workbuddy or openclaw and run it:
  58. ```
  59. Read https://browser4.io/SKILL.md, install or upgrade browser4-cli for browser automation, perform the following task:
  60. 1. Open the browser in headed mode (`open --headed`) so the window is visible — this is a human-facing demo
  61. 2. go to amazon.com
  62. 3. search for pens to draw on whiteboards
  63. 4. compare the first 4 ones
  64. 5. write the result to a markdown file
  65. ```
  66. ## DeepSeek Harness integration
  67. https://github.com/platonai/dsh-browser4
  68. ```
  69. dsh plugin --profile web add dsh-browser4 # npm registry
  70. dsh plugin --profile web add github:platonai/dsh-browser4 # GitHub
  71. ```
  72. ## 🧭 Tool Selection Guide
  73. Choosing the right tool for your task:
  74. ### How to Interact with a Page
  75. Use `snapshot -i --boxes` to see clickable/typeable elements with refs like `e15`, then `click <ref>`, `fill <ref> "<text>"`, `type`/`press`, `select`, `hover`/`drag`/`scroll`, and `wait` to drive the page. All interaction commands accept CSS selectors too. Chain multiple steps with `batch` — every step runs on the client through the same path as the equivalent standalone command.
  76. Content embedded in `<iframe>`s (payment forms, editors, widgets) is reached with the built-in frame switching: `frames` lists the frame tree, `frame "<iframe selector>"` scopes subsequent element commands into that frame (same-origin iframes fully supported), and `frame main` returns to the main document — no manual `contentDocument` eval needed.
  77. Typical interactive flow:
  78. ```bash
  79. # Humans usually want to see the browser — open it headed
  80. browser4-cli open --headed https://example.com/login
  81. browser4-cli snapshot -i --boxes
  82. browser4-cli fill e3 "user@example.com"
  83. browser4-cli fill e4 "secret" --submit
  84. browser4-cli wait --load networkidle
  85. browser4-cli snapshot -i
  86. # iframe-heavy page:
  87. browser4-cli frame "#pay-frame"
  88. browser4-cli fill "#card-number" "4111 1111 1111 1111"
  89. browser4-cli frame main
  90. ```
  91. ### How to Extract Data
  92. ```
  93. Need to extract data from a page?
  94. ├─ Interactive page (click, fill, scroll first)? → snapshot + refs, then extract
  95. ├─ Static page, one field? → htmlsnapshot get text "<selector>"
  96. ├─ Static page, all matches of one field? → htmlsnapshot get all text "<selector>"
  97. ├─ Static page, multiple correlated fields (title+price+url per item)?
  98. │ → htmlsnapshot query --sql @query.sql
  99. ├─ Live JS / complex DOM logic? → eval --json
  100. ├─ Several outputs from one page (text + links + images + a table)?
  101. │ → scrape --formats "markdown,links,images" # one capture for all of them
  102. ├─ A screenshot or a PDF as a *file* on this machine?
  103. │ → scrape --formats "screenshot,pdf" --output ./out
  104. ├─ Natural language ("find the product price")? → extract (needs LLM key)
  105. └─ High volume, many pages? → crawl or swarm with --sql
  106. ```
  107. ### How to Process at Scale
  108. ```
  109. Need to process multiple pages?
  110. ├─ Single list page (search results)? → htmlsnapshot query with LOAD_AND_SELECT
  111. ├─ List of known URLs (in a file)? → crawl --seed-file urls.txt --depth 0 --sql @query.sql
  112. ├─ Crawl from a start URL (follow links)? → crawl <url> --out-link-selector "..." --depth N
  113. ├─ Need parallel execution (high throughput)? → swarm create → swarm query --seed-file ...
  114. ├─ Repeated monitoring (check every hour)? → loop -i 3600 -- eval "..."
  115. └─ Just a few URLs in a shell script?
  116. → browser4-cli open --headed "https://first-url" # humans: open once, visibly
  117. → for url in ...; do browser4-cli goto "$url"; ... done
  118. ```
  119. ### How to Turn HTML into Spreadsheets — Zero LLM Tokens
  120. [WebMiner](https://github.com/platonai/web-miner) runs ML clustering on downloaded HTML files to produce structured spreadsheets and interactive reports — **no LLM tokens, everything runs locally.** webminer is a first-class Browser4 CLI citizen: `browser4-cli webminer install` + `browser4-cli webminer all <html-dir>` runs the whole pipeline without PowerShell.
  121. ```
  122. Have HTML files and want structured data — without LLM Tokens?
  123. ├─ < 20 pages? → browser4-cli crawl --seed-file urls.txt --depth 0 --sql @query.sql
  124. ├─ < 1,000 pages (small to medium)? → WebMiner Free (SMILE ML engine)
  125. │ browser4-cli webminer install
  126. │ browser4-cli webminer all ./pages/
  127. │ → Interactive HTML report + Excel spreadsheets — local, zero cost
  128. ├─ > 1,000 pages (production scale)? → WebMiner Commercial (Apache Spark ML)
  129. │ Same encode → cluster → views pipeline, distributed across machines
  130. └─ Need to acquire pages first?
  131. ├─ Single pages: browser4-cli htmlsnapshot export
  132. ├─ Bulk download: browser4-cli crawl --seed-file urls.txt --depth 0
  133. └─ High throughput: browser4-cli swarm create → swarm query --seed-file ...
  134. Then feed the HTML directory to WebMiner
  135. ```
  136. > **Pipeline:** `encode` (HTML → feature vectors → CSV) → `cluster` (KMeans, auto-detected K) → `views` (HTML report + Excel). Free tier uses the [SMILE](https://haifengl.github.io/) ML library for single-machine clustering (< 1,000 pages). Requires JDK 17+ (auto-detected). See [web-miner](https://github.com/platonai/web-miner) and `browser4-cli help webminer` for usage.
  137. ---
  138. ## 📦 Installation
  139. Manual installation is optional since your AI agent is smart enough to install it after reading the SKILL.
  140. Install browser4-cli globally using npm (requires Node.js):
  141. ```shell
  142. npm install -g browser4-cli
  143. browser4-cli install
  144. ```
  145. Or bootstrap the native binary directly with a single command. The scripts
  146. also install the Browser4 backend (runtime bundle) afterwards — running
  147. `browser4-cli install` on a fresh machine, or `browser4-cli upgrade` when a
  148. backend is already present (pass `--skip-backend` to skip this step):
  149. **Windows (PowerShell):**
  150. ```powershell
  151. irm https://browser4.oss-cn-beijing.aliyuncs.com/scripts/install-browser4-cli.ps1 | iex
  152. ```
  153. **Linux / macOS (bash):**
  154. ```bash
  155. curl -fsSL https://browser4.oss-cn-beijing.aliyuncs.com/scripts/install-browser4-cli.sh | bash
  156. ```
  157. ## 💡 CLI Guide for Humans
  158. `browser4-cli` is a human-usable browser automation shell, not just an agent backend. You can drive a real browser, inspect state, extract structured data, run X-SQL, orchestrate crawl/swarm jobs, manage server plugins and skills, and hand long-running work to built-in AI features.
  159. If you want the embedded agent-facing instructions, see [skills/browser4-cli/SKILL.md](skills/browser4-cli/SKILL.md). This section is the human reference.
  160. ### Quick start
  161. ```bash
  162. # Open a visible browser session (humans usually want to see the window;
  163. # agents should prefer the default headless mode — see SKILL.md)
  164. browser4-cli open --headed https://browser4.io
  165. # Inspect the page and get element refs
  166. browser4-cli snapshot --boxes
  167. # Interact using a ref from the snapshot
  168. browser4-cli click e15
  169. browser4-cli fill e16 "Browser4" --submit
  170. # Extract data from the live page
  171. browser4-cli get text "h1"
  172. # Capture the page into the store, then extract from that copy
  173. browser4-cli htmlsnapshot
  174. browser4-cli htmlsnapshot get text "#main-content"
  175. browser4-cli htmlsnapshot query --sql @query.sql
  176. # Save output
  177. browser4-cli screenshot --full-page --filename page.jpg
  178. browser4-cli pdf --filename page.pdf
  179. ```
  180. ### Mental model
  181. 1. **Session-oriented**: commands work against the current browser session; use `-s <name>` for isolated named sessions.
  182. 2. **Two page views**: `snapshot` is for interactive work with element refs like `e15`; `htmlsnapshot` is for DOM/X-SQL extraction with CSS selectors.
  183. 3. **Interactive vs static extraction**: use `click`, `fill`, `type`, `press`, `wait` when the page must be manipulated first; use `htmlsnapshot query` when you need structured extraction from the DOM.
  184. 4. **Synchronous vs async jobs**: `agent`, `swarm`, `crawl`, and async chat-style commands return task IDs you poll later.
  185. ### Global options
  186. These flags can appear before any command.
  187. | Flag | Meaning |
  188. |---|---|
  189. | `-h`, `--help [command\|category]` | Show top-level help, category help, or detailed command help |
  190. | `--help-json` | Emit the machine-readable command reference |
  191. | `-v`, `--version` | Print the CLI version |
  192. | `-s`, `--session <name>` | Use a named session instead of the default session. A **global** flag: place it **before** the command (`browser4-cli -s job-42 snapshot`) — after the command it is rejected as a positional argument |
  193. | `--server <url>` | Override the Browser4 server URL |
  194. | `--timeout <seconds>` | Override the HTTP timeout for the current command |
  195. | `--proxy <url>` | Proxy used for runtime downloads/install operations |
  196. | `--json` | Emit machine-readable JSON only |
  197. | `--pretty` | Pretty-print JSON output |
  198. | `-q`, `--quiet` | Suppress normal human-readable output |
  199. | `-tip`, `--show-tip` | Show a relevant tip on stderr after commands |
  200. ### Key concepts before the command list
  201. #### Element refs vs CSS selectors
  202. - `snapshot` returns accessibility-tree refs such as `e5`, `e12`, `e42`
  203. - most interaction commands accept either a snapshot ref or a CSS selector
  204. - `htmlsnapshot` commands use CSS selectors, not accessibility refs
  205. #### `snapshot` vs `htmlsnapshot`
  206. | Tool | Best for | Input model | Output model |
  207. |---|---|---|---|
  208. | `snapshot` | clicking, typing, finding interactive elements | live accessibility tree | refs like `e15` |
  209. | `htmlsnapshot` | DOM inspection, CSS extraction, X-SQL | a fresh snapshot of the active page (every command captures the tab first, then reads; `--expires <dur>` reads the stored snapshot instead) | CSS selectors and query results |
  210. #### LLM configuration
  211. AI-powered commands such as `extract`, `summarize`, `chat`, `agent run`, and X-SQL `llm_*` functions require an LLM provider key.
  212. | Provider | Environment variables |
  213. |---|---|
  214. | DeepSeek | `DEEPSEEK_API_KEY` |
  215. | OpenRouter | `OPENROUTER_API_KEY`, `OPENROUTER_MODEL_NAME`, `OPENROUTER_BASE_URL` |
  216. | Volcengine | `VOLCENGINE_API_KEY`, `VOLCENGINE_MODEL_NAME`, `VOLCENGINE_BASE_URL` |
  217. | OpenAI-compatible | `OPENAI_API_KEY`, `OPENAI_MODEL_NAME`, `OPENAI_BASE_URL` |
  218. | Aliyun Qwen | `OPENAI_API_KEY`, `OPENAI_MODEL_NAME`, `OPENAI_BASE_URL` |
  219. ```bash
  220. export DEEPSEEK_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxx
  221. ```
  222. > Configure **one** provider. When several provider keys are present, the first one in
  223. > Browser4's provider order wins — the order lives in
  224. > `browser4-core/browser4-resources/src/main/resources/config/llm/providers.json`, so a
  225. > leftover `DEEPSEEK_API_KEY` silently wins over `OPENAI_*`, while `OPENAI_API_KEY` wins
  226. > over `GROQ_API_KEY`.
  227. > `browser4-cli doctor` prints the key that won (`Selected key`) and the model the backend
  228. > will request (`Active model`). See [LLM configuration](docs/config.md#which-provider-is-used).
  229. ### Complete command reference
  230. #### Session lifecycle and server administration
  231. | Command | Description |
  232. |---|---|
  233. | `open [url]` | Open a browser session or reconnect to an existing one. **Headless by default.** Supports `--headed` (visible window), `--headless`, `--profile <path>`, `--profile-mode <DEFAULT\|SYSTEM_DEFAULT\|SEQUENTIAL\|TEMPORARY>`, `--interact-level <FASTEST\|FAST\|DEFAULT>`. **Note:** `SYSTEM_DEFAULT` is deprecated and unsupported on Chrome ≥ 143 — use `attach` + `state-save`/`state-load` to reuse system browser state (see [browser-state-import.md](skills/browser4-cli/references/browser-state-import.md)). |
  234. | `attach` | Attach to an existing browser via CDP or the Browser4 extension. Supports `--cdp <url\|port\|channel>` and remote endpoint options. A channel name resolves candidates from the browser's `DevToolsActivePort`, `--remote-debugging-port` and listening ports, and binds the first endpoint that can host a page — over `/json`, or over the browser-level WebSocket that Chrome's built-in `chrome://inspect/#remote-debugging` toggle publishes (`attach --cdp ws://127.0.0.1:<port>/devtools/browser/<uuid>` also works). After a successful attach the CLI prints the browser that actually connected (`Connected browser: …` / `Attached to … at …`) and shows a ⚠ warning when it conflicts with the requested channel (e.g. requested msedge but Chrome connected) — verify it before driving the session. |
  235. | `close` | Close the active browser session. |
  236. | `list` | List browser sessions with their status and next-open behavior. The Connection column prefers the backend-reported actual browser and annotates channel conflicts (e.g. `requested msedge · actual Google Chrome`). Supports `--all`, which adds a Workspace column and includes the sessions persisted by every other checkout (`*` marks the workspace you are running in; foreign rows read Unknown / `-` / Refresh because this backend cannot verify them). |
  237. | `session-default <name>` | Make a named session become the default unnamed session. |
  238. | `close-all` | Close all sessions without stopping the backend. |
  239. | `kill-all` | Force-stop the backend and Browser4-managed browser processes. |
  240. | `stop` | Gracefully stop the Browser4 server. |
  241. | `status` | Show server version, port, health, and the web status panel URL (`http://<server>:18182/status`). When a session is active it also prints a current-session block: Name / Session ID / Status / Display / Connection / Next open. |
  242. | `doctor` | Run diagnostics: build info, LLM status (including the configuration file it reads, the winning provider key and the active model), stale daemon cleanup, optional repair. Supports `--verbose` and `--fix`; `--fix` also writes a commented LLM config template. |
  243. | `doctor log [name]` | List, view, tail, or grep backend log files. Supports `--tail`, grep-style flags, and `doctor log <name> grep <pattern>`. |
  244. | `doctor metrics [filter]` | List, filter, or grep backend metrics. Supports `doctor metrics grep <pattern>`. |
  245. | `doctor status [--section <name>] [--verbose]` | Print the aggregated status panel report in the terminal: summary layer by default, full detail with `--verbose`, one report with `--section` (health, build, runtime, llm, sessions, pulsar-sessions, swarm, url-pool, browsers, drivers, privacy, plugins, skills, metrics, logs), machine-readable JSON with `--json`. |
  246. | `delete-data` | Delete session data. |
  247. | `install` | Install the Browser4 runtime bundle. Supports `--tag <version>` and `--force`. |
  248. | `upgrade` | Upgrade the CLI/runtime bundle. Supports `--tag <version>` and `--force`. |
  249. | `uninstall` | Remove global installs and runtime data. Supports `-y`, `--yes`, and `--dry-run`. |
  250. ```bash
  251. browser4-cli open --headed https://example.com
  252. browser4-cli attach --cdp chrome
  253. browser4-cli doctor --verbose
  254. browser4-cli doctor log server.log --tail
  255. browser4-cli doctor metrics grep request
  256. browser4-cli doctor status --section skills --verbose
  257. ```
  258. **Web status panel:** open `http://127.0.0.1:18182/status` in a browser for a live dashboard
  259. (health, version, JVM/runtime, LLM config, sessions, **Pulsar sessions** — SDK identity,
  260. context and main-loop state, **swarm** — swarm session plus task summary, **URL pool** —
  261. queued/real-time/delay counts per priority cache, browsers & open tabs — per-session
  262. browser/driver binding and tab counts, with on-demand live tab details via
  263. `GET /api/system/tabs` — driver pools, plugins: load/enable state and SDK compatibility,
  264. **skills**: registered skills with origin (classpath/filesystem/programmatic),
  265. metrics, log files; auto-refreshes, set `?refresh=<ms>` to change the interval). The panel
  266. is backed by the aggregated `GET /api/system/status` endpoint; the individual endpoints
  267. (`/api/system/health`, `/api/system/build`, `/api/doctor/llm-status`, `/api/doctor/metrics`,
  268. `/api/doctor/log-files`, `/api/plugins`, `/api/skills`) remain available. `browser4-cli plugin-list` also
  269. reports load/enable state and SDK version for every installed plugin; the same reports can be
  270. read from the terminal with `browser4-cli doctor status`.
  271. **Page screenshots:** open `http://127.0.0.1:18182/pages.html` for a grid of every open page
  272. across sessions. The active tab of each session is captured automatically (click a screenshot
  273. to re-capture it); inactive tabs show a placeholder that captures on click. Swarm sessions only
  274. show placeholders. Screenshots load **asynchronously** — the backend captures in the background
  275. (`202 Accepted` with `Retry-After` while capturing, cached `image/png` when ready), so the panel
  276. never blocks on a capture. Backed by `GET /api/pages` and
  277. `GET /api/pages/{sessionId}/{guid}/screenshot.png` (`?refresh=1` forces a new capture).
  278. #### Navigation
  279. | Command | Description |
  280. |---|---|
  281. | `goto <url>` | Navigate to a URL; auto-opens/reconnects a session if needed. |
  282. | `go-back` | Go back in browser history. |
  283. | `go-forward` | Go forward in browser history. |
  284. | `reload` | Reload the current page. |
  285. #### Core interaction
  286. All interaction commands accept a snapshot ref such as `e15` or a CSS selector unless noted otherwise. Most of them also support `--no-snapshot` to skip the automatic post-action accessibility snapshot.
  287. | Command | Description |
  288. |---|---|
  289. | `click <ref> [button]` | Click an element. Supports `--modifiers`, `--follow`, `--auto-dismiss-dialogs`. |
  290. | `dblclick <ref> [button]` | Double-click an element. Supports `--modifiers`, `--follow`, `--auto-dismiss-dialogs`. |
  291. | `hover <ref>` | Hover over an element. |
  292. | `fill <ref> <text>` | Clear and fill text into an editable field. Supports `--submit`, `--verify`. |
  293. | `type <text> [ref]` | Type text into the focused element or a target element. Supports `--submit`, `--verify`, `--focus`, `--interactable-timeout`, and `--method auto\|chars\|exec` (requires a target ref; `auto` types short text per-character and bulk-inserts long/multi-line text on textarea/contenteditable via a single `execCommand('insertText')`, `chars` forces per-character typing, `exec` forces the bulk insert). |
  294. | `press <key> [ref]` | Press a key on the focused element or a target element. Supports `--verify`, `--follow`. |
  295. | `select <ref> <value>` | Select a dropdown value. Supports `--verify`. |
  296. | `check <ref>` | Check a checkbox or radio button. |
  297. | `uncheck <ref>` | Uncheck a checkbox or radio button. |
  298. | `drag <startRef> <endRef>` | Drag and drop from one element to another. |
  299. | `wait [target]` | Wait for a selector/ref, duration, text, URL pattern, page-load state, or JavaScript expression. Supports `--timeout`, `--text`, `--url`, `--load`, `--fn`. |
  300. | `upload <ref> <file> [file...]` | Upload one or more local files to a page file input. The target must be an `<input type="file">` (anything else errors); the paths must be readable by the browser process — local mode: the same machine, and empty/missing files are rejected with a hint; remote backend: paths resolve on the backend host. Supports `--no-snapshot`. |
  301. `wait --load` accepts `domcontentloaded`, `load`, and `networkidle`. `networkidle` only proves the network went quiet — it does **not** mean late-rendered results exist; for result pages poll the element instead: `wait "<result-selector>"`.
  302. ```bash
  303. browser4-cli click e8 --follow
  304. browser4-cli fill e4 "john@example.com" --submit
  305. browser4-cli type "Browser4" e7 --verify
  306. browser4-cli wait --text "Success"
  307. browser4-cli wait --load networkidle
  308. ```
  309. #### Keyboard and mouse
  310. | Command | Description |
  311. |---|---|
  312. | `keydown <key>` | Press and hold a key. |
  313. | `keyup <key>` | Release a held key. |
  314. | `mousemove <x> <y>` | Move the mouse to viewport CSS pixels `(x, y)`, relative to the main frame's viewport top-left corner. This is not a desktop/screen coordinate and it does not move the OS cursor; a coordinate outside the viewport means "leave the page", not "outside the browser window". Coordinates are stale after the page scrolls. |
  315. | `mousedown [button]` | Press a mouse button. |
  316. | `mouseup [button]` | Release a mouse button. |
  317. | `mousewheel <dx> <dy>` | Scroll using a wheel delta. |
  318. | `scroll <direction> <pixels>` | Scroll the page `up`, `down`, `left`, or `right`. |
  319. #### Page inspection and live extraction
  320. | Command | Description |
  321. |---|---|
  322. | `snapshot` | Capture an accessibility-tree snapshot. Supports `--boxes`/`--no-boxes`, `-i/--interactive`, `-u/--urls`, `-c/--compact`, `--no-compact`, `-d/--depth`, `--selector` (no short form — `-s` is the global session flag), `--raw`, `--stdout`, `-v/--viewport`, `--auto-diff`, `-b/--brief`, `--filename`. `--stdout`/`--raw` output is paginated at 2000 lines/page by default — when truncated, stdout (if piped) gets a `# … output truncated: showing N of M lines …` hint and the full footer goes to stderr; use `--all` or `--page-size 0` for the complete tree, and bound very large pages with `-v N`/`--depth`/`--selector`/`--no-boxes`. |
  323. | `snapshot grep <pattern>` | Search saved/current snapshot YAML with grep-style flags such as `-i`, `-v`, `-c`, `-l`, `-F`, `-w`, `-A`, `-B`, `-C`, `--selector`, `--page`, `--page-size`, `--all`. |
  324. | `snapshot list` | List saved snapshot files with timestamps and sizes. |
  325. | `snapshot clean` | Remove old snapshot files. Supports `--dry-run`. |
  326. | `get <mode> <selector> [name]` | Extract `text`, `html`, `box`, `styles`, `property`, or `attr` from a live page element. |
  327. | `eval [expression] [ref]` | Evaluate JavaScript on the page or an element. Supports `--file`, `--stdin`, `--base64`, `--await`, `--wait-selector`, `--json`. |
  328. | `console [min-level]` | List browser console messages. Supports `--clear`. |
  329. | `cdp <method>` | Send an arbitrary Chrome DevTools Protocol command. Supports `--json <params>`. |
  330. | `generate-locator <ref>` | Generate the best CSS selector for a snapshot ref or existing selector. |
  331. | `resize <width> <height>` | Resize the browser window. |
  332. | `dialog-accept [prompt]` | Accept an alert/confirm/prompt dialog, optionally filling the prompt. |
  333. | `dialog-dismiss` | Dismiss an alert/confirm/prompt dialog. |
  334. `get` modes:
  335. | Mode | Meaning | Example |
  336. |---|---|---|
  337. | `text` | visible inner text | `browser4-cli get text ".price"` |
  338. | `html` | inner HTML | `browser4-cli get html "#main"` |
  339. | `box` | bounding box | `browser4-cli get box "#hero"` |
  340. | `styles` | computed styles | `browser4-cli get styles e9` |
  341. | `property` | DOM property value | `browser4-cli get property "input" value` |
  342. | `attr` | HTML attribute value | `browser4-cli get attr "a" href` |
  343. ```bash
  344. browser4-cli snapshot -i --boxes
  345. browser4-cli snapshot grep -C 2 "button"
  346. browser4-cli eval "document.title"
  347. browser4-cli eval --file script.js --await
  348. browser4-cli console warn
  349. browser4-cli cdp Runtime.evaluate --json '{"expression":"document.title"}'
  350. ```
  351. #### HTML snapshot and X-SQL extraction
  352. `htmlsnapshot` captures a raw DOM snapshot of the page the active tab is showing and is the center of Browser4's structured extraction workflow. **Every `htmlsnapshot` command works on a fresh snapshot of the active page**: it captures the tab first (serializing the document the tab already shows, without navigating) and then operates on that snapshot — `capture` returns the metadata, while the reads consume it, so a read already sees the live document (form results, SPA updates, `eval` mutations). A read can also be told to serve the **stored** snapshot instead: `--expires <dur>` (default `0s`, the live page) serves the stored copy of the active page while it is younger than the window — `htmlsnapshot get text ".price" --expires 1d` reads the previous snapshot version and never touches the tab. A command aimed at another URL (`readability <url>`, `query --url <url>`) reads *that URL's* stored copy, or an independent read-only load when the store has nothing — a URL the tab does not show is never captured, so the tab's document is never filed under it.
  353. | Command | Description |
  354. |---|---|
  355. | `htmlsnapshot` | Short form of `htmlsnapshot capture`. |
  356. | `htmlsnapshot capture` | Capture and store a static HTML snapshot with metadata about the page and interactive elements. |
  357. | `htmlsnapshot get <field> [selector] [name]` | Extract the first matching `text`, `textcontent`, `html`, or `attr` from a fresh snapshot of the active page. Supports `--expires <dur>`. |
  358. | `htmlsnapshot get all <field> [selector] [name]` | Extract all matching values from a fresh snapshot of the active page. Supports `--offset`, `--limit`, and `--expires <dur>`. |
  359. | `htmlsnapshot query [url]` | Run X-SQL against a fresh snapshot of the active page, or against an explicit URL's stored page. Supports `--sql <query\|@file>`, `--sql-stdin`, `--sql-base64`, `--expires <dur>`, result pagination, and extraction-focused output flags. |
  360. | `htmlsnapshot export` | Export a fresh snapshot's HTML to a file. Supports positional file path or `--file <path>` plus `--clean` and `--expires <dur>`. |
  361. | `htmlsnapshot summary [--algorithm <id>]` | Generate a compressed Web Page Summary Index (WPSI) from a fresh snapshot of the active page; plugins may contribute additional algorithm ids. Supports `--expires <dur>`. |
  362. | `htmlsnapshot algorithms` | List installed summary algorithms (built-in `wpsi` plus plugin-contributed ids). No page required. |
  363. | `htmlsnapshot grep <pattern>` | Search a fresh snapshot's HTML with grep-style flags. Supports `--expires <dur>`. |
  364. | `htmlsnapshot inspect [selector]` | Discover recurring DOM patterns and selector candidates in a fresh snapshot of the active page. Supports `--max`, `--depth`, `--stdin`, `--selector-base64`, `--expires <dur>`. |
  365. | `htmlsnapshot readability [url]` | Extract the main article content with a Readability-style heuristic — no LLM, no tokens. Without a URL: the active page; with one: that URL's own stored copy. Supports `--text-only`, `--expires <dur>`, and pagination. |
  366. Important rules:
  367. - use `snapshot` when you need refs and interaction
  368. - use `htmlsnapshot` when you need repeated DOM extraction — every command captures the tab first, so simply rerunning it sees the page as it is now
  369. - use `--expires <dur>` on a read when you want the snapshot already in the store (`--expires 1d`) instead of the live page (`--expires 0s`, the default) — the stored copy is left untouched and the tab is not serialized
  370. - `htmlsnapshot query --sql @query.sql` is the recommended way to avoid shell quoting issues
  371. - for correlated list extraction, prefer `htmlsnapshot query` over repeated `get all`
  372. - for one-step article extraction (no selectors needed), use `htmlsnapshot readability`
  373. ```bash
  374. browser4-cli htmlsnapshot
  375. browser4-cli htmlsnapshot get text "#productTitle"
  376. browser4-cli htmlsnapshot get all text ".result-title" --offset 10 --limit 5
  377. browser4-cli htmlsnapshot inspect ".s-result-item" --depth 6 --max 20
  378. browser4-cli htmlsnapshot export --file page.html --clean
  379. browser4-cli htmlsnapshot query --sql @query.sql
  380. browser4-cli htmlsnapshot readability --text-only --all
  381. ```
  382. For deep X-SQL usage, see [skills/browser4-cli/references/htmlsnapshot.md](skills/browser4-cli/references/htmlsnapshot.md) and [skills/browser4-cli/references/x-sql-dom-load-select.md](skills/browser4-cli/references/x-sql-dom-load-select.md).
  383. #### Screenshots and PDF
  384. | Command | Description |
  385. |---|---|
  386. | `screenshot [ref]` | Take a page or element screenshot. Supports `--filename`, `--full-page`, `--viewport`. |
  387. | `pdf` | Save the current page as PDF. Supports `--filename`. |
  388. #### Tabs
  389. | Command | Description |
  390. |---|---|
  391. | `tab-list` | List open tabs with indexes, titles, and URLs; use `--json` for full GUIDs. |
  392. | `tab-new [url]` | Open a new tab, optionally navigating to a URL. |
  393. | `tab-close [index]` | Close a tab by index; supports `--guid <guid>`. |
  394. | `tab-select <index>` | Switch to a tab by index; supports `--guid <guid>`. |
  395. #### Browser storage and local page data
  396. | Command | Description |
  397. |---|---|
  398. | `state-save [filename]` | Save cookies and localStorage to a JSON file. |
  399. | `state-load <filename>` | Restore cookies and localStorage from a JSON file. |
  400. | `cookie-list` | List cookies. Supports `--domain`, `--path`. |
  401. | `cookie-get <name>` | Get a cookie by name. |
  402. | `cookie-set <name> <value>` | Set a cookie. Supports `--domain`, `--path`, `--expires`, `--httpOnly`, `--secure`, `--sameSite`. |
  403. | `cookie-delete <name>` | Delete a cookie by name. Supports `--domain`, `--path`. |
  404. | `cookie-clear` | Clear all cookies. |
  405. | `localstorage-list` | List localStorage entries. |
  406. | `localstorage-get <key>` | Read a localStorage key. |
  407. | `localstorage-set <key> <value>` | Set a localStorage key. |
  408. | `localstorage-delete <key>` | Delete a localStorage key. |
  409. | `localstorage-clear` | Clear localStorage. |
  410. | `sessionstorage-list` | List sessionStorage entries. |
  411. | `sessionstorage-get <key>` | Read a sessionStorage key. |
  412. | `sessionstorage-set <key> <value>` | Set a sessionStorage key. |
  413. | `sessionstorage-delete <key>` | Delete a sessionStorage key. |
  414. | `sessionstorage-clear` | Clear sessionStorage. |
  415. | `webdb export <dir>` | Export pages from the Browser4 web database to a local directory. |
  416. | `webdb normalize <url>` | Normalize a URL into the web database key format. |
  417. #### AI extraction, chat, and autonomous agent tasks
  418. These commands require an LLM key.
  419. | Command | Description |
  420. |---|---|
  421. | `extract <instruction>` | Extract structured data from the current page. Supports `--schema <json\|@file>`, `--filename`, `--raw`, `--stdout`. |
  422. | `summarize [instruction]` | Summarize the current page. Supports `--selector`, `--filename`, `--raw`, `--stdout`. |
  423. | `chat <message>` | Send a plain AI chat request without auto-appended browser context. |
  424. | `chat-result <id>` | Retrieve the result of an async chat task. |
  425. | `agent run <task>` | Submit an autonomous browser task and immediately receive a task ID. Supports `--wait` (block for the result) and `--wait-timeout <seconds>` (default 600). `--follow` streams every step (tool calls, model text, slow/failed tools) and ends with the result — Ctrl+C cancels the task; `--ndjson` emits that stream as one JSON object per line. `-i` opens an interactive session where a line typed while a task runs steers it (never queued as a second task), and `/stats` reports the run's LLM rounds/requests, token usage (prompt-cache reads/writes and hit rate included when the provider reports them) and tool calls; the per-task budget counts **cache-miss** tokens (5M by default — prompt-cache reads are free), a budget abort offers a one-key "continue" with the cap doubled, and after every task `-i` predicts 2–3 numbered next *tasks* — the model's own follow-up suggestions first, then what the payload left open (files to review/test/commit, findings to dig into, a failure to diagnose) — never a menu of CLI commands; every task of a session also inherits a compacted `## Session context` block of the earlier ones, plus any mid-session correction — a revised goal supersedes the original, and the current instruction wins over both (`/new` starts a fresh context), and `/result [--json] [--full]` re-prints the last payload (pretty-printed JSON, or nothing folded). A backend hiccup or an unreadable step never ends the live view: `-i` keeps following a task that still runs and skips the one unreadable step. Task type is browser by default; `--coding` explicitly marks a pure file/build task (never auto-detected). `--access <preset>` (`full`/`write`/`read-build`/`read`) narrows that task's coding tools and is reset when the task ends; `--unrestricted` runs it with YOUR own OS permissions instead (full preset, no workspace/protected rails, no OS sandbox — and the shell's command allow-list off as well, so programs outside it (a PowerShell cmdlet, for example) run verbatim; shapes the checker cannot decompose, such as `for` loops and inline scripts, are handed to the platform shell in every mode), audited per task and inherited by `--resume`, while the OS credential stores (`~/.ssh`, `~/.aws`, `~/.gnupg`, `~/.config/gcloud`) and the commands that would kill or rebuild the backend stay refused; `--add-dir <folder>` grants this task an extra **existing** folder besides its workspace (repeatable; readable, writable and usable as a shell working directory — `--access` still bounds what may be written there, credential stores stay refused, and `--resume` inherits the grant; in `-i`, `/add-dir <folder>` grants one mid-session and `/dirs [clear]` lists or drops the grants); a refused step is not a dead end — `coding.requestAccess` files a non-blocking pending request and an operator approves it through `POST /api/agent/<taskId>/access/<requestId>/approve`, while `denyTools`, protected paths and sensitive paths are never approved; a job with no TTY (scripts, CI, submitted tasks) derives `full` with outbound network instead of the server-wide preset (`browser4.agent.access.unattended` narrows it) |
  426. | `agent status <id>` | Check a task — the shared status envelope (`status`: queued/running/done/failed/cancelled, plus `statusCode`, `message` and the agent's step count). |
  427. | `agent result <id>` | Fetch a completed task's result: its summary, `keyFindings`, `filesChanged` and the workspace its deliverables live in. Rendered as sections (`--json` prints the raw envelope). |
  428. | `agent list` | List tracked agent tasks with the same statuses (refreshed from the backend on every call); `--clear` untracks the finished ones. |
  429. ```bash
  430. browser4-cli extract "product name, price, rating"
  431. browser4-cli extract "contacts" --schema @schema.json
  432. browser4-cli summarize --selector "#reviews"
  433. browser4-cli agent run "Go to amazon.com, compare the first 3 keyboards, write a summary"
  434. browser4-cli agent status agent-task-1
  435. ```
  436. #### Batch and loop automation
  437. | Command | Description |
  438. |---|---|
  439. | `batch [command...]` | Execute multiple commands in one invocation. The steps run on the client — one backend call per step, through the same path as the equivalent standalone command. Supports `--bail` (stop at the first failed step) and `--json` (read the command array from stdin). Exit code 5 means at least one step failed. |
  440. | `loop [task]` | Run a task repeatedly. Supports `--name`, `-i/--interval`, `-n/--count`, `-t/--timeout`, `--shell`, `--list`, `--pause`, `--resume`, `--pause-all`, `--resume-all`, `--stop`, `--stop-all`, `--status`, `--history`, `--keep-state`. |
  441. Batch-compatible commands:
  442. ```text
  443. goto go-back go-forward reload press key keyboard type keydown keyup
  444. click dblclick hover fill select upload check uncheck drag focus
  445. mousemove mousedown mouseup mousewheel scroll wait get eval
  446. snapshot screenshot pdf dialog-accept dialog-dismiss resize
  447. tab-list tab-new window-new tab-close tab-select frame
  448. htmlsnapshot htmlsnapshot-capture htmlsnapshot-get htmlsnapshot-get-all
  449. ```
  450. ```bash
  451. browser4-cli batch --bail "goto https://example.com" "snapshot" "screenshot"
  452. browser4-cli loop "load https://example.com and extract the title" -i 300 -n 10
  453. browser4-cli loop --shell "curl -s https://api.example.com/health" -i 60
  454. browser4-cli loop --list
  455. ```
  456. Every batch step is compiled and executed on the client through the same code
  457. path as the equivalent standalone command, so a step behaves exactly as it would
  458. on its own: it opens the session when needed, restores the focused element and
  459. the mouse position, honours `--timeout` and `--verify`, and prints its snapshot.
  460. The steps are **not** packed into a single backend request — each one is its own
  461. call. A step that fails is reported on stderr as
  462. `Batch command N failed (<command>): <reason>` and the batch continues with the
  463. next step, unless `--bail` was given.
  464. #### Network inspection, HAR recording & request routing
  465. Inspect what the page actually loaded (XHR/fetch calls, status codes, headers,
  466. response bodies), record a HAR 1.2 archive importable by Chrome DevTools, and
  467. route (mock/abort) matching requests. See
  468. [`skills/browser4-cli/references/network.md`](skills/browser4-cli/references/network.md)
  469. for the full guide.
  470. | Command | Description |
  471. |---|---|
  472. | `network requests` | List tracked requests. Supports `--filter`, `--type`, `--method`, `--status` (`200`, `2xx`, `400-499`), `--clear`. |
  473. | `network request <id>` | Full detail of one request: headers, timing, and the response body (fetched on demand). |
  474. | `network har start [--content <mode>]` | Start a HAR recording. Content mode: `none`, `text`, or `all` (binary base64). |
  475. | `network har stop [path]` | Stop recording and print the HAR JSON, or write it to a `.har` file when a path is given. |
  476. | `network route <pattern> --body <text>\|--abort` | Intercept matching requests (mock response or fail them) via CDP Fetch. Supports `--content-type`, `--resource-type`. |
  477. | `network unroute [pattern]` | Remove routes; without a pattern, disable interception entirely. |
  478. ```bash
  479. browser4-cli network requests --filter api --status 2xx
  480. browser4-cli network har start --content text
  481. browser4-cli network har stop ./capture.har
  482. browser4-cli network route "**/api/users" --body '{"users":[]}' --content-type application/json
  483. ```
  484. #### Swarm and crawl for scale
  485. The `co` prefix is accepted as an alias for `swarm`.
  486. | Command | Description |
  487. |---|---|
  488. | `swarm create` | Create a parallel scraping session. Supports `--profile-mode`, `--max-open-tabs`, `--max-browser-contexts`, `--display-mode`. |
  489. | `swarm submit [url]` | Submit URLs or X-SQL payloads as jobs. Supports `--seed-file`, `--sql`, `--deadline`, `--expires`, `--refresh`, `--parse`. |
  490. | `swarm query <url>` | Run an X-SQL extraction job against one or more loaded pages. Supports `--sql`, `--seed-file`, `--deadline`, `--expires`, `--refresh`. |
  491. | `swarm status <id>` | Check a swarm task status. |
  492. | `swarm result <id>` | Fetch a completed swarm result. |
  493. | `swarm list` | List tracked swarm tasks. |
  494. | `swarm close` | Close the swarm session and release browser resources. |
  495. | `crawl [url]` | Crawl from a URL or seed file (every seed must be an absolute http(s) URL — a malformed one is refused before the crawl is submitted). Supports `--seed-file`, `--sql`, `--sql-stdin`, `--sql-base64`, `--format`, `--output`, `-d/--depth`, `-ol/--out-link-selector`, `-olp/--out-link-pattern`, `-tl/--top-links`, `-a/--args`, `--refresh`, `--parse`, `--expires`, `-p/--priority`, `--page-load-timeout`, `--ignore-url-query`, `--no-norm`, `--readonly`, `--args-stdin`, `--parallel`, `--timeout`, `--verbose`, `-bg/--background`. |
  496. | `crawl status <id>` | Check crawl task status. |
  497. | `crawl result <id>` | Fetch crawl results. |
  498. | `crawl cancel <id>` | Cancel a running crawl (the checkpoint is kept, so it can be resumed). |
  499. | `crawl resume <id>` | Continue an interrupted crawl from its checkpoint: same task id, no repeat requests for URLs that already succeeded. `--retry-failed` re-fetches terminal failures; automatic resume at startup is off by default (`crawl.autoResume`). See [Crawl checkpoint & resume](docs/crawl-checkpoint-resume.md). |
  500. | `crawl clear` | Remove terminal-state crawl tasks; supports force-style cleanup options. Resumable checkpoints are kept until `crawl clear --all`. |
  501. | `crawl list` | List tracked crawl tasks (`--status interrupted` shows the resumable ones). |
  502. ```bash
  503. browser4-cli swarm create --max-open-tabs 12 --display-mode HEADLESS
  504. browser4-cli swarm query --seed-file urls.txt --sql @query.sql --refresh
  505. browser4-cli crawl "https://example.com" --depth 2 --out-link-selector "a[href]"
  506. browser4-cli crawl list
  507. browser4-cli crawl resume <task-id> # continue an interrupted crawl
  508. ```
  509. #### WebMiner — HTML to spreadsheets, zero LLM Tokens
  510. WebMiner runs locally against a downloaded JAR (`scent-miner.jar`) and does not need the Browser4 server. See [How to Turn HTML into Spreadsheets](#how-to-turn-html-into-spreadsheets--zero-llm-tokens) for the full pipeline.
  511. | Command | Description |
  512. |---|---|
  513. | `webminer install [version]` | Download and install the webminer release to `~/.scent/webminer`, verifying the SHA-256 checksum (GitHub Releases with an OSS mirror fallback). Supports `--force`. |
  514. | `webminer update` | Update webminer to the latest release. |
  515. | `webminer version` | Print the installed webminer version. |
  516. | `webminer uninstall` | Remove the installed webminer. |
  517. | `webminer run-example` | Run the bundled example. |
  518. | `webminer all <html-dir>` | Run the full pipeline (encode → cluster → views) on a directory of HTML files. Supports `--max-files`, `--output`, `--resume`. |
  519. | `webminer views <result-dir>` | Rebuild the interactive views (`<project>.html`, xlsx, json) from an existing clustering result directory. |
  520. ```bash
  521. browser4-cli webminer install
  522. browser4-cli webminer all ./pages/
  523. ```
  524. #### Bundled skill files vs installed runtime skills
  525. Browser4 has two different "skill" surfaces:
  526. 1. **`skills ...`** manages bundled, embedded skill documents that ship with the CLI.
  527. 2. **`skill-*`** manages installed runtime skills exposed by the backend.
  528. ##### Bundled CLI skills
  529. | Command | Description |
  530. |---|---|
  531. | `skills` | List bundled skill names. |
  532. | `skills list` | Same as `skills`. |
  533. | `skills get <name>` | Print a skill's `SKILL.md`. Supports `--full` and `--all`. |
  534. | `skills path [name]` | Print the bundled skill directory path. |
  535. | `skills unpack [dest]` | Unpack bundled skill files to a directory. |
  536. ##### Installed runtime skills
  537. | Command | Description |
  538. |---|---|
  539. | `skill-list` | List installed backend skills. |
  540. | `skill-info <id>` | Show detailed skill metadata. |
  541. | `skill-install <path>` | Install a skill from a directory containing `SKILL.md`. Supports `--overwrite`. |
  542. | `skill-uninstall <id>` | Remove a skill by ID. |
  543. | `skill-reload <id>` | Reload a skill from its source directory. |
  544. #### Progressive experience memory
  545. These commands operate on Browser4's learned experience store.
  546. | Command | Description |
  547. |---|---|
  548. | `experience save <url> <trace>` | Save a task execution trace. Supports `--outcome`, `--intent`, `--task-type` (canonical types including `publish_post`), and `--facts <inline JSON \| @file.json>` — merges retrospective knowledge (`selectors` / `interaction_hints` / `known_blockers` / `anti_patterns`, camelCase or snake_case keys) into the (domain, intent) facts entry; the merge is refused when that entry is VERIFIED (immutable). |
  549. | `experience query <url>` | Query known selectors, blockers, and hints for a URL/domain. Supports `--intent`. |
  550. | `experience list` | List stored experience entries. Supports `--filter`, `--intent-filter`, `--page`, `--page-size`. |
  551. | `experience deep-learn <url> <intent>` | Re-derive the (domain, intent) knowledge entry from stored traces and promote it (no page access). Supports `--force`. |
  552. #### Plugins
  553. Plugins are server-side JARs that extend Browser4. A development runtime bundle
  554. ships the first-party plugins the checkout builds — `browser4-swarm`,
  555. `browser4-images`, `browser4-markdown`, `browser4-media` and `browser4-seo`
  556. (SEO is opt-in: enable it with `-Dbrowser4.plugins.enable=browser4-seo`).
  557. `browser4-{captcha,pptx,profile-import,summary-demo}` are installed on demand:
  558. ```bash
  559. browser4-cli plugin install "browser4-plugins/browser4-pptx/target/browser4-pptx-$(cat VERSION).jar"
  560. browser4-cli stop # the next command restarts the dev backend
  561. ```
  562. Plugin tool names are the snake_case form of `domain.method`
  563. (`image.detectImages` → `image_detect_images`) and are enumerated by
  564. `browser4-cli tool list` (or `GET /mcp/tools`); `plugin list` lists installed plugin
  565. JARs, not tools.
  566. | Command | Description |
  567. |---|---|
  568. | `plugin list` | List installed plugins. |
  569. | `plugin info <name>` | Show plugin details. |
  570. | `plugin install <file>` | Install a plugin from a local JAR file. Supports `--replace`. |
  571. | `plugin remove <name>` | Remove a plugin. Supports `-y`, `--yes`. |
  572. | `tool list [--filter <substr>]` | List every MCP tool name the backend advertises (plugin tools included); `tool call <name> --json '{…}'` invokes one. |
  573. #### Removed commands
  574. | Command | Replacement |
  575. |---|---|
  576. | `act <description>` | Removed in 4.16: the server-side `/api/act` one-shot text→tool-call translator (which reported a failed tool call as success) is gone. Use `agent run "<task>" --wait` — the CLI tool loop is the only agent engine. |
  577. ### Timeout environment variables
  578. | Variable | Default | Used for |
  579. |---|---:|---|
  580. | `BROWSER4_CLI_HTTP_TIMEOUT_SECS` | `30` | most commands |
  581. | `BROWSER4_CLI_INPUT_TIMEOUT_SECS` | `90` | `type`, `fill`, and other slower input workflows |
  582. | `BROWSER4_CLI_NAVIGATION_TIMEOUT_SECS` | `120` | `goto`, `reload`, `go-back`, `go-forward` |
  583. ```bash
  584. export BROWSER4_CLI_INPUT_TIMEOUT_SECS=180
  585. export BROWSER4_CLI_NAVIGATION_TIMEOUT_SECS=300
  586. ```
  587. ### State persistence
  588. CLI state lives under `~/.browser4` unless overridden.
  589. - default session: `~/.browser4/cli-state.json`
  590. - named sessions: `~/.browser4/sessions/<name>.json`
  591. - loops: `~/.browser4/loops/<name>.json`
  592. The runtime bundle is stored separately in a platform-conventional application-data directory, so clearing session state does not force a re-download of Browser4 itself.
  593. ---
  594. ## 🚀 Build from Source
  595. **Prerequisites:** Git, JDK 25+ (Eclipse Temurin), Chrome/Chromium, and PowerShell 7 (Linux/macOS only). For the full prerequisites table, platform-specific tools, and Chrome auto-detection paths, see [Build from Source](docs/build-from-source.md).
  596. 1. **Clone the repository**
  597. ```shell
  598. git clone https://github.com/platonai/Browser4.git
  599. cd Browser4
  600. ```
  601. 2. **Configure your LLM API key**
  602. > Edit [application.properties](application.properties) and add your API key, or set environment variables. See [LLM Configuration](#llm-configuration) for supported providers and variable names.
  603. 3. **Build the project**
  604. ```shell
  605. ./mvnw -DskipTests
  606. ```
  607. 4. **Build and run the CLI (from source)**
  608. ```shell
  609. # Build the Rust CLI (requires Rust toolchain)
  610. cd cli/browser4-cli && cargo build --release
  611. # Or run directly without installing:
  612. cargo run --manifest-path cli/browser4-cli/Cargo.toml -- --help
  613. # Add --quiet to suppress Cargo build-status output:
  614. cargo run --quiet --manifest-path cli/browser4-cli/Cargo.toml -- <command>
  615. # Or install globally:
  616. cd cli/browser4-cli && cargo install --path .
  617. ```
  618. > On Windows, prefix the command with `chcp 65001 >nul &&` for proper UTF-8 output.
  619. > See [Build from Source](docs/build-from-source.md) for full platform-specific instructions.
  620. **Dev-mode wrappers (no install needed):** The repo root provides shell wrappers
  621. that auto-build from source. Use `./b4w.ps1 <command>` (PowerShell),
  622. `./b4w.sh <command>` (Git Bash / Linux / macOS), or `./b4w.bat <command>`
  623. (CMD) — all accept the same arguments as the installed `browser4-cli` binary.
  624. Dev mode only ever serves the checked-out code: a local runtime bundle built
  625. from a **different project version** makes the command refuse to start (naming
  626. the reason, the bundle's versions and build time, and the rebuild command)
  627. rather than silently testing an outdated backend; a checkout whose sources
  628. merely look newer than the bundle jars is rebuilt before the server starts —
  629. see
  630. [CLI install & upgrade](docs/cli-install-upgrade.md#dev-mode-the-backend-must-match-the-checkout).
  631. ---
  632. 🎬 YouTube:
  633. [![Watch the video](https://img.youtube.com/vi/_BcryqWzVMI/0.jpg)](https://www.youtube.com/watch?v=_BcryqWzVMI)
  634. 📺 Bilibili:
  635. [https://www.bilibili.com/video/BV1kM2rYrEFC](https://www.bilibili.com/video/BV1kM2rYrEFC)
  636. ---
  637. ## Architecture
  638. ```
  639. browser4-cli (Rust) ──MCP over HTTP──▶ browser4-rest (Kotlin/Spring) ──▶ PulsarWebDriver (Kotlin/CDP)
  640. ```
  641. - **CLI** (`cli/browser4-cli`) — native Rust binary, talks to the backend via MCP tool calls
  642. - **Backend** (`browser4-rest`) — Spring Boot server, dispatches MCP tools to browser drivers
  643. - **Browser driver** (`browser4-core/browser4-browser`) — wraps Chrome DevTools Protocol
  644. - **Agent tools** (`browser4-agentic`) — maps MCP tool names to browser automation methods
  645. - **Programming kernel** (`browser4-coding`) — dependency-light agent toolkit (sandboxed shell/filesystem, scaffolding, validation, self-development tools) — see [below](#-programming-agent-kernel-browser4-coding)
  646. ## 📦 Modules Overview
  647. | Module | Description |
  648. |---|----------------------------------------------------------------------|
  649. | `cli/browser4-cli` | Rust CLI — fast, native binary for browser automation |
  650. | `skills/browser4-cli` | AI agent skill definitions (SKILL.md) |
  651. | `browser4-core` | Core engine: sessions, scheduling, DOM, browser control |
  652. | `browser4-dependencies` | BOM and dependency version alignment |
  653. | `browser4-tools` | Operational tools and launch helpers |
  654. | `browser4-agentic` | AI agents, MCP integration, skill registration |
  655. | `browser4-coding` | Programming-agent kernel — sandboxed shell/fs, artifact scaffolding & validation, self-development tools (50+ `coding.*` tools) |
  656. | `browser4-agent-tools` | High-level agent tools: scraping, crawling, stateful page interaction |
  657. | `browser4-rest` | Spring Boot REST layer & command endpoints |
  658. | `browser4-apps/browser4-standalone` | Product packaging — unified launcher (`target/Browser4.jar`) |
  659. | `examples/browser4-examples` | Runnable examples and demos |
  660. | `browser4-tests` | E2E, integration, and scenario test suites |
  661. | `cdp-protocol` | Chrome DevTools Protocol JSON definitions |
  662. | `coworker/` | Builtin AI coworker |
  663. ---
  664. ## 🧩 Programming-Agent Kernel (browser4-coding)
  665. `browser4-coding` is the dependency-light programming kernel that lets an AI agent create Browser4 artifacts **and** develop Browser4 itself. It is independent of `browser4-agentic` and `pulsar-common` (only SLF4J + Jackson + coroutines), so it can be reused by non-agent hosts. Heavy backends (LSP servers, kotlin-compiler-embeddable) are probed at runtime and never downloaded by default.
  666. The `coding` domain exposes **50+ tools** in four groups:
  667. | Group | Count | Highlights |
  668. |---|---|---|
  669. | Shell & filesystem | 32 | sandboxed `coding.shell` (command whitelist) + `runCode` snippet execution, snapshot-based edit primitives with `revert`, `diff` (Myers/Patience), repo-governance protection (`coding.protect`) |
  670. | Artifact creation & validation | 5 | `scaffold` (plugin/skill/js/script), `scaffoldToDir`, `scaffoldFlow` (multi-file dev-flow), `scaffoldFromExample` (anti-staleness live templates, directory mode + stem-derived renames), `validate` (incl. `repo-consistency`) |
  671. | Self-development | 13 | `mvnBuild` (structured diagnostics), `ktSymbols`/`ktReferences`/`ktInheritance`/`classInfo` (zero-dep Kotlin analysis), `impact` + `moduleGraph` (live pom graph), `devTask` + `resumeDevTask` (AGENTS.md flow + execution), `verify` (deterministic gate verdict), `trapCheck` (CDP pitfalls), `tokenStats`/`estimateTokens` (context budget) |
  672. | LSP | 4 | on-demand `diagnostics`/`symbols`/`references`/`lspServers` for ts/js/py/rs (degrades gracefully when a server is missing) |
  673. **Generic vs project-specific**: the kernel is layered by *mechanism vs data* — diff, sandbox, LSP client, Kotlin analysis, Maven passthrough and the pom-graph scanner are generic and portable; the scaffolds, validators, `ModuleMap`, `CdpTrapCheck` and the governance defaults encode Browser4 conventions and are the layer to rewrite when reusing the kernel elsewhere.
  674. - Full tool reference & workflows: `skills/browser4-coding/SKILL.md`
  675. - Developing Browser4 itself: `skills/browser4-dev/SKILL.md`
  676. - Four-artifact comparison examples (real vs scaffold output): `docs-dev/copilot/examples/`
  677. - Evaluation summary (P1–P7): `docs-dev/copilot/browser4-programming-support-eval.md`
  678. ---
  679. ## 🧪 Test Fixture Server (MockSite)
  680. Browser4 includes a lightweight **MockSite** server that serves static HTML pages for testing and demos. Start it from the repository root:
  681. **Windows (pwsh — PowerShell 7+):** `./bin/test.ps1 mock-site -Dmock.site.port=18080`
  682. **Linux/macOS:** `./bin/test.sh mock-site -Dmock.site.port=18080`
  683. > **First run on a cold Maven cache takes 10–15 minutes** (observed ~13 min) and prints nothing
  684. > while it installs `browser4-dependencies`, then `browser4-rest` and its ~25 modules — the first
  685. > `[PASS]` banner only appears after each phase finishes. Once the artifacts are cached, startup is
  686. > fast. Don't kill the process and start a second concurrent Maven build.
  687. Key demo pages are served at `http://localhost:18080/generated/`. For the full page listing, environment variables, Python fallback, and Maven-based launch, see [MockSite](docs/mocksite.md). For the test taxonomy and tagging system, see [Test Taxonomy](docs/TESTING.md).
  688. ---
  689. ## 🤝 Support & Community
  690. Join our community for support, feedback, and collaboration!
  691. - **GitHub Discussions**: Engage with developers and users.
  692. - **Issue Tracker**: Report bugs or request features.
  693. - **Social Media**: Follow us for updates and news.
  694. We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for details.
  695. ### Contact Us
  696. - 💬 WeChat: galaxyeye
  697. - 🌐 Weibo: [galaxyeye](https://weibo.com/galaxyeye)
  698. - 📧 Email: galaxyeye@live.cn, ivincent.zhang@gmail.com
  699. - 🐦 Twitter: galaxyeye8
  700. <div style="display: flex;">
  701. <img src="docs/images/wechat-author.png" width="300" height="365" alt="WeChat QR Code" />
  702. </div>
  703. ---
  704. ## 📜 Documentation
  705. Comprehensive documentation is available in the `docs/` directory and on our [GitHub Pages site](https://platonai.github.io/browser4/).
  706. ---
  707. ## 🔧 Proxy Configuration - Unblock Website Access
  708. <details>
  709. Set the environment variable `PROXY_ROTATION_URL` to the rotation URL provided by your proxy service provider:
  710. ```shell
  711. export PROXY_ROTATION_URL=https://your-proxy-provider.com/rotation-endpoint
  712. ```
  713. Each time you access this rotation URL, it should return a response containing one or more fresh proxy IPs.
  714. If you need this type of URL, please contact your proxy service provider.
  715. For a single fixed proxy (`--proxy-server`), proxy authentication, the format the rotation
  716. endpoint must return, and how to verify the egress IP, see **[docs/ip-proxy.md](docs/ip-proxy.md)**.
  717. Note that `browser4-cli --proxy` is a *download* proxy — it does not route page traffic.
  718. </details>
  719. ---
  720. ## License
  721. Apache 2.0 License. See [LICENSE](LICENSE) for details.
  722. ## Links
  723. * [omdsh-dev/dsh-data-agent](https://github.com/omdsh-dev/dsh-data-agent) - DSH Data Agent · Analyze data through conversation
  724. * [ccch1mneyyy/dsh-TUI](https://github.com/ccch1mneyyy/dsh-TUI) - DSH TUI · Text-based User Interface

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.