Canonical: https://lean-browser-use.aunysillyme.dev/docs/commands/

From [docs/install.md](https://github.com/aunysillyme/lean-browser-use/blob/e31dc9131228621ebcb09d98e827d6bb8692e964/docs/install.md) · [e31dc91](https://github.com/aunysillyme/lean-browser-use/tree/e31dc9131228621ebcb09d98e827d6bb8692e964) · 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 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](https://lean-browser-use.aunysillyme.dev/docs/guides/) and [search](https://lean-browser-use.aunysillyme.dev/docs/guides/).

## 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](https://lean-browser-use.aunysillyme.dev/docs/guarantees/)). 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](https://lean-browser-use.aunysillyme.dev/docs/commands/).

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](https://github.com/aunysillyme/lean-browser-use/blob/main/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](https://lean-browser-use.aunysillyme.dev/docs/proof/) 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](https://github.com/aunysillyme/lean-browser-use/blob/main/proof/benchmark.json), carry no expiry, and are never re-measured by the proof script. Read [the benchmark](https://lean-browser-use.aunysillyme.dev/docs/proof/) 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](https://github.com/aunysillyme/lean-browser-use/blob/main/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](https://github.com/aunysillyme/lean-browser-use/blob/main/reader/README.md) 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](https://github.com/aunysillyme/lean-browser-use/blob/main/reader/specs/claude-pricing.json) and [package spec](https://github.com/aunysillyme/lean-browser-use/blob/main/reader/specs/npm-package.json) 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](https://lean-browser-use.aunysillyme.dev/docs/guides/). Avoid repeating an unchanged failed fetch.

From [docs/search.md](https://github.com/aunysillyme/lean-browser-use/blob/main/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](https://lean-browser-use.aunysillyme.dev/docs/guides/).

This repository ships configuration and a container reference. SearXNG itself is AGPL-3.0 and is not bundled here. See [the companion guide](https://github.com/aunysillyme/lean-browser-use/blob/main/searxng/README.md) and [credits](https://lean-browser-use.aunysillyme.dev/docs/guarantees/).

From [README.md](https://github.com/aunysillyme/lean-browser-use/blob/main/README.md)

## After you install

Start a fresh Claude Code session and ask it to use the `lean-browser-use` skill.

Run `npx lean-browser-use doctor` to check files, hooks, and available companion tools.

Try: "Use lean-browser-use to read the title from [https://example.com](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](https://lean-browser-use.aunysillyme.dev/docs/commands/) 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](https://lean-browser-use.aunysillyme.dev/docs/commands/) 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
```


