AunySillyMelean-browser-use
Documentation

From docs/install.md · e31dc91 · Built 2026-11-17

Commands

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 flagEffect
--claude-dir DIRUse the named Claude config directory.
--projectInstall into the current project's .claude.
--no-hooksCopy the hooks and print registration to paste by hand; skip the settings merge.
--with-readerAlso copy the optional reader and SearXNG files.
--dryPrint the real plan while leaving files unchanged.
--yesProceed after the plan without an interactive confirmation.
--helpPrint command usage.
--versionPrint the package version.

Files and settings

Here <cfg> means the selected config directory.

DestinationContents
<cfg>/skills/lean-browser-use/Method entrypoint and focused references.
<cfg>/agents/aun-browser-runner.mdBrowser 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.jsonInstall-time hashes, created directories, and settings changes.
<cfg>/settings.jsonMerged hook registrations, preserving other settings and hooks.
<cfg>/settings.json.lean-browser-use.bakBackup 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.

ExitMeaning
0Success.
1A check failed.
2Usage error or refused target; a missing uninstall manifest names its path.
3Uninstall 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

FieldMeaning
GroupMain session or runner.
StepsDistinct assistant messages using browser tools.
MedianTypical input-context tokens per step.
p90Input-context tokens near the upper end of the observed steps.
TotalSum of input-context tokens across browser steps.
reread_shareCache-read plus cache-creation tokens divided by total input-context tokens.
ratioMain median divided by runner median, reported when each has at least 3 steps.
skipped_linesTranscript 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.

ExitMeaning
0Success.
2Usage error, refused target, or missing compile command when needed.
10Fetch failed.
11Compile failed.
12Extraction 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

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

  1. Start a fresh Claude Code session and ask it to use the lean-browser-use skill.
  2. Run npx lean-browser-use doctor to check files, hooks, and available companion tools.
  3. 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-heal
reader/reader ls

Python 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.sh
searxng/searx 'public documentation' --json

command

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 --json

command

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 --json

commands

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 --dry
npx lean-browser-use uninstall --dry