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

From [README.md](https://github.com/aunysillyme/lean-browser-use/blob/e31dc9131228621ebcb09d98e827d6bb8692e964/README.md) · [e31dc91](https://github.com/aunysillyme/lean-browser-use/tree/e31dc9131228621ebcb09d98e827d6bb8692e964) · Built 2026-11-17

# Overview

Cut browser use cost 3% to 25% (about 14% across two runs) in Claude Code: run page work in a fresh runner, send it in bulk, and see your own saving. 

For Claude Code users who run browser work in their sessions.
You get a skill, a runner agent (a fresh subagent that does the browser work), three hooks and a token meter (the `measure` command that counts tokens per step).
Next: start a fresh Claude Code session and ask it to use the `lean-browser-use` skill.

Bulk means many steps and reads sent in one call; a packet is the brief that carries those steps.
A guard is a small hook that blocks a wasteful or unsafe step.



```
npx lean-browser-use
```


`npx` runs the package without a permanent install.

Undo it with `npx lean-browser-use --uninstall`. Preview the install with `npx lean-browser-use --dry`.

## What it does

Part |  What you get | 

Method skill |  A route table for public pages, repeated reads, forms, and logged-in work. | 

Subagent runner |  Browser execution in a fresh context, with named fields and an evidence handoff. | 

Packet briefs |  Paste-ready scope, code, permissions, stop conditions, and cleanup checks. | 

Pick guard |  A session-bound browser choice before page actions. | 

Retry guard |  A stop on repeated waits, reloads, and fruitless reads. | 

Batch nudge |  A reminder to combine predictable actions. | 

Optional page reader |  Compile extraction once, then run it as code. | 

Optional search companion |  Find links through your SearXNG instance (a self-hosted search engine), then read selected pages. | 

Token meter |  Compare main and runner browser context in your local transcripts. | 

Installer and doctor |  Managed files, preserved settings, health checks, and hash-aware removal. | 

The installer has 0 runtime dependencies. [Package measurements](https://lean-browser-use.aunysillyme.dev/docs/proof/) include the reproduction commands and measurement dates.
The installer manages the package files and hooks in your Claude config, works offline, and leaves optional tool installation to you.

## 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.

## Cleanup: nothing keeps running

Follow the [cleanup steps](https://lean-browser-use.aunysillyme.dev/docs/guarantees/#cleanup-steps): the runner saves evidence, closes run-owned tabs and panes, stops its shell tasks, removes scratch, checks what remains and runs leased-process cleanup. Main then closes its remaining job tabs, stops its background tasks and servers, runs `npx lean-browser-use doctor`, verifies the runner's evidence and removes the handoff scratch.

The stop gate blocks once to request closure of run-owned tabs; use `npx lean-browser-use keep --reason "<why>"` to hold a tab for the user and say what stays open and why.

Every process the runner starts goes through `npx lean-browser-use spawn`, which records a lease. The runner's last command is:



```
npx --yes lean-browser-use cleanup --apply
```


It ends only leased automation processes, children first, with SIGTERM and a 3 second wait before SIGKILL for the same process. Registered hooks repeat the cleanup when a runner stops, a turn ends or the session ends, and `doctor` reports any leftover.
Your normal Chrome windows, your profile and any process without a lease are never touched. Add `--apply` yourself only after the dry run lists what you expect. See [cleanup](https://lean-browser-use.aunysillyme.dev/docs/guarantees/).

## Part of a set

Package |  What it gives | 

[agent-personalizer](https://github.com/aunysillyme/agent-personalizer) |  AI custom instructions from approved entries: a profile and rules for Claude Code, Codex, Cursor, Gemini CLI and ChatGPT, kept in sync from one source. | 

[model-orchestrator](https://github.com/aunysillyme/model-orchestrator) |  Model router for AI coding agents: routes routine work to cheaper models with routing rules, 8 subagents, hooks and a CLI runner | 

[repo-build-skill](https://github.com/aunysillyme/repo-build-skill) |  Skill pack that teaches your AI to build, release and launch a GitHub repo: stack pick, README, AGENTS.md, llms.txt, repo SEO and AEO, trusted publishing. | 

[website-build-skill](https://github.com/aunysillyme/website-build-skill) |  A skill pack that turns your AI into an expert website builder: current research, design, code, accessibility, speed, SEO and security, alone or as a team. | 

lean-browser-use  |  Cut Claude Code browser use cost 3% to 25% (about 14% in 2 runs): fresh runner subagent, bulk reads, 3 guards and a token meter. One npx command. | 

[lean-computer-use](https://github.com/aunysillyme/lean-computer-use) |  Background Mac computer control for AI agents: desk tools, a fresh runner subagent, retry guards and a transcript token meter, installed with one command | 

[decompose](https://github.com/aunysillyme-dev/aunx-decompose) |  Task planner and wave checker for AI coding agents: splits prompts into checkable units and parallel waves, rejecting cycles and overlapping writes | 

[aunx-skills](https://github.com/aunysillyme-dev/aunx-skills) |  Ten standalone agent skills for Claude Code, Codex, Cursor and Gemini CLI: full output keeper, number guard, docs fetch ladder, rename sweep and more | 

## 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.

## Common questions

### How do I install browser-use tools for Claude Code?

Run `npx lean-browser-use`, then start a fresh Claude Code session and invoke the skill.
The installer copies the method, runner, briefs, and guards into your selected Claude config directory.

### Can a subagent run browser work on its own?

Yes: the subagent runner handles the full browser route with the same packets.
Run `npx lean-browser-use doctor` to inspect the tools your machine provides, then follow the [route table](https://lean-browser-use.aunysillyme.dev/docs/guides/).

### How do I install into just this project?

Run `npx lean-browser-use --project` to target the current project's `.claude` directory.
Check it with `npx lean-browser-use doctor --claude-dir ./.claude`.

### How do I add the page reader and search?

Run `npx lean-browser-use --with-reader` to copy both companions.
The reader and search companions use tools you install separately; see their setup guides: [reader](https://lean-browser-use.aunysillyme.dev/docs/guides/) and [search](https://lean-browser-use.aunysillyme.dev/docs/guides/).

### How do I check browser hooks after installing?

Run `npx lean-browser-use doctor`; hook behavior on your Claude Code version is confirmed there.
For payload examples and stop rules, read [the guards guide](https://lean-browser-use.aunysillyme.dev/docs/guarantees/).

## 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.

## Read next

[Install and manage](https://lean-browser-use.aunysillyme.dev/docs/commands/): every flag, target path, health check, and removal behavior.

[How the method works](https://lean-browser-use.aunysillyme.dev/docs/how-it-works/): prepare, route, batch, verify, and clean up.

[Guards](https://lean-browser-use.aunysillyme.dev/docs/guarantees/): selection, retry bounds, batching, and fail-open checks.

[Cleanup](https://lean-browser-use.aunysillyme.dev/docs/guarantees/): leases, the cleanup command, hooks, and what is never touched.

[Page reader](https://lean-browser-use.aunysillyme.dev/docs/guides/): compile a public extraction and reuse it as code.

[Search](https://lean-browser-use.aunysillyme.dev/docs/guides/): find URLs with the optional SearXNG companion.

[Benchmark](https://lean-browser-use.aunysillyme.dev/docs/proof/): the paired run, exact counts, and how far to trust the ballpark.

[Measure](https://lean-browser-use.aunysillyme.dev/docs/commands/): count local browser context and read the comparison.

[Provenance](https://lean-browser-use.aunysillyme.dev/docs/guarantees/): public names, upstream ideas, and evidence boundaries.

For agents:  [llms.txt](https://github.com/aunysillyme/lean-browser-use/blob/main/llms.txt) maps the docs; [AGENTS.md](https://github.com/aunysillyme/lean-browser-use/blob/main/AGENTS.md) defines repository work. Use `npx lean-browser-use doctor` for a headless check.

## Contributing

Bring a reproducible browser failure, a tool-family fixture, a reader spec, or a docs fix.
[CONTRIBUTING.md](https://github.com/aunysillyme/lean-browser-use/blob/main/CONTRIBUTING.md) gives the checks and review expectations.

## Credits

[trycua/cua](https://github.com/trycua/cua), MIT: the sibling's background native-app driver.

[Jev research client / typesafe-sdk](https://pypi.org/project/typesafe-sdk/) and [its source](https://github.com/typesafe-ai/typesafe-sdk-python), MIT: index-choice and packet techniques.

[browser-use/jev-ultrafast](https://github.com/browser-use/jev-ultrafast), MIT: packet ideas.

[Crawl4AI](https://github.com/unclecode/crawl4ai), Apache-2.0: reader fetching and text extraction.

[SearXNG](https://github.com/searxng/searxng), AGPL-3.0: the search container referenced by the companion.

[rtk](https://github.com/rtk-ai/rtk), Apache-2.0: shell-output compression techniques.

[fetchapi.co](https://fetchapi.co): the compile-once idea, reimplemented here from scratch; idea credit only.

[Anthropic's Claude in Chrome](https://claude.com/chrome): the logged-in browser integration, under Anthropic's service terms.

[Keep a Changelog](https://keepachangelog.com), MIT, and [Contributor Covenant](https://www.contributor-covenant.org), CC-BY-4.0: repository conventions.

Credits describe each upstream contribution; see [CREDITS.md](https://lean-browser-use.aunysillyme.dev/docs/guarantees/).

## License

[MIT](https://github.com/aunysillyme/lean-browser-use/blob/main/LICENSE). Copyright Auny LLC and contributors.
