--- url: https://adityasasidhar.github.io/browsercontrol/guide.md description: >- What BrowserControl is, what an agent sees when it uses it, and where to go next. --- # Introduction BrowserControl is a local [MCP](https://modelcontextprotocol.io) server that gives an AI agent a real Chromium browser. Your MCP client starts it, the agent calls its tools, and every tool that changes the page answers with a fresh screenshot of it. ## What the agent sees Each screenshot has a numbered box drawn around every control the agent can use, and the same numbers come back as text: ![A web form with numbered red boxes around its fields and its Submit button](/images/annotated-web-form.webp) ```text Found 17 interactive elements: [1] a - Return to index [2] button[submit] - Submit [3] input[text] [4] input[password] [5] input[text] (disabled) ... ``` To use a control, the agent passes its number: `type_text(3, "hello")`, then `click(2)`. It never writes a CSS selector, and it never guesses at coordinates. This way of labeling a screenshot is called [Set of Marks](/concepts/set-of-marks). ## The one rule Numbers belong to the screenshot they came from. Every action returns a new screenshot with a new map, and a control that was Submit a moment ago may be number 9 now. An agent should read the newest map before every action that takes an ID. If an ID has gone out of date, BrowserControl doesn't guess. It refuses to act and returns a fresh screenshot to pick again from. ## What else it does The numbered screenshot is the core, but BrowserControl is a whole browser: ## Good to know * **It runs on your machine.** The browser, its profile, and everything it captures stay local. BrowserControl calls no model and needs no API key. * **Logins persist.** The default browser profile lives in `~/.browsercontrol/user_data`, so a site you sign in to once stays signed in. * **It works with any MCP client.** Claude Code, Claude Desktop, Cursor, VS Code, Gemini CLI, Zed, and anything else that speaks MCP over stdio or HTTP. ## Next steps --- --- url: https://adityasasidhar.github.io/browsercontrol/guide/quickstart.md description: >- Install BrowserControl, connect it to your MCP client, and run a first browsing task in about two minutes. --- # Quickstart Install the server, connect your client, and ask your agent to use a browser. ### Install uv The commands below launch BrowserControl with [uv](https://docs.astral.sh/uv/getting-started/installation/), which downloads it on first use. Check that uv is on your `PATH`: ```bash uv --version ``` If you would rather install with pip, see [Installation](/guide/installation). ### Add BrowserControl to your client For Claude Code, the plugin is the quickest route: it adds the MCP server and the [agent skill](/guide/agent-skill) together. Restart Claude Code or run `/reload-plugins` afterwards. For every other client, see [Connect a client](/guide/clients). ### Ask for something Reload your client, then try: > Open Hacker News with BrowserControl and tell me the top story. The first launch can take a minute: BrowserControl reuses a Chromium or Chrome it finds, and otherwise downloads Chromium once. ## What just happened 1. The agent called `navigate_to("https://news.ycombinator.com")`. 2. BrowserControl loaded the page, waited for it to [settle](/concepts/settling), and returned a screenshot with every link and button numbered, plus the same numbers as text. 3. The agent read the top story from the screenshot or the text, and, if it needed more, called something like `click(12)` or `get_page_content()`. The browser opens a visible window by default. To hide it, set `BROWSER_HEADLESS=true` in your client's MCP config. See [Configuration](/reference/configuration#browser_headless). ::: tip Not working? If your client doesn't list BrowserControl's tools, check its MCP logs, then see [Troubleshooting](/help/troubleshooting#the-client-cant-find-browsercontrol). ::: ## Next steps --- --- url: https://adityasasidhar.github.io/browsercontrol/guide/installation.md description: >- Requirements and every way to install BrowserControl, plus how it picks a browser on first launch. --- # Installation BrowserControl needs Python 3.11 or newer and runs on Linux, macOS, and Windows. Allow about 300 MB if it has to download Chromium. ## Choose how to run it Most people don't install anything: their MCP client runs `uvx browsercontrol`, which fetches the package on first use. Install it yourself when you want a fixed version or a command on your `PATH`. ::: code-group ```bash [uvx] # Nothing to install. Use this as your client's command: uvx browsercontrol ``` ```bash [uv] uv tool install browsercontrol # If uv warns that its tool directory is not on PATH: uv tool update-shell ``` ```bash [pip] python -m pip install browsercontrol ``` ```bash [pipx] pipx install browsercontrol ``` ```bash [source] git clone https://github.com/adityasasidhar/browsercontrol cd browsercontrol uv sync # Client command: uv --directory /absolute/path/to/browsercontrol run browsercontrol ``` ::: If you install into a virtual environment, give your MCP client the full path to that environment's `browsercontrol` executable. Check the install: ```bash browsercontrol --help ``` ## How it picks a browser On first launch BrowserControl looks for a browser in this order: 1. The binary in [`BROWSER_EXECUTABLE_PATH`](/reference/configuration#browser_executable_path), if you set one. 2. Playwright's cached Chromium. 3. An installed Google Chrome, run with its own separate profile so your everyday Chrome data is never touched. 4. If none of those start, it downloads Chromium. With [`BROWSER_EXTENSION_PATH`](/reference/configuration#browser_extension_path) set, automatic selection uses Playwright's Chromium, since extensions need it. To download Chromium ahead of time, run this in an environment that has Playwright (prefix with `uv run` inside a uv project): ```bash python -m playwright install chromium ``` ::: details Linux needs extra libraries? Chromium depends on system libraries that minimal Linux images often lack. Install them with: ```bash python -m playwright install chromium --with-deps ``` If Playwright has no Chromium build for your distribution, point `BROWSER_EXECUTABLE_PATH` at a Chrome or Chromium you already have. See [Troubleshooting](/help/troubleshooting#chromium-won-t-launch). ::: BrowserControl is listed in the official [MCP Registry](https://registry.modelcontextprotocol.io/v0/servers?search=io.github.adityasasidhar/browsercontrol) as `io.github.adityasasidhar/browsercontrol`. ## Next step [Connect your MCP client →](/guide/clients) --- --- url: https://adityasasidhar.github.io/browsercontrol/guide/clients.md description: >- MCP configuration for Codex, Claude Code, Claude Desktop, Cursor, VS Code, Gemini CLI, Cline, Zed, Continue, OpenCode, Hermes, OpenClaw, and the Python SDK. --- # Connect a client Your MCP client launches BrowserControl as a local server over stdio. Plugin installs and the manual `uvx browsercontrol` examples need [uv](https://docs.astral.sh/uv/getting-started/installation/). If you [installed](/guide/installation) the `browsercontrol` command yourself, use it directly in your manual configuration. ## Codex ```bash codex plugin marketplace add adityasasidhar/browsercontrol codex plugin add browsercontrol@browsercontrol ``` The plugin installs the local MCP server and the [agent skill](/guide/agent-skill) together. Make sure `uv` is on the PATH that Codex uses, then start a new session and ask Codex to use BrowserControl. The plugin keeps its browser profile and downloads in its Codex plugin data directory. ## Claude Code ::: code-group ```text [Plugin] /plugin marketplace add adityasasidhar/browsercontrol /plugin install browsercontrol@browsercontrol ``` ```bash [Manual] claude mcp add --transport stdio browsercontrol -- uvx browsercontrol ``` ::: The plugin installs the MCP server and the [agent skill](/guide/agent-skill) together; restart Claude Code or run `/reload-plugins` afterwards. The manual command adds only the server, for the current project. Run `/mcp` to check the connection. ## Clients with an `mcpServers` file Most clients read a JSON file with an `mcpServers` object. Add this entry to it: ```json { "mcpServers": { "browsercontrol": { "command": "uvx", "args": ["browsercontrol"] } } } ``` | Client | Where the file lives | | --- | --- | | Claude Desktop | **Settings → Developer → Edit Config** opens `claude_desktop_config.json`. | | Cursor | `.cursor/mcp.json` in a project, or `~/.cursor/mcp.json` for all projects. [Docs](https://cursor.com/docs/mcp) | | Gemini CLI | `.gemini/settings.json` in a project, or `~/.gemini/settings.json`. [Docs](https://geminicli.com/docs/tools/mcp-server/) | | Cline | **MCP Servers → Configure → Configure MCP Servers**. [Docs](https://docs.cline.bot/mcp/mcp-overview) | | VS Code (Copilot) | **Chat: Open Customizations → MCP Servers → Add Server**. In a portable config, add `"type": "stdio"` to the entry. [Docs](https://code.visualstudio.com/docs/agents/reference/mcp-configuration) | ## OpenCode With OpenCode 2.3.2 or later, install the plugin globally: ```bash opencode plugin add github:adityasasidhar/browsercontrol opencode mcp list ``` The plugin loads the bundled MCP server and [agent skill](/guide/agent-skill). If you already configured a server named `browsercontrol`, the plugin uses that configuration. Open a session and mention `@browsercontrol` to load the skill. For manual setup, add the server to your project's `opencode.json` or your OpenCode user configuration. Select the example for your major version. ::: code-group ```json [OpenCode 2] { "mcp": { "servers": { "browsercontrol": { "type": "local", "command": ["uvx", "browsercontrol"] } } } } ``` ```json [OpenCode 1] { "mcp": { "browsercontrol": { "type": "local", "command": ["uvx", "browsercontrol"], "enabled": true } } } ``` ::: ## Hermes ```bash hermes mcp add browsercontrol --command uvx --args browsercontrol ``` This adds the server to your Hermes configuration. Start a new session so Hermes picks it up. It installs the server only, not the [agent skill](/guide/agent-skill). ## OpenClaw ```bash openclaw mcp add browsercontrol --command uvx --arg browsercontrol ``` This registers the server with OpenClaw and probes it before saving. Restart the gateway or start a new session to load it. It installs the server only, not the [agent skill](/guide/agent-skill). ## Other formats ::: code-group ```json [Zed] { "context_servers": { "browsercontrol": { "command": "uvx", "args": ["browsercontrol"] } } } ``` ```yaml [Continue] mcpServers: - name: browsercontrol type: stdio command: uvx args: - browsercontrol ``` ::: Zed takes the entry in its settings JSON ([docs](https://zed.dev/docs/ai/mcp)), and Continue in its `config.yaml` ([docs](https://docs.continue.dev/customize/deep-dives/mcp)). ## From Python The MCP Python SDK can launch BrowserControl and call its tools from a script: ```python import asyncio from mcp import ClientSession, StdioServerParameters from mcp.client.stdio import stdio_client async def main() -> None: server = StdioServerParameters(command="uvx", args=["browsercontrol"]) async with stdio_client(server) as (read, write): async with ClientSession(read, write) as session: await session.initialize() result = await session.call_tool("navigate_to", {"url": "https://example.com"}) print(result.content[0].text) asyncio.run(main()) ``` ## Launch commands | How you installed | Command | Arguments | | --- | --- | --- | | Nothing (uv) | `uvx` | `["browsercontrol"]` | | Nothing (pipx) | `pipx` | `["run", "browsercontrol"]` | | `uv tool`, `pip`, or `pipx install` | `browsercontrol` | none | | Source checkout | `uv` | `["--directory", "/path/to/browsercontrol", "run", "browsercontrol"]` | A desktop app may not see the same `PATH` as your terminal. If the client can't find the command, use its full path (`which uvx` prints it). ## Pass settings Add an `env` object to the server entry to configure BrowserControl. For example, to run the browser headless: ```json { "mcpServers": { "browsercontrol": { "command": "uvx", "args": ["browsercontrol"], "env": { "BROWSER_HEADLESS": "true" } } } } ``` Every setting is listed in [Configuration](/reference/configuration). ## Check the connection Reload your client's MCP servers or restart it, then look for `navigate_to` in its tool list. If the server doesn't start, read the client's MCP log and see [Troubleshooting](/help/troubleshooting). To share one browser between several clients, run BrowserControl yourself over HTTP instead: see [Share over HTTP](/guide/http). --- --- url: https://adityasasidhar.github.io/browsercontrol/guide/first-session.md description: >- Fill in a public demo form with your agent and learn to read the element map as you go. --- # Your first session This walkthrough uses Selenium's public demo form, so nothing you type goes anywhere that matters. It takes two prompts and shows the habit every good BrowserControl session depends on: read the newest numbers before acting. ### Open the form Ask your agent: > Open https://www.selenium.dev/selenium/web/web-form.html with BrowserControl. Tell me the numbers of the text input and the Submit button. The agent calls `navigate_to`, and BrowserControl answers with this: ![The demo form with numbered boxes: the text input is 3 and Submit is 2](/images/annotated-web-form.webp) Here the text input is Text input and the button is Submit. The disabled field is drawn grey and listed as `(disabled)`. ### Fill and submit Ask: > Type "BrowserControl demo" into the text input, then submit the form and confirm the next page says "Form submitted". The agent works in three moves: 1. `type_text(3, "BrowserControl demo")`. The response is a **new** screenshot and map. 2. It finds Submit again **in that new map** and calls `click` with its current number. 3. It checks the result in the returned screenshot, or reads the page with `get_page_content()`. ::: tip Why look up Submit again? Typing doesn't visibly change the form, but it does produce a new screenshot, and numbering is rebuilt from scratch every time. Here Submit probably kept number 2. On a page that shifts, it wouldn't. Reading the latest map costs nothing, while acting on an old number gets a [stale element](/concepts/set-of-marks#stale-ids) error at best. ::: ## Do it in one call Once the agent knows the numbers, it can batch the steps with [`act`](/reference/interaction#act): ```text → act([{"action": "type", "element_id": 3, "text": "BrowserControl demo"}, {"action": "click", "element_id": 2}]) Ran 2 of 2 step(s), 0 failed: 1. ok: typed 'BrowserControl demo' into [3] 2. ok: clicked [2] ``` Every ID in an `act` call refers to the screenshot taken before the call, so batching is safe as long as the steps don't navigate away halfway through. ## Try next --- --- url: https://adityasasidhar.github.io/browsercontrol/guide/agent-skill.md description: >- Install the BrowserControl skill, a playbook that teaches agents to drive the browser reliably, and the machine-readable docs agents can use. --- # Agent skill Connecting the MCP server tells an agent which tools exist. The **skill** teaches it how to use them well: that numbers expire after every action, that a cookie banner can swallow a click, that a missing number usually means "scroll". It is a Markdown playbook the agent loads only when a task involves a browser. It's optional. BrowserControl works without it, but with it agents hit fewer stale IDs and retry the wrong element less often. ## Install it The [Codex](/guide/clients#codex), [Claude Code](/guide/clients#claude-code), and [OpenCode 2](/guide/clients#opencode) plugins include the skill. To install it by hand in Claude Code: ::: code-group ```bash [This project] mkdir -p .claude/skills/browsercontrol curl -fsSL https://raw.githubusercontent.com/adityasasidhar/browsercontrol/main/skills/browsercontrol/SKILL.md \ -o .claude/skills/browsercontrol/SKILL.md ``` ```bash [All projects] mkdir -p ~/.claude/skills/browsercontrol curl -fsSL https://raw.githubusercontent.com/adityasasidhar/browsercontrol/main/skills/browsercontrol/SKILL.md \ -o ~/.claude/skills/browsercontrol/SKILL.md ``` ::: Restart Claude Code and confirm with `/skills`. You can also call it directly with `/browsercontrol`. **Other agents:** the file is plain Markdown with a short YAML header. Paste its body into whatever your client uses for standing instructions, such as a rules file or a system prompt. ## Why it costs almost nothing Skills load in stages: | Stage | What loads | When | | --- | --- | --- | | 1 | The `name` and one-line `description` | Every session, about one line | | 2 | The body of `SKILL.md` | Only when a task needs a browser, or you type `/browsercontrol` | On a task with no browser in it, the agent carries a single sentence. ## What's in it * **The loop**, and why every action makes the previous screenshot useless. * **Three rules** that prevent most failures: an ID lives for one screenshot, no number means hidden rather than absent, and the text map is ground truth. * **How to choose a tool**: `find` versus scrolling, `act` versus single calls, extraction versus reading the page, `wait_for` versus fixed waits. * **Behavior to rely on**: `type_text` replaces rather than appends, `check_checkbox` sets rather than toggles, settings like mocks stick until undone, full-page screenshots aren't annotated. * **Recipes** for forms, debugging, responsive checks, multi-tab research, and recording. * **Recovery**: a symptom-to-fix table. Read it on [GitHub](https://github.com/adityasasidhar/browsercontrol/blob/main/skills/browsercontrol/SKILL.md). ## Docs for agents This site is published in forms an agent can read directly: | URL | What it is | | --- | --- | | [`/llms.txt`](/llms.txt){target="\_blank"} | An index of every page with a one-line summary, following [llmstxt.org](https://llmstxt.org). | | [`/llms-full.txt`](/llms-full.txt){target="\_blank"} | All of the documentation in one file. | | Any page + `.md` | That page as plain Markdown, for example [`/guide/quickstart.md`](/guide/quickstart.md){target="\_blank"}. | | [`/tools.json`](/tools.json){target="\_blank"} | Every tool with its signature, parameters, and return type, generated from the server. | Each page also has a **Copy page** button under its title, with options to view the Markdown or open the page in an AI assistant. --- --- url: https://adityasasidhar.github.io/browsercontrol/guide/http.md description: >- Run BrowserControl as a Streamable HTTP server so several MCP clients can share one browser, with optional per-client isolation. --- # Share over HTTP By default each MCP client launches its own BrowserControl over stdio. To let several clients or agents share one browser, start the server yourself and serve it over Streamable HTTP. ## Start the server ```bash uvx browsercontrol --transport http ``` It listens on `http://127.0.0.1:8000/mcp`. Change the address with `--host` and `--port`, or with `BROWSER_HOST` and `BROWSER_PORT`. `--transport sse` serves the older SSE transport for clients that still need it. ## Point clients at it ::: code-group ```bash [Claude Code] claude mcp add --transport http browsercontrol http://127.0.0.1:8000/mcp ``` ```json [mcpServers] { "mcpServers": { "browsercontrol": { "url": "http://127.0.0.1:8000/mcp" } } } ``` ::: Clients differ in how they name URL-based servers (`url`, `serverUrl`, or a `type: "http"` field). Check your client's MCP docs if the entry above isn't recognized. ## Shared or isolated Every connected client drives the same browser, but each keeps its own choice of [session](/concepts/sessions). One agent calling `switch_session` doesn't move another. To keep clients fully apart, give each its own isolated session automatically: ```bash uvx browsercontrol --transport http --isolate-clients ``` With `--isolate-clients` (or `BROWSER_ISOLATE_CLIENTS=true`), each client gets a fresh in-memory session on its first tool call: separate cookies, tabs, captured traffic, mocks, and action log. Use it when agents work in parallel and must not see each other's logins. ## Security ::: danger There is no authentication Anyone who can reach the port controls the browser, including every site it is signed in to. Keep the default `127.0.0.1` host. BrowserControl logs a warning if you bind to any other address. ::: If you do need remote access, put it behind something that authenticates, such as an SSH tunnel (`ssh -L 8000:127.0.0.1:8000 host`) or a reverse proxy with auth. --- --- url: https://adityasasidhar.github.io/browsercontrol/concepts/how-it-works.md description: >- The act, settle, look loop every BrowserControl tool runs, what a tool response contains, and how the pieces fit together. --- # How it works Three things are involved: your **agent** (a model plus an MCP client), the **BrowserControl server**, and a real **Chromium** that the server drives through [Playwright](https://playwright.dev/python/). The agent never touches the page directly. It calls tools, and every tool that changes the page answers with a fresh picture of it. ```text Agent + MCP client BrowserControl Chromium ─────────────────── ─────────────────── ──────────────── click(7) ───────▶ find element 7 ─────▶ real click wait for the page to settle screenshot + map ◀─────── number the controls ◀──── screenshot ``` ## The loop Every page-changing tool runs the same cycle. ### Act The agent names an element by its number, for example `click(7)`. BrowserControl looks up element 7 in the current tab's map and finds that exact element again through a tag it placed on it, inside the right frame and through shadow DOM. If the element was removed, hidden, or moved since the screenshot, the tool doesn't act. It returns a [stale ID](/concepts/set-of-marks#stale-ids) error and a fresh screenshot instead. ### Settle The page is given time to finish reacting: the DOMContentLoaded event, then in-flight network requests, then DOM changes, all within a budget of 3 seconds by default. See [Settling](/concepts/settling). ### Look BrowserControl takes a screenshot, finds the interactive elements in every frame, numbers them, draws the boxes, and returns the image together with a text list of the same numbers. The previous map is replaced. ## What a response looks like A tool like `click` returns a status line, any notices, the element list, and the annotated image: ```text Clicked element 7 (button: Add to cart) Notice: Downloaded invoice.pdf to /home/me/.browsercontrol/downloads/invoice.pdf Found 23 interactive elements: [1] a - acme.shop [2] a - Shop [3] input[search] - Search keyboards [4] button[submit] - Search [5] input[checkbox] - In stock only [6] button (disabled) - Checkout ... ``` * **Status line.** What the tool did, or `Error: …` and why. * **Notices.** Things that happened during the action that the screenshot can't show, such as a [JS dialog](/reference/waiting#handle_dialog) that was answered or a file that was downloaded. * **Element list.** One line per element: number, tag, input type, `(disabled)` when relevant, and up to 40 characters of its text. It lists the first 30 elements; higher numbers still work. * **Image.** The screenshot with the same numbers drawn on it. Tools that only read (like `get_console_logs`, `list_tabs`, or the extraction tools) return text without a screenshot. The [tool explorer](/reference/) marks which is which. ## The pieces | Part | What it does | | --- | --- | | **Server** | A [FastMCP](https://gofastmcp.com) app with 69 tools, 8 `browser://` [resources](/reference/resources), and middleware that binds each call to the calling client's session. It serves stdio by default, or [Streamable HTTP](/guide/http). | | **Browser manager** | Starts the browser: a persistent profile, or [your own Chrome](/recipes/your-chrome) over CDP. Settles the page after each action and keeps one element map per tab. | | **Element detection** | Runs in every frame (cross-origin included), descends into open shadow roots, keeps elements that are visible and not covered, and tags each with a numbered attribute so it can be found again. | | **Sessions** | Each [session](/concepts/sessions) is one browser context with its own tabs, captured console and network data, mocks, emulation, dialog policy, and action log. | | **Codegen** | Records each action with a locator a person would write, for [`export_test`](/reference/recording#export_test). | ## Why a screenshot plus a list * **Nothing to invent.** The model picks a number it can see. It never writes `div.flex > button:nth-child(3)` and hopes. * **Both views at once.** The image shows layout, color, and state; the list names icon-only buttons and input types the image can't. * **Small.** A list of numbered elements costs far fewer tokens than a DOM or accessibility tree. * **Honest about change.** Numbers are rebuilt every time, and an out-of-date number is refused rather than silently applied to whatever moved into its place. --- --- url: https://adityasasidhar.github.io/browsercontrol/concepts/set-of-marks.md description: >- How BrowserControl numbers what an agent can use, how long a number stays valid, and what happens when it goes stale. --- # Set of Marks **Set of Marks** is a way of prompting a vision model: draw a numbered box around each thing it can act on, and let it answer with a number. BrowserControl uses it as its whole interface. Each annotated screenshot outlines every usable control, and the same numbers come back as a text list. ![A demo web form with numbered boxes on every field and button](/images/annotated-web-form.webp) An agent looking at this calls `type_text(3, "Hello")` for the text input and, after reading the new map, `click(2)` for Submit. The technique comes from the paper [Set-of-Mark Prompting Unleashes Extraordinary Visual Grounding in GPT-4V](https://arxiv.org/abs/2310.11441). ## What gets a number An element is numbered when it is **interactive**, **in the viewport**, and **not covered**. **Interactive** means any of: * links, buttons, inputs (except hidden ones), selects, textareas, `summary`, `label[for]` * elements with a role such as `button`, `link`, `tab`, `menuitem`, `checkbox`, `radio`, `switch`, `option`, `combobox`, or `textbox` * `contenteditable` regions, `[onclick]`, and focusable `[tabindex]` elements * elements that start a `cursor: pointer` area, which catches framework click handlers that leave no attribute behind **In the viewport** means at least partly on screen. Off-screen controls get no number until you scroll to them or `find` them. **Not covered** means the element itself is what you would click at that spot. A control under a cookie banner, modal, or sticky header gets no number. There is one exception: checkboxes, radios, and file inputs that a site makes transparent and replaces with a styled stand-in are still numbered, because they still work. Detection runs in **every frame**, cross-origin iframes included, and descends into **open shadow roots**. **Disabled** controls are numbered too, drawn grey, and listed as `(disabled)`, so the agent can see that a button exists but needs something first. ## A number lives for one screenshot Every annotated screenshot rebuilds the map from scratch: every click, typed value, scroll, navigation, tab switch, and `screenshot()` call. Number 7 before a click can be a different element, or nothing, after it. The rule for agents is short: **read the newest map before every action that takes an ID.** The one exception is [`act`](/reference/interaction#act), where every ID in the batch refers to the map from before the call. Maps are kept per tab, so an ID from one tab never resolves against another. ## Stale IDs {#stale-ids} When the agent passes a number, BrowserControl finds that element again by a tag it placed on it during the screenshot, using a locator scoped to the element's own frame. Before acting it checks that the element is still the one the screenshot showed. It refuses when the element has: * been removed from the page, or its frame has gone * become hidden * changed content (a framework recycled the node for something else) * been duplicated, so the tag is ambiguous * moved more than 3 pixels and settled somewhere new (an element still animating is accepted) A refusal returns an error and a fresh screenshot to choose from: ```text Error: Element 7 is stale (it moved). The page changed since the last screenshot; use the IDs in the fresh one below. Found 18 interactive elements: ... ``` An unknown number gets `Error: Element 42 not found. Valid IDs: [1, 2, 3, …]`. In both cases nothing was clicked, so it's safe to retry with a number from the new map. ## When the control you want has no number | Situation | What to do | | --- | --- | | It's below the fold and you know its text | `find("Delete account")` searches the whole page, iframes and shadow DOM included, scrolls to it, and returns its number. | | You're exploring | `scroll("down")` and read the new map. | | You can see it, but it has no number | Something covers it. Close the banner or modal first. | | It's a canvas or a map with no elements | `click_at(x, y)` with coordinates from the screenshot. | ## Crowded pages On a page with hundreds of controls, picking from the screenshot gets noisy. Some ways around that: * **Search instead of scanning.** `find("Add to cart", role="button")` lists every match with its number and skips text that isn't a button. * **Batch.** Once you have the numbers you need, `act` runs the steps against one map in a single call. * **Extract instead of reading.** [`extract_table`, `extract_links`, and `extract`](/reference/extraction) return structured data without picking elements at all. * **Read one element.** `get_text(id)` returns an element's full, current text. ## Why not selectors? Selectors are written by the model, so they can be wrong, and they break when a site changes its markup. Accessibility trees are precise on well-built sites, but they're long and give the model no picture of the page. Numbers on a screenshot give the model something it can see and something it can't get wrong by inventing: it can only pick a number that exists. See [How it compares](/concepts/comparison). --- --- url: https://adityasasidhar.github.io/browsercontrol/concepts/settling.md description: >- How BrowserControl waits for a page to finish reacting after each action, and when to wait longer with wait_for or wait_for_response. --- # Settling After every action, BrowserControl waits for the page to finish reacting before it takes the screenshot. A single-page app that fetches data and then renders is captured complete, not half drawn, and the agent rarely needs to sleep. ## The three stages ### Load Wait for the `DOMContentLoaded` event, which matters after a navigation. ### Network quiet Wait until no request has been in flight for 200 ms. Streams (WebSocket, EventSource, media) and requests open for more than 10 seconds, such as long polling, are ignored so they can't hold every action hostage. ### DOM quiet Wait until the page has gone 200 ms without a DOM change, for at most one second. All three share one budget, [`BROWSER_SETTLE_TIMEOUT`](/reference/configuration#browser_settle_timeout), 3 seconds by default. When the budget runs out, BrowserControl takes the screenshot anyway. Settling never fails an action. Tune the budget for your sites: lower it on static pages for speed, raise it for slow apps. ## When to wait longer Some things take longer than any sensible budget: a report that renders after ten seconds, a payment that confirms asynchronously. Wait for the condition itself rather than for time. | You're waiting for | Use | | --- | --- | | Text to appear | `wait_for(text="Order confirmed")` | | An element to appear or go away | `wait_for(selector=".spinner", state="hidden")` | | All network activity to stop | `wait_for(network_idle=True)` (500 ms with nothing in flight) | | A specific API call | `wait_for_response("/api/orders")`, called right after the action that sends it | | Nothing in particular | `wait(seconds)`, as a last resort | `wait_for` and `wait_for_response` time out after 10 seconds by default (`timeout_seconds`). A timeout isn't an error: the response says what timed out and still includes the screenshot. ```text → click(12) # "Place order" → wait_for_response("/api/orders", status=201) Response received: #57 POST https://shop.test/api/orders -> 201 (842ms) Body: {"id": "ord_123", "status": "confirmed"} ``` `wait_for_response` also counts responses that arrived during the previous tool call, so calling it right after the click never misses a fast response. ## Things that happen while settling A JS `alert`, `confirm`, or `prompt` can't be allowed to block the page, so BrowserControl answers it straight away. Alerts are acknowledged, confirms and prompts are dismissed, and `beforeunload` is accepted. Files the page downloads are saved. Both show up as `Notice:` lines at the top of the next response: ```text Notice: A JS dialog appeared: confirm('Delete this item?'), dismissed. Call handle_dialog() before the action to choose the answer. ``` To answer differently, call [`handle_dialog(accept=True)`](/reference/waiting#handle_dialog) and repeat the action. --- --- url: https://adityasasidhar.github.io/browsercontrol/concepts/sessions.md description: >- The persistent default profile, attaching to your own Chrome, isolated sessions, and how several MCP clients share one server. --- # Sessions & profiles A **session** is one browser context: its own cookies, storage, and tabs. BrowserControl always has a default session, and you can open more. | | Cookies and logins | Use it for | | --- | --- | --- | | **Default session** | A persistent profile on disk | Everyday work: log in once, stay logged in. | | **Your own Chrome** | Whatever you're signed in to | Sites you already use, without logging in again. | | **Isolated session** | Fresh, in memory, gone when closed | A second user, signed-out flows, or keeping agents apart. | ## The default session BrowserControl launches Chromium with a persistent profile in `~/.browsercontrol/user_data` ([`BROWSER_USER_DATA_DIR`](/reference/configuration#browser_user_data_dir)). Cookies, `localStorage`, and history survive restarts, so an agent that signed in yesterday is still signed in today. Sites can still expire a login on their own schedule. Only one process can use a profile at a time. To run two BrowserControl servers side by side, give each its own `BROWSER_USER_DATA_DIR`. ## Your own Chrome Instead of launching its own browser, BrowserControl can attach to a Chrome you started with remote debugging, using the Chrome DevTools Protocol (CDP): ```text connect_to_chrome("http://localhost:9222") ``` The agent opens a tab of its own rather than taking over yours. Disconnecting, or stopping the server, only detaches, and your Chrome keeps running. To attach at startup, set [`BROWSER_CDP_URL`](/reference/configuration#browser_cdp_url). The full walkthrough is in [Use your own Chrome](/recipes/your-chrome). ## Isolated sessions ```text create_session("buyer", device="iPhone 13", url="https://shop.test") ``` This opens a fresh context with no shared cookies, storage, or tabs, and switches to it. With `device`, the whole context is created as that device, pixel ratio and mobile layout included, which is more faithful than emulating a device in an existing session. Isolated sessions live in memory and disappear when closed. Move between sessions with `switch_session(name)` (`"default"` is the persistent one), list them with `list_sessions()`, and discard one with `close_session(name)`. The default session can't be closed. ## What each session keeps Everything BrowserControl captures or changes belongs to the session it happened in: * tabs, and the element map of each tab * console messages, page errors, and network requests * request mocks and emulation settings * the dialog policy and downloads * the action log that [`export_test`](/reference/recording#export_test) turns into a test Switching sessions switches all of it. ## Several clients, one server When several MCP clients share a server over [HTTP](/guide/http), each client keeps its own current session. One agent calling `switch_session` doesn't move another. To isolate clients completely, start the server with `--isolate-clients` (or `BROWSER_ISOLATE_CLIENTS=true`). Each client then gets its own isolated session on its first tool call. --- --- url: https://adityasasidhar.github.io/browsercontrol/concepts/comparison.md description: >- How BrowserControl's numbered-screenshot approach differs from accessibility-tree servers, LLM-driven browser frameworks, and pixel-level computer use. --- # How it compares There are several good ways to give an agent a browser. They differ mostly in **what the model sees** and **who decides the next step**. ## Four approaches | Approach | The model sees | The model acts by | Examples | | --- | --- | --- | --- | | **Numbered screenshots** | A screenshot with numbered boxes, plus the same list as text | Naming a number: `click(7)` | BrowserControl | | **Accessibility snapshots** | A text tree of the page's roles and names, with references | Naming a reference from the tree | Playwright MCP | | **Framework with its own LLM** | Whatever the framework shows its internal model | Natural-language instructions the framework turns into actions | Browser Use, Stagehand | | **Pixels and coordinates** | A plain screenshot | Clicking at `x, y` | Computer-use style agents | ## Numbered screenshots **Strengths** * The model gets a picture *and* precise targets. Layout, color, and state are visible; icon-only buttons and input types are named in the list. * It can't invent a target, since it can only pick a number that exists. Out-of-date numbers are refused rather than applied to whatever moved in. * What the model sees is what a user sees: elements covered by a modal or overlay get no number. **Trade-offs** * Each step returns an image, which costs more tokens than a short text snapshot. The text list helps a text-only model, but the approach is designed for vision models. * Only what's on screen is numbered, so long pages need `find` or scrolling. ## Accessibility snapshots Servers like [Playwright MCP](https://github.com/microsoft/playwright-mcp) describe the page as a tree of roles and names. On well-built, accessible sites this is precise and compact, and it works with models that can't see images. It reaches iframes and shadow DOM too, and costs far fewer tokens per step than a screenshot. The model gets no picture of layout or visual state. **Pick it when** token cost matters most, your model is text-only, or the task doesn't depend on how the page looks. ## Frameworks with their own LLM Libraries such as [Browser Use](https://browser-use.com) and [Stagehand](https://stagehand.dev) put a model inside the automation layer: you describe a goal or step in words, and the framework decides what to click. That's convenient, but every step calls a model behind the scenes, which brings its own API key, latency, and cost. **Pick it when** you're building an automation in code and want the framework to plan the steps. ## Pixels and coordinates Computer-use agents click at coordinates on a plain screenshot. It works on anything, including canvases and native apps, but the model must locate targets precisely by itself, which is where most mistakes happen. BrowserControl keeps [`click_at(x, y)`](/reference/interaction#click_at) for the cases where nothing has a number. ## Where BrowserControl fits Choose it when you want: * **Vision and text together**, with targets the model can't get wrong by guessing. * **Everything local.** BrowserControl calls no model and needs no API key. The browser, its profile, and its captured traffic stay on your machine. * **A full toolbox** in one server: debugging, network mocking, emulation, recording, and test export, alongside the clicks. * **Your real browser**: a persistent logged-in profile, or your own Chrome attached over CDP. * **To see the page**: layout and visual bugs, mobile and dark-mode checks, and UIs where the picture matters. --- --- url: https://adityasasidhar.github.io/browsercontrol/recipes.md description: >- Task-by-task walkthroughs for common BrowserControl jobs, from research and forms to debugging, testing, and test export. --- # Recipes Each recipe starts with a prompt you could give your agent, shows the tool calls it leads to, and explains the choices along the way. ## Do things on the web ## Build and test web apps ::: tip Reading the transcripts Lines starting with `→` are tool calls the agent makes. Numbers like `click(5)` stand for whatever number that element has in *your* latest screenshot; read yours rather than copying ours. ::: --- --- url: https://adityasasidhar.github.io/browsercontrol/recipes/research.md description: >- Use BrowserControl to search a site, open the right result, read it efficiently, and answer with a source. --- # Research a question > Find who created the Python programming language using Wikipedia, and give me the source URL. ```text → navigate_to("https://en.wikipedia.org") → type_text(4, "Python programming language") → press_key("Enter") → find("Python (programming language)", role="link") → click(9) → get_page_content() → get_page_info() ``` ### Search Open the site, type into its search field, and submit with `press_key("Enter")` (or click the search button). If the site has a search URL, going straight there is faster: `navigate_to("https://en.wikipedia.org/w/index.php?search=python")`. ### Pick the result Results pages are crowded. Rather than scanning the screenshot, let `find` locate the result by its text. It scrolls there and reports the number to click: ```text → find("Python (programming language)", role="link") Found 1 match(es) for link 'Python (programming language)'; scrolled to match 1. 1. link 'Python (programming language)' -> element [9] <- scrolled here ``` ### Read Choose the cheapest way to read: | You need | Use | | --- | --- | | The article's text | `get_page_content()`: the page as Markdown, up to 30,000 characters | | One paragraph or cell | `get_text(id)`: one element's full text | | Every link on the page | `extract_links()` | | A table | `extract_table()` | ### Cite `get_page_info()` returns the current URL and title for the answer. ::: tip Long pages `get_page_content()` cuts off at 30,000 characters. For a long article, `find` the section heading first, then read the elements you need with `get_text`. ::: Comparing several sources at once? See [Work across tabs](/recipes/tabs). --- --- url: https://adityasasidhar.github.io/browsercontrol/recipes/fill-a-form.md description: >- Fill text fields, dropdowns, checkboxes, and custom widgets with BrowserControl, then submit and verify the result. --- # Fill a form > Sign up on the demo shop with the name Ada Lovelace and ada@example.com, pick "United Kingdom", accept the terms, and submit. ```text → navigate_to("https://shop.test/signup") → act([{"action": "type", "element_id": 3, "text": "Ada Lovelace"}, {"action": "type", "element_id": 4, "text": "ada@example.com"}, {"action": "select", "element_id": 5, "option": "United Kingdom"}, {"action": "check", "element_id": 6}]) → click(7) → wait_for(text="Welcome") ``` ## Pick the right tool for each control | Control | Tool | Notes | | --- | --- | --- | | Text, email, search, textarea, rich text | `type_text(id, text)` | **Replaces** the current value. To append, read it with `get_text(id)` first. | | Native `` directly, exactly as if the user had picked it. The page sees an ordinary selection. ### Find the file input File inputs show up in the element list as `input[file]`. Many sites hide the real input behind a styled "Choose file" button; BrowserControl still numbers the hidden input, so look for `input[file]` rather than the button. ### Upload ```text → upload_file(8, "/home/me/Documents/resume.pdf") Uploaded 'resume.pdf' to element 8 ``` Use an **absolute path** on the machine where BrowserControl runs. A relative path is resolved against the server's working directory, which is rarely what you expect. If the file doesn't exist, the tool says `File not found`. ### Confirm and submit Most sites show the chosen file name next to the input; check the screenshot, then submit as usual. ## When it doesn't take | Symptom | Cause | Fix | | --- | --- | --- | | The page ignores the file | The input's `accept` attribute rejects the type | `inspect_element(id)` shows `accept`; use a matching file. | | No `input[file]` in the list | A drop zone that only accepts drag and drop | Look for a hidden input with `find("", role="button")` or `run_javascript("document.querySelectorAll('input[type=file]').length")`. | | Upload starts but never finishes | The upload request is slow | `wait_for_response("/upload")` right after the action. | `upload_file` sends one file per call. --- --- url: https://adityasasidhar.github.io/browsercontrol/recipes/extract-data.md description: >- Pull tables, links, and arbitrary fields out of a page as JSON with extract_table, extract_links, and schema-based extract. --- # Extract data > Get every product on this page with its name, price, and link, as JSON. ```text → navigate_to("https://shop.test/keyboards") → extract({"products": [{"_selector": ".product", "name": "h3", "price": ".price", "url": "a@href"}]}) ``` Reading data off a screenshot is slow and error-prone. The extraction tools return structured text instead, with no screenshot. ## Tables ```text → extract_table() table #1: 2 row(s), 2 header(s) [{"Name": "Apple", "Price": "1"}, {"Name": "Pear", "Price": "2"}] ``` * Pick a table by any element inside it, `extract_table(element_id=12)`, or by position, `extract_table(index=2)`. * `output_format` is `json` (rows keyed by header), `markdown`, or `csv`. * Works on HTML `` (honoring ``, an all-`
` first row, and `colspan`) and on ARIA `role="table"` and `role="grid"` widgets. ## Links ```text → extract_links(contains="docs", limit=50) ``` Every link on the page, shadow DOM included, as `{text, href, visible}`, with absolute URLs and duplicates removed. `contains` filters by text or URL. ## Anything else: a schema Describe the shape you want, using CSS selectors as values: ```text → extract({"title": "h1", "products": [{"_selector": ".product", "name": "h3", "price": ".price", "url": "a@href"}]}) { "title": "Keyboards", "products": [ {"name": "Halo 75", "price": "$129", "url": "https://shop.test/halo-75"}, {"name": "Lumen TKL", "price": "$99", "url": "https://shop.test/lumen-tkl"} ] } ``` | Value | Returns | | --- | --- | | `"h1"` | Text of the first match (a form field gives its value) | | `"a@href"` | An attribute of the first match; `href` and `src` come back absolute | | `"@href"` | An attribute of the scoped element itself | | `[".tag"]` | Text of **every** match | | `[{"_selector": ".card", …}]` | One object per match, fields relative to it | | `{"_selector": "#main", …}` | One object, scoped to the first match | Schema selectors run against the main document, not inside iframes or shadow roots. For those, use `get_text(id)` on numbered elements. ## Pages that load more as you scroll Infinite feeds only render what's near the viewport. Scroll, extract, and repeat: ```text → scroll("down", "page") → extract({"posts": [{"_selector": "article", "title": "h2", "url": "a@href"}]}) ``` Duplicates across passes are yours to merge. --- --- url: https://adityasasidhar.github.io/browsercontrol/recipes/tabs.md description: Open several pages in tabs, switch between them, and compare what they say. --- # Work across tabs > Compare the pricing pages of two products and tell me which has the cheaper team plan. ```text → create_tab("https://product-a.example/pricing") → create_tab("https://product-b.example/pricing") → list_tabs() → switch_tab(1) → extract_table() → switch_tab(2) → extract_table() ``` ### Open tabs `create_tab(url)` opens a tab, switches to it, and returns its screenshot. Without a URL it opens a blank tab. ### See what's open ```text → list_tabs() Open Tabs: [0] Hacker News - https://news.ycombinator.com [1] Pricing · Product A - https://product-a.example/pricing * [2] Pricing · Product B - https://product-b.example/pricing ``` Tabs are numbered from 0, `*` marks the active one, and `list_tabs` returns text only, so it's cheap. ### Switch and read `switch_tab(index)` focuses a tab and returns a fresh screenshot of it. Each tab keeps its own element map, so a number from tab 1 never resolves against tab 2. ## Good to know * **Tabs share a session.** Cookies and storage are shared, so signing in on one tab signs in the others. For a separate user, use [`create_session`](/concepts/sessions#isolated-sessions). * **Indexes shift.** Closing tab 0 makes tab 1 the new tab 0. Call `list_tabs()` again after closing. * **Closing the active tab** switches to another open tab automatically. * **Popups count.** A link that opens a new window adds a tab. `list_tabs()` shows it. --- --- url: https://adityasasidhar.github.io/browsercontrol/recipes/debug.md description: >- Find out why a page is broken with BrowserControl's console, page error, network, and inspection tools. --- # Debug a web app > The Users page on localhost:3000 is blank. Find out why. ```text → navigate_to("http://localhost:3000/users") → get_page_errors() → get_console_logs() → get_network_requests() → get_request_details(14) ``` BrowserControl records console messages, uncaught errors, and network traffic for every tab from the moment it opens. Debugging is a matter of reading the right one first. ### Open the page ```text → navigate_to("http://localhost:3000/users") ``` If `localhost` refuses the connection, BrowserControl retries with `127.0.0.1` on its own. ### Start with uncaught errors ```text → get_page_errors() Page Errors: TypeError: Cannot read properties of undefined (reading 'map') at UserList (http://localhost:3000/src/UserList.tsx:14:22) ``` An uncaught exception is usually the whole story. ### Then the console ```text → get_console_logs() Console Logs: [ERROR] Failed to load resource: the server responded with a status of 500 (Internal Server Error) (http://localhost:3000/api/users) [WARNING] Each child in a list should have a unique "key" prop. ``` The last 50 messages, with their level and source. ### Then the network ```text → get_network_requests() Network Requests: #12 GET http://localhost:3000/users -> 200 (31ms) #14 GET http://localhost:3000/api/users -> 500 (88ms) ``` The 30 most recent requests by default (`num_requests` to change it), each with an `#id`, status, and timing. Pass the id to see everything about one request: ```text → get_request_details(14) ``` Request and response headers, POST data, and the response body (text up to 10,000 characters, binary as base64). Bodies are read on demand, so ask before navigating away. ## Reproduce an interaction To see what one action causes, clear the buffers first so only new entries show: ```text → get_console_logs(clear=True) → get_network_requests(clear=True) → click(7) # the button that misbehaves → get_page_errors() → get_console_logs() → get_network_requests() ``` If the click fires a request you care about, `wait_for_response("/api/save")` right after it waits for that response and shows its status and body. ## Look closer | Question | Tool | | --- | --- | | Why is this element invisible or misplaced? | `inspect_element(id)`: tag, attributes, size, position, and computed styles | | What's in this variable? | `run_in_console("window.__APP_STATE__")` | | Is the page slow? | `get_page_performance()`: time to first byte, first contentful paint, load timings, resource count, JS heap | | What cookies does it have? | `get_cookies()` | | Can I share this with someone? | `export_har("users-500")` saves the traffic; `take_snapshot("users-500")` saves a screenshot and the HTML | Captured data is also available without a tool call, as [MCP resources](/reference/resources) like `browser://errors` and `browser://network`. --- --- url: https://adityasasidhar.github.io/browsercontrol/recipes/edge-states.md description: >- Check how a page handles server errors, empty data, slow or offline networks, and other hard-to-reach states with request mocks and throttling. --- # Test edge states The bugs that hurt are in states a real backend rarely produces on demand: a 500 from the API, an empty list, a slow network. Mock the request or throttle the network, and let the agent check what the page does. > On localhost:3000/cart, make the cart API fail and check that the page shows a useful error. ```text → mock_route("/api/cart", status=500, body='{"error": "internal"}') → navigate_to("http://localhost:3000/cart") → get_console_logs() → clear_mocks() ``` ### Mock before you load ```text → mock_route("/api/cart", status=500, body='{"error": "internal"}') ``` From now on, every tab in the session answers matching requests with this response. A second mock with the same pattern replaces the first. Patterns can be a **substring** (`/api/cart`), a **glob** (`**/api/*`), or a **regex** prefixed with `re:` (`re:/users/\d+$`). ### Load the page and check it ```text → navigate_to("http://localhost:3000/cart") ``` The screenshot shows what a user would see. `get_console_logs()` and `get_page_errors()` show what they wouldn't. ### Clean up ```text → clear_mocks() ``` Mocks stay until you clear them. `clear_mocks("/api/cart")` removes just one. ## Common mocks | State | Mock | | --- | --- | | Server error | `mock_route("/api/cart", status=500, body='{"error": "internal"}')` | | Empty list | `mock_route("/api/cart", body='{"items": []}')` | | Signed out | `mock_route("/api/me", status=401)` | | Outage | `mock_route("/api/", abort=True)` | | A tracker you don't want | `mock_route("**/analytics/**", abort=True)` | | Custom headers | `mock_route("/api/cart", body="{}", headers={"Retry-After": "30"}, status=429)` | ## Slow and offline ```text → throttle_network("slow-3g") → refresh_page() ``` Check spinners, skeletons, and timeouts. Profiles are `slow-3g`, `fast-3g`, and `4g` (Chrome DevTools' presets), `offline`, and `none` to restore the network. ## Requests the page sends later When a request fires on a click, wait for it right after the click: ```text → click(8) # "Apply coupon" → wait_for_response("/api/coupon") Response received: #31 POST http://localhost:3000/api/coupon -> 500 (12ms) Body: {"error": "internal"} ``` Pass the `#id` to `get_request_details` for the full headers and body. ::: tip Turn it into a test Mocks are part of the action log, so [`export_test`](/recipes/record-tests#export-a-playwright-test) reproduces them in the generated Playwright test. ::: For devices, dark mode, timezones, and locations, see [Mobile & dark mode](/recipes/responsive). --- --- url: https://adityasasidhar.github.io/browsercontrol/recipes/responsive.md description: >- Check a page on phones and tablets, in dark mode, and in other timezones and locations with BrowserControl's emulation tools. --- # Mobile & dark mode > Check the home page on an iPhone in dark mode and tell me if anything overflows. ```text → emulate_device("iPhone 13") → set_color_scheme("dark") → navigate_to("https://my-site.test") → screenshot(annotate=False, full_page=True) → reset_emulation() ``` ## Pick how faithful you need to be | Need | Use | What you get | | --- | --- | --- | | A quick size check | `set_viewport(390, 844)` | The viewport only | | A phone, quickly | `emulate_device("iPhone 13")` | Screen size, user agent, and touch input, then a reload | | A phone, exactly | `create_session("phone", device="iPhone 13")` | A new context created as that device, pixel ratio and mobile layout viewport included | Device pixel ratio and the mobile layout viewport can only be set when a browser context is created, which is why the exact option opens a new [session](/concepts/sessions). `list_devices("iphone")` shows the available names (about 140 phones, tablets, and desktops). ## Other conditions | Condition | Tool | | --- | --- | | Dark or light mode | `set_color_scheme("dark")`, `"light"`, or `"no-preference"` | | Another timezone | `set_timezone("Asia/Tokyo")`; `""` resets | | Another location | `set_geolocation(35.68, 139.69)`, which also grants the permission | | A slow or offline network | `throttle_network("slow-3g")`; see [Test edge states](/recipes/edge-states) | Emulation applies to every tab in the session, including tabs opened later, and stays until `reset_emulation()`. ## Capture the result * `screenshot(annotate=False)` gives a clean image for a bug report. * `screenshot(annotate=False, full_page=True)` captures the whole scrollable page. Full-page screenshots are never annotated, so use them to review layout, not to find numbers. ## Compare several sizes ```text → set_viewport(1440, 900); screenshot(annotate=False, full_page=True) → set_viewport(768, 1024); screenshot(annotate=False, full_page=True) → set_viewport(390, 844); screenshot(annotate=False, full_page=True) ``` Each screenshot comes back inline, so the agent can compare them directly. --- --- url: https://adityasasidhar.github.io/browsercontrol/recipes/your-chrome.md description: >- Attach BrowserControl to a Chrome you started with remote debugging, so the agent works in sites you're already signed in to. --- # Use your own Chrome Let the agent work in your own Chrome, with the sites you're already signed in to, instead of logging in again inside BrowserControl's browser. > Connect to my Chrome and check whether my last order on shop.example.com has shipped. ```text → connect_to_chrome("http://localhost:9222") → navigate_to("https://shop.example.com/orders") → find("Order #", role="link") → click(14) → get_page_content() → disconnect_chrome() ``` ### Start Chrome with remote debugging Quit Chrome, then start it with a debugging port and a profile directory for agent work: ::: code-group ```bash [Linux] google-chrome --remote-debugging-port=9222 --user-data-dir="$HOME/.chrome-agent" ``` ```bash [macOS] "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" \ --remote-debugging-port=9222 --user-data-dir="$HOME/.chrome-agent" ``` ```powershell [Windows] & "C:\Program Files\Google\Chrome\Application\chrome.exe" ` --remote-debugging-port=9222 --user-data-dir="$env:USERPROFILE\.chrome-agent" ``` ::: ::: warning Chrome 136 and later need a separate profile Chrome ignores `--remote-debugging-port` on its default profile. The first time you use the `--user-data-dir` above, sign in to the sites the agent needs. That profile remembers them from then on. ::: ### Attach Ask the agent to connect, or attach at startup so every session begins in your Chrome: ::: code-group ```text [From the agent] connect_to_chrome("http://localhost:9222") ``` ```json [At startup] { "mcpServers": { "browsercontrol": { "command": "uvx", "args": ["browsercontrol"], "env": { "BROWSER_CDP_URL": "http://localhost:9222" } } } } ``` ::: The agent opens a tab of its own rather than taking over the one you're looking at. `list_tabs()` and `switch_tab()` reach your other tabs if you ask it to. ### Work as usual Every tool works the same: numbered screenshots, `find`, `act`, extraction, network capture, recording. [Isolated sessions](/concepts/sessions#isolated-sessions) created while attached open as incognito-like contexts in your Chrome. ### Detach ```text → disconnect_chrome() ``` This only detaches. Your Chrome and its tabs keep running, and BrowserControl goes back to its own browser. Stopping the server has the same effect. ::: danger The debugging port is full control Anything that can reach port 9222 can read and drive that browser, signed-in sessions included. Keep it on `localhost`, use a profile signed in only to what the agent needs, and close Chrome when you're done. ::: --- --- url: https://adityasasidhar.github.io/browsercontrol/recipes/record-tests.md description: >- Capture a Playwright trace of an agent's session for bug reports, and turn the same run into a Playwright test you can keep and run in CI. --- # Record & export tests Two outputs, from the same run: * A **trace**: a replayable recording with a timeline, screenshots, DOM snapshots, and network, for bug reports and review. * A **test**: a pytest-playwright or `@playwright/test` file that repeats what the agent did, for CI. > Walk through the login flow on staging while recording, then export it as a test. ```text → start_recording("login_flow") → navigate_to("https://staging.example.com/login") → type_text(3, "user@example.com") → type_text(4, "correct-horse-battery") → click(5) → wait_for(text="Dashboard") → stop_recording() → export_test("login_flow") ``` ### Start recording ```text → start_recording("login_flow") Recording started: login_flow.zip Call stop_recording() when done. ``` It also restarts the action log, so the test you export afterwards covers exactly this run. ### Walk through the flow Call tools as usual. Every action goes into the trace and the action log. Wait for results with `wait_for` rather than fixed sleeps, so the trace and the test wait for the same thing. ### Stop and view the trace ```text → stop_recording() Recording saved: /home/me/.browsercontrol/recordings/login_flow.zip View with: npx playwright show-trace /home/me/.browsercontrol/recordings/login_flow.zip ``` Open it with that command, or drop the file on [trace.playwright.dev](https://trace.playwright.dev). ### Export a Playwright test {#export-a-playwright-test} ```text → export_test("login_flow") # pytest-playwright → export_test("login_flow", language="typescript") # @playwright/test ``` ```python def test_login_flow(page: Page) -> None: page.goto("https://staging.example.com/login") page.get_by_label("Email", exact=True).fill("user@example.com") page.get_by_label("Password", exact=True).fill(os.environ["BC_SECRET_1"]) page.get_by_role("button", name="Sign in", exact=True).click() expect(page.get_by_text("Dashboard").first).to_be_visible() ``` The response includes the file path (`test_login_flow.py` or `login_flow.spec.ts` in `~/.browsercontrol/generated_tests`) and the command to run it. ## How the test is written * **Locators a person would write.** Each step uses a test id, role and name, label, placeholder, or text, falling back to a CSS path. Every locator was checked against the live page, before the action ran, to match exactly that one element. Element numbers never appear. * **What's covered:** navigation, clicks, typing, keys, selects, checkboxes, uploads, drags, scrolls, waits for text, dialog answers, and request mocks. * **No secrets.** Text typed into password fields is never stored; the test reads it from `BC_SECRET_1`, `BC_SECRET_2`, and so on. Set those when you run it. * **Review before committing.** An agent's exploration often includes steps a test doesn't need. Trim them, and add assertions for what matters. `export_test(clear=True)` empties the action log afterwards, ready for the next flow. ## Snapshots For a single moment rather than a whole flow, `take_snapshot("checkout-error")` saves a PNG and the page's HTML to `~/.browsercontrol/snapshots`. `list_recordings()` lists recent traces and snapshots. --- --- url: https://adityasasidhar.github.io/browsercontrol/reference.md description: >- Search and filter all 69 BrowserControl MCP tools, with signatures, parameters, and links to each category's reference. --- # Tool reference BrowserControl exposes 69 MCP tools. Search them below, filter by category, and open any tool for its signature and parameters. Tools marked **screenshot** return a fresh annotated screenshot with their result; tools marked **text** return text only. Either kind can change browser state: `clear_cookies`, for example, returns text. ## By category ## Also in the reference * [MCP resources](/reference/resources): captured data readable without a tool call. * [Configuration](/reference/configuration): environment variables and command-line flags. * [`tools.json`](/tools.json){target="\_blank"}: this catalog as JSON, generated from the server. ## Every tool | Tool | Category | Summary | | --- | --- | --- | | `navigate_to(url)` | Navigation | Open a URL in the current tab. | | `find(query, role, nth)` | Navigation | Search the whole page and scroll to a match; returns its element ID. | | `scroll(direction, amount)` | Navigation | Scroll the page. | | `go_back()`, `go_forward()`, `refresh_page()` | Navigation | History and reload. | | `click(element_id)` | Interaction | Click a numbered element. | | `type_text(element_id, text)` | Interaction | Replace a field's text. | | `press_key(key)` | Interaction | Press a key or combination such as `Control+A`. | | `act(steps, stop_on_error)` | Interaction | Run up to 25 steps in one call. | | `hover`, `double_click`, `right_click`, `scroll_to_element` (element_id) | Interaction | Pointer actions on a numbered element. | | `drag(source_id, target_id)` | Interaction | Drag one element onto another. | | `click_at(x, y)` | Interaction | Click at coordinates, for spots with no number. | | `wait(seconds)` | Interaction | Fixed sleep; prefer `wait_for`. | | `wait_for(text, selector, state, network_idle, timeout_seconds)` | Waiting | Wait for a condition. | | `handle_dialog(accept, prompt_text)` | Waiting | Choose the answer to the next JS dialog. | | `list_downloads()` | Waiting | Files downloaded in this session. | | `select_option(element_id, option)` | Forms | Pick from a native select. | | `check_checkbox(element_id, check)` | Forms | Set a checkbox or radio. | | `upload_file(element_id, file_path)` | Forms | Set a file on a file input. | | `get_page_content()` | Content | The page as Markdown. | | `get_text(element_id)` | Content | One element's full text. | | `get_page_info()` | Content | URL and title. | | `screenshot(annotate, full_page)` | Content | Annotated or clean screenshot. | | `run_javascript(script)` | Content | Evaluate JavaScript. | | `extract_table(element_id, index, output_format)` | Extraction | A table as JSON, Markdown, or CSV. | | `extract_links(contains, limit)` | Extraction | All links as JSON. | | `extract(schema)` | Extraction | Fields from a selector schema. | | `create_tab(url)`, `list_tabs()`, `switch_tab(index)`, `close_tab(index)` | Tabs | Tab management. | | `connect_to_chrome(cdp_url)`, `disconnect_chrome()` | Sessions | Attach to and detach from your own Chrome. | | `create_session(name, device, url)`, `switch_session(name)`, `list_sessions()`, `close_session(name)` | Sessions | Isolated sessions. | | `get_console_logs(clear)`, `get_page_errors()`, `get_network_requests(num_requests, clear)` | DevTools | Captured logs, errors, traffic. | | `inspect_element(element_id)`, `run_in_console(code)`, `get_page_performance()` | DevTools | Inspection and performance. | | `get_cookies()`, `set_cookie(name, value, domain, path)`, `delete_cookie(name)`, `clear_cookies()` | DevTools | Cookies. | | `set_viewport(width, height)` | DevTools | Resize the viewport. | | `mock_route(url_pattern, status, body, content_type, headers, abort)`, `clear_mocks(url_pattern)` | Network | Mock or block requests. | | `wait_for_response(url_pattern, status, timeout_seconds)` | Network | Wait for a matching response. | | `get_request_details(request_id, include_body)`, `export_har(name, include_bodies)` | Network | Request details and HAR export. | | `list_devices(contains)`, `emulate_device(name)` | Emulation | Devices. | | `set_color_scheme(scheme)`, `set_timezone(timezone_id)`, `set_geolocation(latitude, longitude, accuracy)` | Emulation | Environment. | | `throttle_network(profile)`, `reset_emulation()` | Emulation | Network speed and reset. | | `start_recording(name)`, `stop_recording()`, `take_snapshot(name)`, `list_recordings()` | Recording | Traces and snapshots. | | `export_test(name, language, clear)` | Recording | The session as a Playwright test. | --- --- url: https://adityasasidhar.github.io/browsercontrol/reference/navigation.md description: Open URLs, move through history, scroll, and find anything on the page. --- # Navigation Open pages, move through history, scroll, and search the whole page for the element you want. | Tool | Does | Returns | | --- | --- | --- | | [`navigate_to`](#navigate_to) | Navigate to a URL. Returns an annotated screenshot with numbered interactive elements. | text + screenshot | | [`find`](#find) | Search the whole page, including content scrolled out of view, and scroll to a match. | text + screenshot | | [`scroll`](#scroll) | Scroll the page. | text + screenshot | | [`go_back`](#go_back) | Navigate back to the previous page. | text + screenshot | | [`go_forward`](#go_forward) | Navigate forward to the next page. | text + screenshot | | [`refresh_page`](#refresh_page) | Refresh the current page. | text + screenshot | ## `navigate_to` {#navigate_to} Navigate to a URL. Returns an annotated screenshot with numbered interactive elements. ```python navigate_to(url: str) ``` Returns text and a fresh annotated screenshot. | Parameter | Type | Default | Description | | --- | --- | --- | --- | | `url` | `str` | required | The URL to navigate to | Opens the URL in the current tab and waits for it to settle. `http`, `https`, `file`, and `about:blank` URLs all work. If a `localhost` URL refuses the connection, it retries with `127.0.0.1`. Navigation times out after [`BROWSER_TIMEOUT`](/reference/configuration#browser_timeout) (30 s). ```text → navigate_to("https://news.ycombinator.com") → navigate_to("http://localhost:3000") ``` ## `find` {#find} Search the whole page, including content scrolled out of view, and scroll to a match. ```python find(query: str, role: str | None = None, nth: int = 1) ``` Returns text and a fresh annotated screenshot. | Parameter | Type | Default | Description | | --- | --- | --- | --- | | `query` | `str` | required | Text to look for (case-insensitive substring) | | `role` | `str \| None` | `None` | Optional ARIA role to restrict matches to | | `nth` | `int` | `1` | Which match to scroll to, 1-based (default 1) | Searches every frame and open shadow root, including content scrolled out of view, scrolls to a match, and lists every match with the number it has in the new screenshot. A match inside a button maps to the button. ```text → find("Delete account") Found 2 match(es) for 'Delete account'; scrolled to match 1. 1. button 'Delete account' -> element [14] <- scrolled here 2. h2 'Delete account' -> off-screen; find('Delete account', nth=2) scrolls to it ``` `find("", role="button")` lists every button on the page. ## `scroll` {#scroll} Scroll the page. ```python scroll(direction: str = 'down', amount: str = 'medium') ``` Returns text and a fresh annotated screenshot. | Parameter | Type | Default | Description | | --- | --- | --- | --- | | `direction` | `str` | `"down"` | "up", "down", "left", or "right" | | `amount` | `str` | `"medium"` | "small" (100px), "medium" (400px), "large" (800px), "page" (full viewport), "top", "bottom", or pixels like "500" | | `amount` | Distance | | --- | --- | | `small` | 100 px | | `medium` | 400 px | | `large` | 800 px | | `page` | 720 px | | `top`, `bottom` | Jump to the top or bottom | | `"500"` | Exactly that many pixels | ```text → scroll() # 400 px down → scroll("up", "small") → scroll("down", "bottom") ``` ## `go_back` {#go_back} Navigate back to the previous page. ```python go_back() ``` Returns text and a fresh annotated screenshot. Moves back one entry in the tab's history. ## `go_forward` {#go_forward} Navigate forward to the next page. ```python go_forward() ``` Returns text and a fresh annotated screenshot. Moves forward one entry in the tab's history. ## `refresh_page` {#refresh_page} Refresh the current page. ```python refresh_page() ``` Returns text and a fresh annotated screenshot. Reloads the current page and waits for it to settle. ## See also * [Research a question](/recipes/research) * [Set of Marks](/concepts/set-of-marks) --- --- url: https://adityasasidhar.github.io/browsercontrol/reference/interaction.md description: >- Click, type, press keys, hover, drag, and batch several steps into one call with act. --- # Interaction Act on numbered elements. Every tool here returns a fresh annotated screenshot, so the next call has new numbers. | Tool | Does | Returns | | --- | --- | --- | | [`click`](#click) | Click on an element by its ID number shown in the screenshot. | text + screenshot | | [`type_text`](#type_text) | Type text into a text field by its ID number, replacing what it holds. | text + screenshot | | [`press_key`](#press_key) | Press a keyboard key or key combination on the focused element. | text + screenshot | | [`act`](#act) | Run several steps in one call and return one screenshot at the end. | text + screenshot | | [`hover`](#hover) | Hover over an element by its ID number. | text + screenshot | | [`double_click`](#double_click) | Double-click an element by its ID number (e.g. to open an item or select a word). | text + screenshot | | [`right_click`](#right_click) | Right-click an element by its ID number to open its context menu. | text + screenshot | | [`drag`](#drag) | Drag one element and drop it onto another (sortable lists, kanban cards, sliders). | text + screenshot | | [`scroll_to_element`](#scroll_to_element) | Scroll to bring an element into view. | text + screenshot | | [`click_at`](#click_at) | Click at specific x,y coordinates. | text + screenshot | | [`wait`](#wait) | Wait for a specified time (useful for pages with animations or loading). | text + screenshot | ## `click` {#click} Click on an element by its ID number shown in the screenshot. ```python click(element_id: int) ``` Returns text and a fresh annotated screenshot. | Parameter | Type | Default | Description | | --- | --- | --- | --- | | `element_id` | `int` | required | The number label shown on the element in the screenshot | Finds the numbered element itself, in its frame and through shadow DOM, scrolls it into view, and clicks it. It never clicks at stored coordinates, so an overlay can't steal the click silently. * A **stale** ID (the element moved, vanished, or changed since the screenshot) is refused with a fresh screenshot. See [Stale IDs](/concepts/set-of-marks#stale-ids). * A **disabled** element is refused immediately instead of waiting out the timeout. ```text → click(5) Clicked element 5 (button: Sign in) ``` ## `type_text` {#type_text} Type text into a text field by its ID number, replacing what it holds. ```python type_text(element_id: int, text: str) ``` Returns text and a fresh annotated screenshot. | Parameter | Type | Default | Description | | --- | --- | --- | --- | | `element_id` | `int` | required | The number label shown on the element | | `text` | `str` | required | Text to type | **Replaces** whatever the field holds. To append, read the current value with `get_text(id)` and type the combined text. Works on inputs, textareas, contenteditable regions, and `textbox`, `searchbox`, and `combobox` widgets. Checkboxes, buttons, dropdowns, and file inputs are refused with the right tool to use instead. ```text → type_text(3, "ada@example.com") ``` ## `press_key` {#press_key} Press a keyboard key or key combination on the focused element. ```python press_key(key: str) ``` Returns text and a fresh annotated screenshot. | Parameter | Type | Default | Description | | --- | --- | --- | --- | | `key` | `str` | required | Key to press (e.g., "Enter", "Tab", "Escape", "ArrowDown", "Backspace"), or a combination joined with "+" (e.g., "Control+A", "Shift+Tab", "ControlOrMeta+C" for copy on any OS, "Control+Shift+T") | Presses a key, or a combination joined with `+`, on whatever has focus. ```text → press_key("Enter") → press_key("Escape") # close a modal → press_key("Control+A") → press_key("ControlOrMeta+C") # copy on any OS ``` ## `act` {#act} Run several steps in one call and return one screenshot at the end. ```python act(steps: list[dict[str, Any]], stop_on_error: bool = True) ``` Returns text and a fresh annotated screenshot. | Parameter | Type | Default | Description | | --- | --- | --- | --- | | `steps` | `list[dict[str, Any]]` | required | The steps to run in order (at most 25) | | `stop_on_error` | `bool` | `True` | Stop at the first failing step (default True) | Runs several steps and returns one screenshot. Every element ID refers to the screenshot taken **before** the call; a step whose element is gone (after a navigation, say) fails as stale, so put navigation last. At most 25 steps. `stop_on_error=False` keeps going after a failed step. | `action` | Fields | | --- | --- | | `click`, `double_click`, `right_click`, `hover` | `element_id` | | `type` | `element_id`, `text` | | `select` | `element_id`, `option` | | `check` | `element_id`, `checked` (default `true`) | | `drag` | `element_id`, `target_id` | | `press` | `key` | | `scroll` | `direction`, `amount` | | `navigate` | `url` | | `wait` | `seconds` | | `wait_for` | `text` or `selector`, `timeout_seconds` | ```text → act([{"action": "type", "element_id": 3, "text": "ada@example.com"}, {"action": "type", "element_id": 4, "text": "hunter2"}, {"action": "click", "element_id": 5}]) Ran 3 of 3 step(s), 0 failed: 1. ok: typed 'ada@example.com' into [3] 2. ok: typed ******* into [4] 3. ok: clicked [5] ``` ## `hover` {#hover} Hover over an element by its ID number. ```python hover(element_id: int) ``` Returns text and a fresh annotated screenshot. | Parameter | Type | Default | Description | | --- | --- | --- | --- | | `element_id` | `int` | required | The number label shown on the element | Moves the pointer over the element, for tooltips, hover menus, and `:hover` styles. The returned screenshot shows what appeared. ## `double_click` {#double_click} Double-click an element by its ID number (e.g. to open an item or select a word). ```python double_click(element_id: int) ``` Returns text and a fresh annotated screenshot. | Parameter | Type | Default | Description | | --- | --- | --- | --- | | `element_id` | `int` | required | The number label shown on the element in the screenshot | Double-clicks the element, for example to open an item or select a word. ## `right_click` {#right_click} Right-click an element by its ID number to open its context menu. ```python right_click(element_id: int) ``` Returns text and a fresh annotated screenshot. | Parameter | Type | Default | Description | | --- | --- | --- | --- | | `element_id` | `int` | required | The number label shown on the element in the screenshot | Right-clicks the element to open its context menu. ## `drag` {#drag} Drag one element and drop it onto another (sortable lists, kanban cards, sliders). ```python drag(source_id: int, target_id: int) ``` Returns text and a fresh annotated screenshot. | Parameter | Type | Default | Description | | --- | --- | --- | --- | | `source_id` | `int` | required | The number label of the element to drag | | `target_id` | `int` | required | The number label of the element to drop onto | Drags one element onto another: sortable lists, kanban cards, sliders, and HTML5 drop zones. Both IDs come from the same, latest screenshot. ## `scroll_to_element` {#scroll_to_element} Scroll to bring an element into view. ```python scroll_to_element(element_id: int) ``` Returns text and a fresh annotated screenshot. | Parameter | Type | Default | Description | | --- | --- | --- | --- | | `element_id` | `int` | required | The number label shown on the element | Scrolls until the element is in view. To reach something that has no number yet, use [`find`](/reference/navigation#find). ## `click_at` {#click_at} Click at specific x,y coordinates. ```python click_at(x: int, y: int) ``` Returns text and a fresh annotated screenshot. | Parameter | Type | Default | Description | | --- | --- | --- | --- | | `x` | `int` | required | X coordinate | | `y` | `int` | required | Y coordinate | Clicks at viewport coordinates. Use it only for a spot with no number, such as a canvas or a map; for anything numbered, `click` is safer. ## `wait` {#wait} Wait for a specified time (useful for pages with animations or loading). ```python wait(seconds: float = 1.0) ``` Returns text and a fresh annotated screenshot. | Parameter | Type | Default | Description | | --- | --- | --- | --- | | `seconds` | `float` | `1.0` | Time to wait in seconds (default: 1.0) | Sleeps for a fixed time. Prefer [`wait_for`](/reference/waiting#wait_for), which waits for the thing you actually need. ## See also * [Fill a form](/recipes/fill-a-form) * [Forms](/reference/forms) --- --- url: https://adityasasidhar.github.io/browsercontrol/reference/waiting.md description: >- Wait for a condition instead of sleeping, choose how JS dialogs are answered, and list downloads. --- # Waiting & dialogs Every action already [settles](/concepts/settling) before it returns. These tools cover what takes longer, and the dialogs and downloads that happen along the way. | Tool | Does | Returns | | --- | --- | --- | | [`wait_for`](#wait_for) | Wait until a condition holds instead of sleeping a fixed time. | text + screenshot | | [`handle_dialog`](#handle_dialog) | Choose how to answer the next JS dialog (alert, confirm, prompt, beforeunload). | text | | [`list_downloads`](#list_downloads) | List files downloaded in this session, with where they were saved. | text | ## `wait_for` {#wait_for} Wait until a condition holds instead of sleeping a fixed time. ```python wait_for(text: str | None = None, selector: str | None = None, state: str = 'visible', network_idle: bool = False, timeout_seconds: float = 10.0) ``` Returns text and a fresh annotated screenshot. | Parameter | Type | Default | Description | | --- | --- | --- | --- | | `text` | `str \| None` | `None` | Wait for an element containing this text | | `selector` | `str \| None` | `None` | Wait for an element matching this CSS selector | | `state` | `str` | `"visible"` | "visible" (default), "hidden", "attached", or "detached" | | `network_idle` | `bool` | `False` | Also wait until no request has been in flight for 500ms | | `timeout_seconds` | `float` | `10.0` | Give up after this long (default 10) | Waits for text or a CSS selector to reach a state, for the network to go idle (500 ms with nothing in flight), or any combination. With no condition, it just settles the page. A timeout is not an error: the response says what timed out and still has the screenshot. ```text → wait_for(text="Order confirmed") → wait_for(selector=".spinner", state="hidden", timeout_seconds=30) → wait_for(network_idle=True) ``` `state` is `visible`, `hidden`, `attached`, or `detached`. ## `handle_dialog` {#handle_dialog} Choose how to answer the next JS dialog (alert, confirm, prompt, beforeunload). ```python handle_dialog(accept: bool = True, prompt_text: str | None = None) ``` Returns text only. | Parameter | Type | Default | Description | | --- | --- | --- | --- | | `accept` | `bool` | `True` | True to press OK, False to press Cancel | | `prompt_text` | `str \| None` | `None` | Text to enter into a prompt() dialog (only used when accepting) | Dialogs are never left blocking the page. Without a choice, alerts are acknowledged, confirms and prompts are dismissed, and `beforeunload` is accepted. Either way, the next response starts with a notice: ```text Notice: A JS dialog appeared: confirm('Delete this item?'), dismissed. Call handle_dialog() before the action to choose the answer. ``` To answer differently, call `handle_dialog(accept=True)` (with `prompt_text` for a prompt) and repeat the action. ## `list_downloads` {#list_downloads} List files downloaded in this session, with where they were saved. ```python list_downloads() ``` Returns text only. Downloads are saved automatically to [`BROWSER_DOWNLOADS_DIR`](/reference/configuration#paths) under the name the server suggests, never overwriting an existing file. Each is also reported as a `Notice:` in the next response. ## See also * [Settling](/concepts/settling) * [wait_for_response](/reference/network#wait_for_response) --- --- url: https://adityasasidhar.github.io/browsercontrol/reference/forms.md description: Native dropdowns, checkboxes and radios, and file uploads. --- # Forms Controls that need more than a click or typed text. For text fields, use [`type_text`](/reference/interaction#type_text). | Tool | Does | Returns | | --- | --- | --- | | [`select_option`](#select_option) | Select an option from a dropdown by element ID. | text + screenshot | | [`check_checkbox`](#check_checkbox) | Check or uncheck a checkbox (or select a radio button) by element ID. | text + screenshot | | [`upload_file`](#upload_file) | Upload a file to a file input element. | text + screenshot | ## `select_option` {#select_option} Select an option from a dropdown by element ID. ```python select_option(element_id: int, option: str) ``` Returns text and a fresh annotated screenshot. | Parameter | Type | Default | Description | | --- | --- | --- | --- | | `element_id` | `int` | required | The number label of the select element | | `option` | `str` | required | The value or visible text of the option to select | For native `` directly, with no native file picker involved. Use an absolute path on the machine running BrowserControl; one file per call. ```text → upload_file(8, "/home/me/Documents/resume.pdf") Uploaded 'resume.pdf' to element 8 ``` See [Upload a file](/recipes/upload-a-file). ## See also * [Fill a form](/recipes/fill-a-form) * [Upload a file](/recipes/upload-a-file) --- --- url: https://adityasasidhar.github.io/browsercontrol/reference/content.md description: >- Read the page as Markdown, read one element, run JavaScript, and take screenshots. --- # Content Read what's on the page, and take screenshots on demand. | Tool | Does | Returns | | --- | --- | --- | | [`get_page_content`](#get_page_content) | Get the page content as markdown text. | text + screenshot | | [`get_text`](#get_text) | Get the full, current text of an element by its ID. | text | | [`get_page_info`](#get_page_info) | Get current page URL and title. | text | | [`screenshot`](#screenshot) | Take a screenshot of the page. | text + screenshot | | [`run_javascript`](#run_javascript) | Execute JavaScript and return the result. | text + screenshot | ## `get_page_content` {#get_page_content} Get the page content as markdown text. ```python get_page_content() ``` Returns text and a fresh annotated screenshot. Returns the page as Markdown, with scripts and styles stripped, cut off at 30,000 characters, plus the annotated screenshot. For one element, use `get_text`; for structured data, the [extraction tools](/reference/extraction). ## `get_text` {#get_text} Get the full, current text of an element by its ID. ```python get_text(element_id: int) ``` Returns text only. | Parameter | Type | Default | Description | | --- | --- | --- | --- | | `element_id` | `int` | required | The number label of the element | Reads the live element, so it returns the whole text rather than the 40-character label from the element list (up to 10,000 characters). Form fields return their current value. ## `get_page_info` {#get_page_info} Get current page URL and title. ```python get_page_info() ``` Returns text only. ```text → get_page_info() Current page info: URL: https://en.wikipedia.org/wiki/Python_(programming_language) Title: Python (programming language) - Wikipedia ``` ## `screenshot` {#screenshot} Take a screenshot of the page. ```python screenshot(annotate: bool = True, full_page: bool = False) ``` Returns text and a fresh annotated screenshot. | Parameter | Type | Default | Description | | --- | --- | --- | --- | | `annotate` | `bool` | `True` | If True, overlay numbered element markers (default). If False, clean screenshot. | | `full_page` | `bool` | `False` | If True, capture the full scrollable page. | | Call | Result | | --- | --- | | `screenshot()` | Annotated viewport, with a new element map | | `screenshot(annotate=False)` | Clean viewport, for sharing | | `screenshot(annotate=False, full_page=True)` | Clean image of the whole scrollable page | Full-page screenshots are never annotated, even with `annotate=True`. Use them to review layout, not to find numbers. ## `run_javascript` {#run_javascript} Execute JavaScript and return the result. ```python run_javascript(script: str) ``` Returns text and a fresh annotated screenshot. | Parameter | Type | Default | Description | | --- | --- | --- | --- | | `script` | `str` | required | JavaScript code to execute | Evaluates JavaScript in the page and returns the result as JSON, with a fresh screenshot. Errors come back as `Error: …`. Use it to read state; for acting on the page, numbered tools are safer. ```text → run_javascript("document.title") → run_javascript("[...document.querySelectorAll('img')].length") ``` ## See also * [Extraction](/reference/extraction) * [Research a question](/recipes/research) --- --- url: https://adityasasidhar.github.io/browsercontrol/reference/extraction.md description: Tables, links, and schema-driven fields as JSON, with no screenshot. --- # Extraction Structured data out of the page. These tools return text only. | Tool | Does | Returns | | --- | --- | --- | | [`extract_table`](#extract_table) | Extract a table (HTML `` or ARIA table/grid) as structured data. | text | | [`extract_links`](#extract_links) | List the page's links as JSON: text, absolute href, and whether each is visible. | text | | [`extract`](#extract) | Extract structured JSON from the page with a selector schema. | text | ## `extract_table` {#extract_table} Extract a table (HTML `
` or ARIA table/grid) as structured data. ```python extract_table(element_id: int | None = None, index: int = 1, output_format: str = 'json') ``` Returns text only. | Parameter | Type | Default | Description | | --- | --- | --- | --- | | `element_id` | `int \| None` | `None` | An element inside (or containing) the table; omit to pick by index | | `index` | `int` | `1` | Which table on the page, 1-based, when element_id is omitted | | `output_format` | `str` | `"json"` | "json" (rows keyed by header), "markdown", or "csv" | Works on HTML `
` (honoring ``, an all-`
` first row, and `colspan`) and on ARIA `role="table"` and `role="grid"` widgets. Point at a table with any element inside it, or pick one by `index` (1-based). `output_format` is `json` (rows keyed by header), `markdown`, or `csv`. ```text → extract_table() table #1: 2 row(s), 2 header(s) [{"Name": "Apple", "Price": "1"}, {"Name": "Pear", "Price": "2"}] ``` ## `extract_links` {#extract_links} List the page's links as JSON: text, absolute href, and whether each is visible. ```python extract_links(contains: str = '', limit: int = 100) ``` Returns text only. | Parameter | Type | Default | Description | | --- | --- | --- | --- | | `contains` | `str` | `""` | Only links whose text or URL contains this (case-insensitive) | | `limit` | `int` | `100` | Maximum number of links to return (default 100) | Every link, shadow DOM included, as `{text, href, visible}`, with absolute URLs and duplicates removed. `contains` filters by text or URL. ## `extract` {#extract} Extract structured JSON from the page with a selector schema. ```python extract(schema: dict[str, Any]) ``` Returns text only. | Parameter | Type | Default | Description | | --- | --- | --- | --- | | `schema` | `dict[str, Any]` | required | The fields to extract, as described above | Each value in the schema is a CSS selector, optionally with `@attr`: | Value | Returns | | --- | --- | | `"h1"` | Text of the first match (a form field gives its value) | | `"a@href"` | An attribute of the first match; `href` and `src` come back absolute | | `"@href"` | An attribute of the scoped element itself | | `[".tag"]` | Text of every match | | `[{"_selector": ".card", …}]` | One object per match, fields relative to it | | `{"_selector": "#main", …}` | One object scoped to the first match | ```text → extract({"title": "h1", "products": [{"_selector": ".product", "name": "h3", "price": ".price", "url": "a@href"}]}) ``` Selectors run against the main document, not inside iframes or shadow roots. ## See also * [Extract data](/recipes/extract-data) --- --- url: https://adityasasidhar.github.io/browsercontrol/reference/tabs.md description: Open, list, switch between, and close tabs. --- # Tabs Tabs belong to the current [session](/concepts/sessions) and share its cookies. Each keeps its own element map. Indexes start at 0. | Tool | Does | Returns | | --- | --- | --- | | [`create_tab`](#create_tab) | Create a new tab and switch to it. | text + screenshot | | [`list_tabs`](#list_tabs) | List all open tabs with their indices, titles, and URLs. | text | | [`switch_tab`](#switch_tab) | Switch to a specific tab by its index. | text + screenshot | | [`close_tab`](#close_tab) | Close a specific tab by its index. | text + screenshot | ## `create_tab` {#create_tab} Create a new tab and switch to it. ```python create_tab(url: str | None = None) ``` Returns text and a fresh annotated screenshot. | Parameter | Type | Default | Description | | --- | --- | --- | --- | | `url` | `str \| None` | `None` | Optional URL to open in the new tab. | Opens a tab, switches to it, and returns its screenshot. Without `url`, the tab is blank. ## `list_tabs` {#list_tabs} List all open tabs with their indices, titles, and URLs. ```python list_tabs() ``` Returns text only. Text only, so it's cheap. `*` marks the active tab. ```text Open Tabs: [0] GitHub - https://github.com * [1] Hacker News - https://news.ycombinator.com ``` ## `switch_tab` {#switch_tab} Switch to a specific tab by its index. ```python switch_tab(index: int) ``` Returns text and a fresh annotated screenshot. | Parameter | Type | Default | Description | | --- | --- | --- | --- | | `index` | `int` | required | The 0-based index of the tab to switch to. | Focuses the tab and returns its screenshot and element map. ## `close_tab` {#close_tab} Close a specific tab by its index. ```python close_tab(index: int) ``` Returns text and a fresh annotated screenshot. | Parameter | Type | Default | Description | | --- | --- | --- | --- | | `index` | `int` | required | The 0-based index of the tab to close. | Closes the tab. Closing the active tab switches to another open one. Indexes after it shift down by one. ## See also * [Work across tabs](/recipes/tabs) --- --- url: https://adityasasidhar.github.io/browsercontrol/reference/sessions.md description: >- Attach to your own Chrome over CDP, and create, switch, list, and close isolated sessions. --- # Sessions Choose which browser and which context the agent works in. See [Sessions & profiles](/concepts/sessions) for the model. | Tool | Does | Returns | | --- | --- | --- | | [`connect_to_chrome`](#connect_to_chrome) | Attach to your own running Chrome so the agent uses its logged-in sessions. | text + screenshot | | [`disconnect_chrome`](#disconnect_chrome) | Detach from an attached Chrome (leaving it open) and go back to the managed browser. | text + screenshot | | [`create_session`](#create_session) | Open an isolated browser session (its own cookies, storage, tabs) and switch to it. | text + screenshot | | [`switch_session`](#switch_session) | Switch to another session. "default" is the persistent, logged-in profile. | text + screenshot | | [`list_sessions`](#list_sessions) | List browser sessions, their tabs, and which one you are using. | text | | [`close_session`](#close_session) | Close an isolated session and discard its cookies and tabs. | text | ## `connect_to_chrome` {#connect_to_chrome} Attach to your own running Chrome so the agent uses its logged-in sessions. ```python connect_to_chrome(cdp_url: str = 'http://localhost:9222') ``` Returns text and a fresh annotated screenshot. | Parameter | Type | Default | Description | | --- | --- | --- | --- | | `cdp_url` | `str` | `"http://localhost:9222"` | Chrome's remote debugging endpoint (default `http://localhost:9222`) | Attaches over the Chrome DevTools Protocol to a Chrome started with `--remote-debugging-port`. The agent works in a new tab of that Chrome; `list_tabs` and `switch_tab` reach the others. Disconnecting never closes your Chrome. To attach at startup, set [`BROWSER_CDP_URL`](/reference/configuration#browser_cdp_url). ::: warning Chrome 136 and later ignore `--remote-debugging-port` on the default profile, so start Chrome with a separate `--user-data-dir`. See [Use your own Chrome](/recipes/your-chrome). ::: ## `disconnect_chrome` {#disconnect_chrome} Detach from an attached Chrome (leaving it open) and go back to the managed browser. ```python disconnect_chrome() ``` Returns text and a fresh annotated screenshot. Detaches, leaving your Chrome open, and returns to the browser BrowserControl manages. ## `create_session` {#create_session} Open an isolated browser session (its own cookies, storage, tabs) and switch to it. ```python create_session(name: str, device: str | None = None, url: str | None = None) ``` Returns text and a fresh annotated screenshot. | Parameter | Type | Default | Description | | --- | --- | --- | --- | | `name` | `str` | required | A name for the session, used by switch_session and close_session | | `device` | `str \| None` | `None` | Optional device to emulate for the whole session (see list_devices) | | `url` | `str \| None` | `None` | Optional URL to open in the session | Opens a fresh context with no shared cookies, storage, or tabs, and switches to it. With `device`, the whole context is created as that device, pixel ratio and mobile viewport included. With `url`, it opens that page. Sessions live in memory and are lost when closed. ## `switch_session` {#switch_session} Switch to another session. "default" is the persistent, logged-in profile. ```python switch_session(name: str) ``` Returns text and a fresh annotated screenshot. | Parameter | Type | Default | Description | | --- | --- | --- | --- | | `name` | `str` | required | The session name (see list_sessions) | Makes another session current. `"default"` is the persistent profile, or your Chrome when attached. With several clients on one server, each client keeps its own choice. ## `list_sessions` {#list_sessions} List browser sessions, their tabs, and which one you are using. ```python list_sessions() ``` Returns text only. Lists sessions, their tabs, and which one is current. ## `close_session` {#close_session} Close an isolated session and discard its cookies and tabs. ```python close_session(name: str) ``` Returns text only. | Parameter | Type | Default | Description | | --- | --- | --- | --- | | `name` | `str` | required | The session to close (the default session cannot be closed) | Closes an isolated session and discards its cookies and tabs. The default session can't be closed. ## See also * [Use your own Chrome](/recipes/your-chrome) * [Share over HTTP](/guide/http) --- --- url: https://adityasasidhar.github.io/browsercontrol/reference/devtools.md description: >- Console logs, page errors, network requests, element inspection, performance, cookies, and viewport size. --- # DevTools What the browser's developer tools would show you. Logs and requests are captured per session from the moment a tab opens. | Tool | Does | Returns | | --- | --- | --- | | [`get_console_logs`](#get_console_logs) | Get browser console logs (errors, warnings, info, log messages). | text | | [`get_page_errors`](#get_page_errors) | Get JavaScript errors that occurred on the page. | text | | [`get_network_requests`](#get_network_requests) | Get captured network requests (API calls, resources, etc.). | text | | [`inspect_element`](#inspect_element) | Inspect an element to get its computed styles, dimensions, and properties. | text | | [`run_in_console`](#run_in_console) | Execute JavaScript code in the browser console and return the result. Useful for debugging, inspecting variables, or manipulating the page. | text + screenshot | | [`get_page_performance`](#get_page_performance) | Get page performance metrics (load time, Core Web Vitals). | text | | [`get_cookies`](#get_cookies) | Get all cookies for the current context. | text | | [`set_cookie`](#set_cookie) | Set a cookie. | text | | [`delete_cookie`](#delete_cookie) | Delete a cookie by name. Note: This deletes all cookies with this name across all domains in context. | text | | [`clear_cookies`](#clear_cookies) | Clear all cookies. | text | | [`set_viewport`](#set_viewport) | Set the browser viewport size. | text + screenshot | ## `get_console_logs` {#get_console_logs} Get browser console logs (errors, warnings, info, log messages). ```python get_console_logs(clear: bool = False) ``` Returns text only. | Parameter | Type | Default | Description | | --- | --- | --- | --- | | `clear` | `bool` | `False` | If True, clear the captured logs after returning them | The last 50 console messages with their level and source. `clear=True` empties the buffer after reading, so the next call shows only new messages. ```text Console Logs: [ERROR] Uncaught TypeError: items is undefined (http://localhost:3000/app.js:42:15) [WARNING] Each child in a list should have a unique "key" prop. ``` ## `get_page_errors` {#get_page_errors} Get JavaScript errors that occurred on the page. ```python get_page_errors() ``` Returns text only. Uncaught exceptions with the first line of their stack. ```text Page Errors: TypeError: Cannot read properties of undefined (reading 'map') at UserList (http://localhost:3000/src/UserList.tsx:14:22) ``` ## `get_network_requests` {#get_network_requests} Get captured network requests (API calls, resources, etc.). ```python get_network_requests(num_requests: int | None = None, clear: bool = False) ``` Returns text only. | Parameter | Type | Default | Description | | --- | --- | --- | --- | | `num_requests` | `int \| None` | `None` | Number of recent requests to return. Defaults to 30. | | `clear` | `bool` | `False` | If True, clear the captured requests after returning them | The most recent requests (30 by default), each with an `#id` to pass to [`get_request_details`](/reference/network#get_request_details). `clear=True` empties the buffer. ```text Network Requests: #12 GET https://api.example.com/users -> 200 (142ms) #13 POST https://api.example.com/login -> 401 (89ms) ``` ## `inspect_element` {#inspect_element} Inspect an element to get its computed styles, dimensions, and properties. ```python inspect_element(element_id: int) ``` Returns text only. | Parameter | Type | Default | Description | | --- | --- | --- | --- | | `element_id` | `int` | required | The number label of the element to inspect | Tag, id, classes, text, size, position, attributes, and key computed styles: what the browser actually rendered. Useful for "why is this invisible?" or "why did my click miss?". ## `run_in_console` {#run_in_console} Execute JavaScript code in the browser console and return the result. Useful for debugging, inspecting variables, or manipulating the page. ```python run_in_console(code: str) ``` Returns text and a fresh annotated screenshot. | Parameter | Type | Default | Description | | --- | --- | --- | --- | | `code` | `str` | required | JavaScript code to execute in the console | Evaluates JavaScript like the DevTools console, with structured error handling, and returns the result with a fresh screenshot. ## `get_page_performance` {#get_page_performance} Get page performance metrics (load time, Core Web Vitals). ```python get_page_performance() ``` Returns text only. Time to first byte, first contentful paint, DOMContentLoaded and load timings, resource count, and JS heap size. ## `get_cookies` {#get_cookies} Get all cookies for the current context. ```python get_cookies() ``` Returns text only. All cookies in the current session, with their domains. ## `set_cookie` {#set_cookie} Set a cookie. ```python set_cookie(name: str, value: str, domain: str | None = None, path: str = '/') ``` Returns text only. | Parameter | Type | Default | Description | | --- | --- | --- | --- | | `name` | `str` | required | Cookie name | | `value` | `str` | required | Cookie value | | `domain` | `str \| None` | `None` | Cookie domain (optional, defaults to current page domain) | | `path` | `str` | `"/"` | Cookie path (default: "/") | Sets a cookie. Without `domain`, it uses the current page's domain. ## `delete_cookie` {#delete_cookie} Delete a cookie by name. Note: This deletes all cookies with this name across all domains in context. ```python delete_cookie(name: str) ``` Returns text only. | Parameter | Type | Default | Description | | --- | --- | --- | --- | | `name` | `str` | required | — | Deletes every cookie with this name, across all domains in the session. ## `clear_cookies` {#clear_cookies} Clear all cookies. ```python clear_cookies() ``` Returns text only. Deletes every cookie in the session. ## `set_viewport` {#set_viewport} Set the browser viewport size. ```python set_viewport(width: int, height: int) ``` Returns text and a fresh annotated screenshot. | Parameter | Type | Default | Description | | --- | --- | --- | --- | | `width` | `int` | required | Width in pixels | | `height` | `int` | required | Height in pixels | Resizes the viewport immediately. For a phone with its user agent and touch input, use [`emulate_device`](/reference/emulation#emulate_device). ## See also * [Debug a web app](/recipes/debug) * [Network](/reference/network) --- --- url: https://adityasasidhar.github.io/browsercontrol/reference/network.md description: >- Mock or block requests, wait for a specific response, read full request details, and export HAR. --- # Network Control and inspect traffic. URL patterns accept a **substring** (`/api/users`), a **glob** (`**/api/*`), or a **regex** prefixed with `re:` (`re:/users/\d+$`). | Tool | Does | Returns | | --- | --- | --- | | [`mock_route`](#mock_route) | Answer matching requests with a canned response, or block them, in every tab. | text | | [`clear_mocks`](#clear_mocks) | Remove request mocks so requests reach the network again. | text | | [`wait_for_response`](#wait_for_response) | Wait for a network response whose URL matches, e.g. the API call a click triggered. | text + screenshot | | [`get_request_details`](#get_request_details) | Show one captured request in full: headers, POST data, response headers and body. | text | | [`export_har`](#export_har) | Save the captured network traffic (last 100 requests) as a HAR file. | text | ## `mock_route` {#mock_route} Answer matching requests with a canned response, or block them, in every tab. ```python mock_route(url_pattern: str, status: int = 200, body: str = '', content_type: str = 'application/json', headers: dict[str, str] | None = None, abort: bool = False) ``` Returns text only. | Parameter | Type | Default | Description | | --- | --- | --- | --- | | `url_pattern` | `str` | required | Substring of the URL, a glob like `**/api/users*`, or `re:` | | `status` | `int` | `200` | HTTP status to return (default 200) | | `body` | `str` | `""` | Response body (e.g. a JSON string) | | `content_type` | `str` | `"application/json"` | Content-Type of the body (default application/json) | | `headers` | `dict[str, str] \| None` | `None` | Extra response headers | | `abort` | `bool` | `False` | Fail matching requests with a network error instead of responding | Answers matching requests in every tab with a canned response, or fails them with `abort=True`. A second mock with the same pattern replaces the first. Mocks stay until [`clear_mocks`](#clear_mocks). ```text → mock_route("/api/cart", status=500, body='{"error": "boom"}') # an error state → mock_route("/api/items", body='{"items": []}') # an empty list → mock_route("**/analytics/**", abort=True) # block a tracker ``` ## `clear_mocks` {#clear_mocks} Remove request mocks so requests reach the network again. ```python clear_mocks(url_pattern: str | None = None) ``` Returns text only. | Parameter | Type | Default | Description | | --- | --- | --- | --- | | `url_pattern` | `str \| None` | `None` | The pattern given to mock_route; omit to remove every mock | Removes one mock by its pattern, or all of them with no argument. ## `wait_for_response` {#wait_for_response} Wait for a network response whose URL matches, e.g. the API call a click triggered. ```python wait_for_response(url_pattern: str, status: int | None = None, timeout_seconds: float = 10.0) ``` Returns text and a fresh annotated screenshot. | Parameter | Type | Default | Description | | --- | --- | --- | --- | | `url_pattern` | `str` | required | Substring of the URL, a glob like `**/api/save*`, or `re:` | | `status` | `int \| None` | `None` | Only accept this HTTP status | | `timeout_seconds` | `float` | `10.0` | Give up after this long (default 10) | Waits for a response whose URL matches and returns its `#id`, status, timing, and a body preview. Responses that arrived during the previous tool call count, so call it right after the action that sends the request. ```text → click(12) → wait_for_response("/api/save", status=200) Response received: #57 POST https://app.test/api/save -> 200 (84ms) Body: {"ok": true} ``` ## `get_request_details` {#get_request_details} Show one captured request in full: headers, POST data, response headers and body. ```python get_request_details(request_id: int, include_body: bool = True) ``` Returns text only. | Parameter | Type | Default | Description | | --- | --- | --- | --- | | `request_id` | `int` | required | The #id shown by get_network_requests or wait_for_response | | `include_body` | `bool` | `True` | Include the response body (text, truncated; binary as base64) | Request headers, POST data, response headers, and the response body (text up to 10,000 characters, binary as base64) for an `#id` from `get_network_requests` or `wait_for_response`. Bodies are read on demand and may be gone once the page has navigated away. ## `export_har` {#export_har} Save the captured network traffic (last 100 requests) as a HAR file. ```python export_har(name: str = '', include_bodies: bool = False) ``` Returns text only. | Parameter | Type | Default | Description | | --- | --- | --- | --- | | `name` | `str` | `""` | File name without extension (default: timestamp) | | `include_bodies` | `bool` | `False` | Also save response bodies (up to 1MB each) | Writes the captured requests (the last 100) to `/.har`. Open it in Chrome DevTools (Network → Import HAR) or any HAR viewer. `include_bodies=True` adds response bodies. ## See also * [Test edge states](/recipes/edge-states) * [Debug a web app](/recipes/debug) --- --- url: https://adityasasidhar.github.io/browsercontrol/reference/emulation.md description: Devices, dark mode, timezones, locations, and network throttling. --- # Emulation Settings apply to every tab in the session, including tabs opened later, and stay until `reset_emulation()`. | Tool | Does | Returns | | --- | --- | --- | | [`list_devices`](#list_devices) | List device names accepted by emulate_device and create_session. | text | | [`emulate_device`](#emulate_device) | Emulate a phone or tablet's screen size, user agent, and touch input. | text + screenshot | | [`set_color_scheme`](#set_color_scheme) | Emulate prefers-color-scheme to check dark or light mode. | text + screenshot | | [`set_timezone`](#set_timezone) | Make pages see a different timezone (Date, Intl). | text | | [`set_geolocation`](#set_geolocation) | Report a fake location to sites, and grant them the geolocation permission. | text | | [`throttle_network`](#throttle_network) | Slow the network down or take it offline, to test loading and offline states. | text | | [`reset_emulation`](#reset_emulation) | Undo all emulation: device, geolocation, timezone, color scheme, and throttling. | text + screenshot | ## `list_devices` {#list_devices} List device names accepted by emulate_device and create_session. ```python list_devices(contains: str = '') ``` Returns text only. | Parameter | Type | Default | Description | | --- | --- | --- | --- | | `contains` | `str` | `""` | Only names containing this (case-insensitive), e.g. "iphone" | Playwright's device catalog: about 140 phones, tablets, and desktops. `contains` filters by name. ## `emulate_device` {#emulate_device} Emulate a phone or tablet's screen size, user agent, and touch input. ```python emulate_device(name: str) ``` Returns text and a fresh annotated screenshot. | Parameter | Type | Default | Description | | --- | --- | --- | --- | | `name` | `str` | required | A device from list_devices(), e.g. "iPhone 13" or "Pixel 7" | Sets the device's screen size, user agent, and touch input, then reloads. `"none"` returns to the desktop viewport. Pixel ratio and the mobile layout viewport need a new context: use `create_session(name, device=…)` for a fully faithful device. ## `set_color_scheme` {#set_color_scheme} Emulate prefers-color-scheme to check dark or light mode. ```python set_color_scheme(scheme: str = 'dark') ``` Returns text and a fresh annotated screenshot. | Parameter | Type | Default | Description | | --- | --- | --- | --- | | `scheme` | `str` | `"dark"` | "dark", "light", or "no-preference" | Sets `prefers-color-scheme` to `dark`, `light`, or `no-preference`. ## `set_timezone` {#set_timezone} Make pages see a different timezone (Date, Intl). ```python set_timezone(timezone_id: str) ``` Returns text only. | Parameter | Type | Default | Description | | --- | --- | --- | --- | | `timezone_id` | `str` | required | IANA name such as "America/New_York" or "Asia/Tokyo"; "" resets | IANA names such as `America/New_York` or `Asia/Tokyo`. `""` resets. ## `set_geolocation` {#set_geolocation} Report a fake location to sites, and grant them the geolocation permission. ```python set_geolocation(latitude: float, longitude: float, accuracy: float = 10.0) ``` Returns text only. | Parameter | Type | Default | Description | | --- | --- | --- | --- | | `latitude` | `float` | required | Latitude in degrees, e.g. 51.5074 | | `longitude` | `float` | required | Longitude in degrees, e.g. -0.1278 | | `accuracy` | `float` | `10.0` | Accuracy radius in meters (default 10) | Reports a fake location to sites and grants them the geolocation permission. ## `throttle_network` {#throttle_network} Slow the network down or take it offline, to test loading and offline states. ```python throttle_network(profile: str = 'slow-3g') ``` Returns text only. | Parameter | Type | Default | Description | | --- | --- | --- | --- | | `profile` | `str` | `"slow-3g"` | "slow-3g", "fast-3g", "4g", "offline", or "none" to remove throttling | `slow-3g`, `fast-3g`, `4g` (Chrome DevTools' presets), `offline`, or `none` to restore the network. ## `reset_emulation` {#reset_emulation} Undo all emulation: device, geolocation, timezone, color scheme, and throttling. ```python reset_emulation() ``` Returns text and a fresh annotated screenshot. Undoes device, geolocation, timezone, color scheme, and throttling at once. ## See also * [Mobile & dark mode](/recipes/responsive) * [Test edge states](/recipes/edge-states) --- --- url: https://adityasasidhar.github.io/browsercontrol/reference/recording.md description: Playwright traces, snapshots, and exporting a session as a Playwright test. --- # Recording Keep a record of what happened. Traces go to `~/.browsercontrol/recordings`, snapshots to `~/.browsercontrol/snapshots`, and tests to `~/.browsercontrol/generated_tests`; see [Configuration](/reference/configuration#paths) to move them. | Tool | Does | Returns | | --- | --- | --- | | [`start_recording`](#start_recording) | Start recording the browser session as a Playwright trace. The trace will be saved when stop_recording is called. Also restarts the action log, so export_test() afterwards covers exactly this recording. | text | | [`stop_recording`](#stop_recording) | Stop recording and save the session trace. | text | | [`export_test`](#export_test) | Turn the actions taken so far into a replayable Playwright test file. | text | | [`take_snapshot`](#take_snapshot) | Take a named snapshot (screenshot + HTML) for later reference. | text | | [`list_recordings`](#list_recordings) | List all saved recordings and snapshots. | text | ## `start_recording` {#start_recording} Start recording the browser session as a Playwright trace. The trace will be saved when stop_recording is called. Also restarts the action log, so export_test() afterwards covers exactly this recording. ```python start_recording(name: str = '') ``` Returns text only. | Parameter | Type | Default | Description | | --- | --- | --- | --- | | `name` | `str` | `""` | Optional name for the recording (default: timestamp) | Starts a Playwright trace and restarts the action log, so `export_test` afterwards covers exactly this recording. Without a name, a timestamp is used. ```text → start_recording("checkout") Recording started: checkout.zip Call stop_recording() when done. ``` ## `stop_recording` {#stop_recording} Stop recording and save the session trace. ```python stop_recording() ``` Returns text only. Saves the trace and returns its path and the command to open it. ```text Recording saved: /home/me/.browsercontrol/recordings/checkout.zip View with: npx playwright show-trace /home/me/.browsercontrol/recordings/checkout.zip ``` ## `export_test` {#export_test} Turn the actions taken so far into a replayable Playwright test file. ```python export_test(name: str = '', language: str = 'python', clear: bool = False) ``` Returns text only. | Parameter | Type | Default | Description | | --- | --- | --- | --- | | `name` | `str` | `""` | Test name and file name (default: timestamp) | | `language` | `str` | `"python"` | "python" (pytest-playwright) or "typescript" (@playwright/test) | | `clear` | `bool` | `False` | Empty the action log afterwards, to start the next test fresh | Writes the actions so far (since the session started, or since `start_recording`) as a test file, and returns its path, the command to run it, and the code. `language` is `python` (pytest-playwright, `test_.py`) or `typescript` (`@playwright/test`, `.spec.ts`). `clear=True` empties the action log afterwards. ```python def test_checkout(page: Page) -> None: page.goto("https://shop.test/") page.get_by_role("textbox", name="Email", exact=True).fill("ada@example.com") page.get_by_label("Password", exact=True).fill(os.environ["BC_SECRET_1"]) page.once("dialog", lambda dialog: dialog.accept()) page.get_by_role("button", name="Pay", exact=True).click() expect(page.get_by_text("Order confirmed").first).to_be_visible() ``` Elements are located by test id, role and name, label, placeholder, or text, falling back to a CSS path, each checked against the live page. Covers navigation, clicks, typing, keys, selects, checkboxes, uploads, drags, scrolls, waits for text, dialog answers, and request mocks. Typed passwords become `BC_SECRET_n` environment variables. Review the file before committing. ## `take_snapshot` {#take_snapshot} Take a named snapshot (screenshot + HTML) for later reference. ```python take_snapshot(name: str = '') ``` Returns text only. | Parameter | Type | Default | Description | | --- | --- | --- | --- | | `name` | `str` | `""` | Optional name for the snapshot (default: timestamp) | Saves a PNG screenshot and the page's HTML (with BrowserControl's markers removed) under the given name. Without a name, a timestamp is used. ## `list_recordings` {#list_recordings} List all saved recordings and snapshots. ```python list_recordings() ``` Returns text only. Lists recent traces and snapshots with their paths. ## See also * [Record & export tests](/recipes/record-tests) --- --- url: https://adityasasidhar.github.io/browsercontrol/reference/resources.md description: >- The browser:// MCP resources that expose captured console messages, network traffic, errors, tabs, downloads, sessions, and the action log as JSON. --- # MCP resources Besides tools, BrowserControl publishes what it has captured as read-only [MCP resources](https://modelcontextprotocol.io/docs/concepts/resources). Reading one costs no tool call and returns no screenshot, which suits clients that can attach resources to a conversation or poll them. | URI | Contents | | --- | --- | | `browser://console` | Captured console messages | | `browser://network` | The last 100 network requests, with headers and status | | `browser://network/{request_id}` | One request by its `#id` | | `browser://errors` | Uncaught page errors | | `browser://tabs` | Open tabs | | `browser://downloads` | Downloaded files and where they were saved | | `browser://actions` | The action log that [`export_test`](/reference/recording#export_test) turns into a test | | `browser://sessions` | Sessions and their tabs | Every resource is JSON (`application/json`) and reads the session of the client asking, so with several clients on one server each sees its own data. Reading a resource never starts the browser. Internal fields (such as the live response object behind a request) are left out, so what you read is plain data. ## Tools or resources? They expose the same data. Tools return it as text formatted for the model and take options like `clear=True`; resources return the raw JSON. Use whichever your client handles better. --- --- url: https://adityasasidhar.github.io/browsercontrol/reference/configuration.md description: >- Every BrowserControl environment variable and command-line flag, with defaults and examples. --- # Configuration BrowserControl reads its settings from environment variables once, at startup. Change a value, then restart the server. ## At a glance | Variable | Default | What it does | | --- | --- | --- | | [`BROWSER_HEADLESS`](#browser_headless) | `false` | `true` hides the browser window. | | [`BROWSER_VIEWPORT_WIDTH`](#viewport) | `1280` | Viewport width in pixels. | | [`BROWSER_VIEWPORT_HEIGHT`](#viewport) | `720` | Viewport height in pixels. | | [`BROWSER_TIMEOUT`](#browser_timeout) | `30000` | Navigation timeout, in ms. | | [`BROWSER_SETTLE_TIMEOUT`](#browser_settle_timeout) | `3000` | How long to wait for the page to settle after each action, in ms. | | [`BROWSER_USER_DATA_DIR`](#browser_user_data_dir) | `~/.browsercontrol/user_data` | The persistent browser profile. | | [`BROWSER_EXECUTABLE_PATH`](#browser_executable_path) | — | A specific Chrome or Chromium binary. | | [`BROWSER_EXTENSION_PATH`](#browser_extension_path) | — | An unpacked extension to load. | | [`BROWSER_CDP_URL`](#browser_cdp_url) | — | Attach to a running Chrome instead of launching one. | | [`BROWSER_RECORDINGS_DIR`](#paths) | beside the profile | Traces and HAR files. | | [`BROWSER_SNAPSHOTS_DIR`](#paths) | beside the profile | Snapshots. | | [`BROWSER_DOWNLOADS_DIR`](#paths) | beside the profile | Downloads. | | [`BROWSER_GENERATED_TESTS_DIR`](#paths) | beside the profile | Tests written by `export_test`. | | [`BROWSER_TRANSPORT`](#transport) | `stdio` | `stdio`, `http`, or `sse`. | | [`BROWSER_HOST`](#transport) | `127.0.0.1` | HTTP bind address. | | [`BROWSER_PORT`](#transport) | `8000` | HTTP port. | | [`BROWSER_ISOLATE_CLIENTS`](#browser_isolate_clients) | `false` | One isolated session per MCP client. | | [`LOG_LEVEL`](#log_level) | `INFO` | `DEBUG`, `INFO`, `WARNING`, or `ERROR`. | ## Setting them In an MCP client, add an `env` object to the server entry: ```json { "mcpServers": { "browsercontrol": { "command": "uvx", "args": ["browsercontrol"], "env": { "BROWSER_HEADLESS": "true", "BROWSER_VIEWPORT_WIDTH": "1440", "BROWSER_VIEWPORT_HEIGHT": "900" } } } } ``` In a shell: ::: code-group ```bash [bash / zsh] BROWSER_HEADLESS=true browsercontrol ``` ```fish [fish] env BROWSER_HEADLESS=true browsercontrol ``` ```powershell [PowerShell] $env:BROWSER_HEADLESS = "true"; browsercontrol ``` ::: ## Command-line flags ```text browsercontrol [--transport {stdio,http,sse}] [--host HOST] [--port PORT] [--isolate-clients] ``` Flags override the matching environment variables. Run `browsercontrol --help` for the list. ## Browser ### `BROWSER_HEADLESS` {#browser_headless} `false` by default: a visible window, so you can watch the agent work. Set `true` for no window, which suits servers and CI. Without a display (a server, CI), a visible browser needs a virtual one such as `xvfb-run browsercontrol`, or set `BROWSER_HEADLESS=true`. In the visible window, an arrow follows the agent's mouse actions and highlights clicks with a brief ring. The arrow disappears after mouse activity stops and is hidden in tool screenshots. ### `BROWSER_VIEWPORT_WIDTH` and `BROWSER_VIEWPORT_HEIGHT` {#viewport} The starting viewport, `1280` × `720` by default. Agents can change it while running with [`set_viewport`](/reference/devtools#set_viewport) or [`emulate_device`](/reference/emulation#emulate_device). ### `BROWSER_TIMEOUT` {#browser_timeout} How long a navigation may take before it fails, in milliseconds. Default `30000`. ### `BROWSER_SETTLE_TIMEOUT` {#browser_settle_timeout} The budget, in milliseconds, for [settling](/concepts/settling) after each action: load, network quiet, DOM quiet. Default `3000`. Lower it on static sites for speed; raise it for slow single-page apps. Running out of budget never fails an action. ### `BROWSER_USER_DATA_DIR` {#browser_user_data_dir} The persistent profile: cookies, `localStorage`, history, extensions. Default `~/.browsercontrol/user_data`. Only one running server can use a profile, so give each server its own. ### `BROWSER_EXECUTABLE_PATH` {#browser_executable_path} A Chrome or Chromium binary to drive. Unset, BrowserControl tries Playwright's Chromium, then an installed Google Chrome (with a separate profile, the profile directory with `-chrome` appended), then downloads Chromium. Set it when Playwright has no Chromium build for your platform: ```bash BROWSER_EXECUTABLE_PATH=/usr/bin/google-chrome browsercontrol ``` With this set, BrowserControl won't download Chromium if the launch fails. The binary you named is the one to fix. ### `BROWSER_EXTENSION_PATH` {#browser_extension_path} The directory of an unpacked Chromium extension to load. Automatic browser selection then uses Playwright's Chromium. ### `BROWSER_CDP_URL` {#browser_cdp_url} Attach to a Chrome already running with remote debugging, instead of launching a browser, so the agent uses that Chrome's signed-in sites. The profile, executable, and extension settings are ignored in this mode. See [Use your own Chrome](/recipes/your-chrome). ```bash BROWSER_CDP_URL=http://localhost:9222 browsercontrol ``` ## Files {#paths} | Variable | Default | Holds | | --- | --- | --- | | `BROWSER_RECORDINGS_DIR` | `~/.browsercontrol/recordings` | Playwright traces and HAR exports | | `BROWSER_SNAPSHOTS_DIR` | `~/.browsercontrol/snapshots` | `take_snapshot` PNG and HTML | | `BROWSER_DOWNLOADS_DIR` | `~/.browsercontrol/downloads` | Downloads (never overwritten) | | `BROWSER_GENERATED_TESTS_DIR` | `~/.browsercontrol/generated_tests` | `export_test` output | Each default sits beside the profile directory, so moving `BROWSER_USER_DATA_DIR` moves them too unless you set them yourself. ## Server ### `BROWSER_TRANSPORT`, `BROWSER_HOST`, `BROWSER_PORT` {#transport} `stdio` (the default) is for clients that launch the server themselves. `http` serves Streamable HTTP at `http://BROWSER_HOST:BROWSER_PORT/mcp` so several clients can share one browser; `sse` is the older HTTP transport. The flags `--transport`, `--host`, and `--port` do the same. See [Share over HTTP](/guide/http). ::: danger No authentication Anyone who can reach the port controls the browser and its signed-in sessions. The default host is `127.0.0.1`, and the server warns if you bind anywhere else. ::: ### `BROWSER_ISOLATE_CLIENTS` {#browser_isolate_clients} `true` (or `--isolate-clients`) gives every MCP client its own isolated session on its first tool call, so agents sharing a server never see each other's cookies, tabs, or traffic. ### `LOG_LEVEL` {#log_level} How much the server logs: `DEBUG`, `INFO` (default), `WARNING`, or `ERROR`. Logs go to stderr, which most clients show in their MCP log. `DEBUG` is the level to attach to a bug report. --- --- url: https://adityasasidhar.github.io/browsercontrol/help/troubleshooting.md description: >- Fixes for BrowserControl problems with connecting, launching Chromium, element numbers, uploads, localhost, profiles, and recordings. --- # Troubleshooting | Symptom | Go to | | --- | --- | | The client doesn't list BrowserControl's tools | [The client can't find BrowserControl](#the-client-cant-find-browsercontrol) | | Chromium fails to start | [Chromium won't launch](#chromium-won-t-launch) | | "Element 7 is stale" or "not found" | [Element numbers stop working](#element-numbers-stop-working) | | A visible button has no number | [Something on screen has no number](#something-on-screen-has-no-number) | | The click lands but nothing happens | [A click does nothing](#a-click-does-nothing) | | A file won't upload | [Uploads](#uploads) | | `localhost` refuses to connect | [Localhost](#localhost) | | Logins don't stick | [Profiles](#profiles) | ## Connecting ### The client can't find BrowserControl {#the-client-cant-find-browsercontrol} 1. **Open the client's MCP log.** It shows the command it ran and why it failed. 2. **Check the command exists.** Desktop apps often have a shorter `PATH` than your terminal. Run `which uvx` (or `which browsercontrol`) and put that full path in the config. 3. **Check the JSON.** A trailing comma or a missing brace makes most clients skip the whole file. 4. **Reload.** Most clients read MCP config only at startup. ### The profile is already in use Only one BrowserControl can use a browser profile at a time. If two clients each launch their own server, the second fails. Either give each its own [`BROWSER_USER_DATA_DIR`](/reference/configuration#browser_user_data_dir), or run one server [over HTTP](/guide/http) and point both clients at it. ## Launching ### Chromium won't launch {#chromium-won-t-launch} BrowserControl downloads Chromium if it can't find a browser. If that fails, install it yourself: ```bash python -m playwright install chromium ``` On Linux, add the system libraries Chromium needs: ```bash python -m playwright install chromium --with-deps ``` If Playwright has no build for your distribution, point BrowserControl at a browser you have: ```bash BROWSER_EXECUTABLE_PATH=/usr/bin/google-chrome browsercontrol ``` ### It won't start on a server or in CI BrowserControl opens a visible window by default, which needs a display. On a server or in CI, set `BROWSER_HEADLESS=true`, or run it under a virtual display: `xvfb-run browsercontrol`. ### Install fails on old Python BrowserControl needs Python 3.11 or newer. `python --version` shows yours; `uv python install 3.12` installs a newer one, and `uvx` picks a suitable Python on its own. ## Elements ### Element numbers stop working Numbers belong to the screenshot they came from. After any action, read the number from the **latest** response. * `Element 7 is stale (it moved)` (or *no longer on the page*, *no longer visible*, *its content changed*): the page changed after the screenshot. Nothing was clicked. Use the fresh screenshot that came with the error. * `Element 42 not found. Valid IDs: [...]`: that number isn't in the current map at all. Inside [`act`](/reference/interaction#act), every number refers to the map from before the call, so a step after a navigation fails as stale. Put navigation last. ### Something on screen has no number Something covers it: a cookie banner, a modal, a sticky header, a chat widget. Close the overlay, then look again. If it's simply off-screen, `find("its text")` scrolls to it. ### A click does nothing * The element may be **disabled**: the list shows `(disabled)`, and the tool says so. Something else (a required field) usually comes first. * The page may still be busy. Check the result with `wait_for(text=…)` rather than assuming. * It may be a custom control that reacts to something else. `inspect_element(id)` shows what it is; `get_console_logs()` shows errors it raised. ### `select_option` fails on a dropdown `select_option` works on native `