Documentation
From docs/install.md · e31dc91 · Built 2026-11-17
Use Node 20 or newer. From a terminal:
npx lean-browser-use
The installer prints its plan, then asks Proceed? [Y/n] on a terminal. Non-interactive runs proceed automatically; --yes also skips the prompt. Undo the install with npx lean-browser-use --uninstall.
Choose the target
The config directory is selected by --claude-dir DIR, then $CLAUDE_CONFIG_DIR, then ~/.claude. --project targets ./.claude in the current project. Use one explicit target choice per invocation.
npx lean-browser-use install --project
npx lean-browser-use install --claude-dir ./sandbox-config --dry
npx lean-browser-use install --with-reader --yes
| Install flag | Effect |
|---|---|
--claude-dir DIR | Use the named Claude config directory. |
--project | Install into the current project's .claude. |
--no-hooks | Copy the hooks and print registration to paste by hand; skip the settings merge. |
--with-reader | Also copy the optional reader and SearXNG files. |
--dry | Print the real plan while leaving files unchanged. |
--yes | Proceed after the plan without an interactive confirmation. |
--help | Print command usage. |
--version | Print the package version. |
Files and settings
Here <cfg> means the selected config directory.
| Destination | Contents |
|---|---|
<cfg>/skills/lean-browser-use/ | Method entrypoint and focused references. |
<cfg>/agents/aun-browser-runner.md | Browser subagent definition. |
<cfg>/lean-browser-use/hooks/ | Guard and cleanup scripts and registration source. |
<cfg>/lean-browser-use/briefs/ | Browser and cheap-helper packet templates. |
<cfg>/lean-browser-use/reader/ | Optional compile-once reader and specs. |
<cfg>/lean-browser-use/searxng/ | Optional search script and container configuration. |
<cfg>/lean-browser-use/manifest.json | Install-time hashes, created directories, and settings changes. |
<cfg>/settings.json | Merged hook registrations, preserving other settings and hooks. |
<cfg>/settings.json.lean-browser-use.bak | Backup of existing settings, written only if the backup is absent. |
Repeated installs avoid duplicate registrations. The installer substitutes real hook paths into the registration template. It never installs third-party tools, runs a vendor login, contacts the network, or prints secrets. Optional tool installation belongs to the user; see reader and search.
Activate and inspect
Start a fresh Claude Code session so it can discover the installed skill and agent. Ask it to use lean-browser-use for a browser task. Pick your Chrome profile by name when logged-in work needs it. A Chrome connection and tool permissions come from your own Claude Code setup.
npx lean-browser-use doctor
npx lean-browser-use doctor --claude-dir ./sandbox-config --json
Doctor checks installed file hashes, registered hook paths, executable shims, synthetic hook responses, and leased processes still running (see cleanup). Edited files are reported. Its capability table explains what Python, crwl, Docker, Claude Code, and local transcripts enable; missing optional tools are capabilities to add, not installation errors. JSON output has ok and checks, each with id, status, and detail. Hook behavior on your Claude Code version is confirmed by npx lean-browser-use doctor.
Measure and remove
npx lean-browser-use measure --dir ./transcripts --since 2026-10-25 --json
npx lean-browser-use uninstall --claude-dir ./sandbox-config --dry
npx lean-browser-use uninstall --claude-dir ./sandbox-config
measure defaults to the selected config directory's projects folder; --dir overrides it, --since YYYY-MM-DD filters timestamps, and --json returns structured results. See the meter.
Uninstall compares each file with its install-time hash. It removes matching files, preserves and lists edited files, removes only its hook entries from settings, and removes only empty directories this install created. It refuses traversal, absolute manifest paths, and symlink entries. The manifest is removed last. Follow printed manual steps for registration pasted by hand. For a project install, point uninstall and doctor at --claude-dir ./.claude.
| Exit | Meaning |
|---|---|
| 0 | Success. |
| 1 | A check failed. |
| 2 | Usage error or refused target; a missing uninstall manifest names its path. |
| 3 | Uninstall preserved edited files. |
From docs/measure.md
Measure browser context
Run the meter on your own Claude Code transcripts:
npx lean-browser-use measure
npx lean-browser-use measure --dir ./transcripts --since 2026-10-25 --json
The default directory is the selected Claude config directory's projects folder. The meter walks JSONL files recursively, including subagent transcripts. --dir selects another tree, --since YYYY-MM-DD filters line timestamps, and --json returns the same measurements in structured form.
What counts
A browser step is a unique assistant message.id with a browser tool_use block. Recognized prefixes are mcp__claude-in-chrome__, mcp__Claude_Browser__, mcp__Control_Chrome__, mcp__playwright__, and mcp__chrome-devtools__. A batch counts once, even when it contains many browser actions.
For each step the meter adds input_tokens, cache_creation_input_tokens, and cache_read_input_tokens. An assistant message can appear on several transcript lines. The meter keeps the largest total for that id as final usage, preserving the browser-step classification across its lines.
A line belongs to the runner group when isSidechain is true or its file path contains /subagents/. Other lines belong to main. Unreadable lines are skipped and counted in skipped_lines.
Read the result
| Field | Meaning |
|---|---|
| Group | Main session or runner. |
| Steps | Distinct assistant messages using browser tools. |
| Median | Typical input-context tokens per step. |
| p90 | Input-context tokens near the upper end of the observed steps. |
| Total | Sum of input-context tokens across browser steps. |
reread_share | Cache-read plus cache-creation tokens divided by total input-context tokens. |
ratio | Main median divided by runner median, reported when each has at least 3 steps. |
skipped_lines | Transcript lines the meter could not read. |
The default output is a short table for main and runner, followed by summary information. With an empty transcript tree it prints no browser steps found and exits 0. Generate a real example from the synthetic fixtures with:
node bin/lean-browser-use.mjs measure --dir test/fixtures/transcripts
This is a context-volume comparison, not a currency bill. Cached tokens can have different pricing. Different jobs, model behavior, and transcript coverage also affect the result. Compare similar work and keep the counts beside the ratio. The meter prints counts and token values, never message text or tool inputs, and makes no network calls.
Package measurements
proof/results.json measures the package: tarball size, file count, dependencies, passing tests, guard timings, install time, and covered guard rules. Reproduce it with npm run proof. These generated rows give their command, measurement date, and expiry. An expired row warns during npm run check; expiry does not block checks or a release. The twenty paired benchmark rows are copied or derived from the saved run in proof/benchmark.json, carry no expiry, and are never re-measured by the proof script. Read the benchmark for conditions, exact counts, and reproduction steps. They give a ballpark for that run; use the meter on your own transcripts to compare your work.
From docs/reader.md
Compile once, run as code
The page reader extracts repeatable fields from public pages. A model writes the extraction spec during compilation. Successful later runs fetch and extract with code, without a model call. Validation can trigger one self-heal when a page changes.
Copy the companion with npx lean-browser-use --with-reader. The examples below run from a repository checkout; installed copies live under the chosen config directory's lean-browser-use/reader/.
Prepare the reader
Python 3 runs the reader. Crawl4AI supplies CSS extraction and the browser fetch fallback. The user installs it separately with pip install crawl4ai in their chosen Python environment. See the reader guide for interpreter discovery and offline tests.
Choose a command that reads a prompt on stdin and prints schema JSON on stdout. For example:
export READER_COMPILE_CMD='claude -p'
reader/reader compile packages --url 'https://www.npmjs.com/package/{name}' \
--param name=react --want 'Name, version, license, repository URL'
reader/reader run packages --param name=zod
reader/reader ls
The compile command is parsed with shlex and run without a shell. It can be an agent CLI, an API client script, or a local model command. The reader supplies the prompt on stdin. An unset READER_COMPILE_CMD makes compilation or self-heal exit 2 with setup guidance. Running an already compiled valid spec needs neither the variable nor a model.
Verify and reuse
Give compile an observed --example row when possible. Verify the resulting values independently before reusing the spec. The bundled pricing spec and package spec include their provenance; saved fixtures demonstrate extraction, while current public values require a fresh read.
run returns rows and fetch metadata. ls shows available specs and their state. Use --no-heal to keep a run to code-only extraction even when validation fails. A successful heal is stored in runtime state, preserving shipped specs. READER_SPECS_DIR selects specs and READER_STATE_DIR selects state.
Only public HTTP and HTTPS pages are eligible. Private targets and authenticated browsing belong outside this reader. Use the user-selected browser route for logged-in work.
| Exit | Meaning |
|---|---|
| 0 | Success. |
| 2 | Usage error, refused target, or missing compile command when needed. |
| 10 | Fetch failed. |
| 11 | Compile failed. |
| 12 | Extraction failed after self-heal or with --no-heal. |
Preserve the error and fall through to an eligible route from the route table. Avoid repeating an unchanged failed fetch.
From docs/search.md
Find links, then read pages
Use search when the URLs are unknown. The optional searx script returns links from a SearXNG instance so a helper or runner can read the selected pages in a packet. SearXNG is a self-hosted search service; hosting and upstream availability depend on your environment.
Install the companion files with npx lean-browser-use --with-reader. Docker is a separate user-provided capability. From a repository checkout:
bash searxng/deploy.sh
searxng/searx 'browser automation documentation'
The default endpoint is http://127.0.0.1:8888. SEARXNG_URL selects another instance. The compose configuration binds to loopback; expose it to a private network only as a deliberate deployment choice. The deployment script keeps its generated secret in ${XDG_CONFIG_HOME:-$HOME/.config}/lean-browser-use/searxng-secret.env with restricted permissions. Keep that file out of briefs and reports.
Search finds candidate URLs. A search snippet is a discovery aid; read the selected page and save the requested fields as evidence. Batch independent public reads within a helper session or a subagent-runner session. See the helper packet.
This repository ships configuration and a container reference. SearXNG itself is AGPL-3.0 and is not bundled here. See the companion guide and credits.
From README.md
After you install
- Start a fresh Claude Code session and ask it to use the
lean-browser-useskill. - Run
npx lean-browser-use doctorto check files, hooks, and available companion tools. - Try: "Use lean-browser-use to read the title from https://example.com, save the evidence, verify it, and report cleanup."
For logged-in work, choose your Chrome profile by name when asked. The runner receives that browser's deviceId (the id Claude in Chrome gives each connected browser) and a named tab. The subagent runner runs the same packets on its own; a cheap helper is another option. See installation and activation for target directories and optional companions.
Measure your own saving
npx lean-browser-use measure
The table compares main and runner groups: steps, median, p90, total input-context tokens, and reread share. The summary includes a main-to-runner median ratio when enough steps are present and a count of skipped lines. It measures context volume and reports counts without exposing message text or tool inputs. See how the meter counts to choose a transcript directory, filter dates, or request JSON.
Uninstall
npx lean-browser-use uninstall
Preview with npx lean-browser-use uninstall --dry.
Removal uses install-time hashes: edited files stay and are listed, while owned hook registrations are removed from settings.
Use --claude-dir to target the same directory as the install; follow printed manual steps for hooks pasted by hand.
Python companion
Optional page reader: web scraping
Compiles a public HTTP or HTTPS page into an extraction spec through a user-selected stdin compiler command. Later valid runs fetch and extract with code, without a model call; validation can trigger one self-heal, stored separately from shipped specs. Lists saved specs and supports a code-only run with --no-heal. Private targets and authenticated browsing use the selected browser route.
reader/reader compile packages --url 'https://www.npmjs.com/package/{name}' --param name=react --want 'Name, version, license, repository URL'reader/reader run packages --param name=zod --no-healreader/reader lsPython companion
Optional search companion: searxng
Queries a user-provided SearXNG instance and prints result titles, URLs and source engines, or JSON. Query flags select engines, categories, time range, language, page, result bound and timeout. The companion includes loopback container configuration and a setup script; the user supplies Docker and hosting. Search results identify pages to read and verify.
bash searxng/deploy.shsearxng/searx 'public documentation' --jsoncommand
Token meter: transcript
Walks local JSONL transcripts and counts distinct assistant message ids using supported browser tools. Keeps the largest input total for each id, including input, cache creation and cache read, and separates main from runner steps. Reports steps, median, p90, total context, reread share, eligible median ratio and skipped lines. Date and directory filters and JSON output leave message text and tool inputs private.
npx lean-browser-use measure --dir ./transcripts --since 2026-10-25 --jsoncommand
Doctor: Claude Code
Checks Node, the install manifest, file hashes, registered hook paths and executable shims. Runs synthetic malformed-payload checks against the installed guards. Reports optional Python, page extraction, Docker, agent and local transcript capabilities, with JSON available. Missing optional tools are capabilities to add; a failed installation check produces a failing exit.
npx lean-browser-use doctor --jsoncommands
Installer and uninstall: agent-skill
Prints a plan, copies the method, runner, briefs and guards into the selected config directory, merges registrations and records install-time hashes. Optional companions are copied only when requested. Dry mode leaves files unchanged. Uninstall rechecks owned file hashes before removal, preserves edited files and the settings backup, removes owned registrations and empty created directories, and removes the manifest last.
npx lean-browser-use install --drynpx lean-browser-use uninstall --dry