The agent then installs the package, registers the skill and connects to your browser itself. The logic is sound: if you already have an agent that can run commands, let it handle the installation.

The Library: Your First Agent

Python 3.11 or newer is required.

The key goes into .env. An important detail here: a single Browser Use key is enough for every provider, though you can bring your own:

The first agent takes a dozen lines:

ChatBrowserUse accepts provider-prefixed model ids - openai/gpt-5.5, anthropic/claude-sonnet-4-6, google/gemini-3-pro - and one key reaches all of them. Separate OpenAI, Anthropic and Google keys are not needed.

Custom tools arrive through a decorator:

How the Agent Looks at a Page

This is the most interesting part, because the approach is not what you would guess.

The project's skill explicitly tells the agent to find elements in the accessibility tree rather than in a screenshot: call Accessibility.getFullAXTree through the Chrome DevTools protocol, filter what you need in Python - there are thousands of nodes - and take the identifier of the node you found. From that identifier comes the element's geometry, from the geometry its centre, and the click happens by coordinates.

The order is spelled out: accessibility node, then the centre of its box, then a click by coordinates, then verification with a separate query. Screenshots stay a last resort for when layout or imagery matters, and raw HTML for when the element is absent from the accessibility tree altogether: canvas, exotic widgets.

Why coordinates rather than selectors is explained in the design constraints: DevTools protocol mouse events pass through iframes, shadow DOM and cross-origin boundaries at the compositor level. What ordinary automation struggles with here works by itself.

The command line, meanwhile, is not a set of subcommands but Python execution with pre-imported helpers:

Also useful there: wait_for_load() after navigation, ensure_real_tab() when the current tab is internal or stale, js(...) for inspection and extraction, and cdp("Domain.method", ...) for direct protocol access.

One rule deserves quoting: on hitting a login wall the agent is told to stop and ask. The exception is an available single sign-on when Chrome is already signed in; passwords, second factors, consents and ambiguous account choices still go to the human.

Local Chrome

The skill works with an already running Chrome over the DevTools protocol, so remote debugging must be enabled in the browser at chrome://inspect/#remote-debugging. If Chrome is not running at all, the harness starts it.

Diagnostics for when the connection will not come up:

macOS has a nuisance of its own: Chrome asks for remote debugging permission in a popup. There is a command for that case, and the skill explicitly forbids polling in a loop - the daemon holds a single connection:

Cloud Browsers: When and Why

The project suggests going to the cloud not always but in two specific cases, and both are honest.

The first is parallel tasks. Local Chrome is one browser, and several tasks will fight over tabs and focus. One cloud browser per task keeps them fully separate.

The second is captchas and blocking. Cloud browsers come with clean managed addresses and stealth settings, so they run into captchas and rate limits less often, while your own address and browser stay out of it.

A named remote daemon is then started and the work goes through it:

And a warning worth learning before rather than after: remote daemons bill until they are stopped or time out. The skill explicitly tells the agent to ask whether to close the browser once the task is done.

Recordings

A fresh install records nothing - that is a separate setting:

The rule for switching recording on is carefully worded: a request to "record", "show" or "make a video" opts that task in, while the sheer volume of work does not. And replaying a finished task for the sake of a nice recording is explicitly forbidden: if the work was not captured, say so.

Agent Parameters and a Discrepancy Worth Knowing

The agent class has more than two dozen parameters. The most noticeable: how many actions the agent may emit per step, how many failures it tolerates before stopping, whether to use vision and thinking, how many seconds a step gets, whether planning and loop detection are on.

There is a trap here that only shows up when you check against the code. The project's documentation and the class signature disagree:

The mismatch is not fatal but it is telling: if you are reasoning from the documentation - working out, say, after how many seconds the agent will definitely stop - check the value in your installed version rather than in the text.

The Numbers the Project Publishes

browser-use handles measurement better than most projects of its kind, but the numbers still need reading carefully.

Its own set of a hundred real browser tasks is published openly as a separate repository - which is already more than almost anyone does. The tasks are hand-picked and verified as achievable.

Separately the README claims first place on an external leaderboard with an 87.4 per cent average across two hundred long-horizon web tasks, ahead of computer-use agents from OpenAI, Anthropic, Google and Microsoft. That is an external leaderboard, and it can be checked by following the link rather than taken on trust.

The line about completing tasks "3-5x faster than other models" in the FAQ, on the other hand, has no method behind it: no task set, no run count, no statement of what it was compared against. That is exactly the difference from the open hundred-task set: one is reproducible, the other is not.

What the Project Admits About Itself

The list is short and to the point.

Chrome eats memory. The README says so plainly and adds that running many agents in parallel can be tricky to manage. That is where the recommendation to use the cloud for production comes from.

The open version does not handle captchas. Better browser fingerprinting and proxies are needed - which is the cloud again.

A browser is not always needed. The skill opens with a section on when not to use it: if public information can be fetched with a plain HTTP request - a page, an API, docs - use curl and leave the browser alone. The browser earns its place when the task needs interaction, the user's logged-in session, JavaScript rendering or a bot-protected page.

Some capabilities are off by default. Domain skills - hints tailored to particular sites - are enabled by an environment variable rather than running on their own.

Telemetry

The library collects anonymised usage data. It is switched off with an environment variable:

Or directly in code before the agent is created:

Mistakes of the First Encounter

Reaching for browser-use where an HTTP request would do. The skill asks you not to: a public page or an API is read with a plain request.

Confusing it with the tools for checking your own work. Chrome DevTools MCP and Playwright MCP exist so the agent can look at what it wrote. browser-use exists so it can work someone else's site. Different jobs, and swapping one for the other costs time.

Running several tasks on one local Chrome. They will fight over tabs and focus; separate cloud browsers exist for parallelism.

Forgetting to stop a cloud browser. It bills while it runs.

Trusting the defaults printed in the documentation. Actions per step, failure count and step timeout differ between the text and the code.

Expecting the agent to sort out a login page by itself. It will stop and ask - by design.

Treating "3-5x faster" as a measurement. There is no method behind that phrase, unlike the open hundred-task set.

Leaving telemetry on without thinking about it. It is on by default and switches off in one line.

To put it in one sentence: browser-use is good exactly where a task has no programmatic interface and a browser is genuinely required - and the first decision to make is whether a browser is required at all.

Sources

This article was checked against the browser-use/browser-use repository (branch main) on 25 August 2026: the README, pyproject.toml, AGENTS.md, the skills/browser-use/SKILL.md skill and the agent source browser_use/agent/service.py. Default values were taken from the code rather than the documentation - they disagree. The project moves very fast, and the command-line interface has changed substantially over recent versions.

• GitHub: browser-use/browser-use
• browser-use documentation
• The open benchmark task set
• The browser-use skill
• Instructions for agents
• The agent source
• Installing the harness
• Browser interaction techniques
• Example: filling in an application
• Example: working with a real Chrome profile