BrowserTrace is a local replay debugger designed specifically for troubleshooting failures in browser automation agents such as Browser Use. When an agent fails, logs can only show what code was executed, but cannot show what the agent actually saw, what it clicked, what it returned, or the cause of the first failing step. BrowserTrace is designed precisely to fill this gap.
Main capabilities: It records each Browser Use step as a local timeline, including screenshots, URLs, actions, model inputs, model outputs, status, and errors. Users can open the local UI and jump directly to the failed browser state. When the same task has both a failed run and a known successful run recorded, browsertrace compare <failed_run_id> <success_run_id> can be used to pinpoint the first action, URL, status, or error where they diverge. It is positioned as a local debugging artifact channel rather than a prompt history record: screenshots, URLs, and model I/O are all kept in the local trace store, and browsertrace export --public omits prompts/model I/O, screenshots, and URLs during export, making it convenient to publicly submit bug reports.
Supported integrations: Browser Use is the primary path. Stagehand, Skyvern, Playwright + LLM scripts, and custom computer-use agents are supported as secondary integrations. The specific Browser Use failure modes covered include new-tab desynchronization, multi-step form drift, local HTML upload navigation errors, remote CDP hangs, and icon-only target mismatches, among others; the secondary integration modes cover Stagehand semantic validation boundaries, Skyvern VNC/CDP debugging integration, and Skyvern multi-session VNC control drift.
Usage: The project is published on PyPI (https://pypi.org/project/browsertrace/），可从 Install from PyPI, requires Python 3.11+. The fastest no-install way to try it is uvx, for a persistent install use pip install, and you can install the [ui] extra for the local Web UI; an SDK-only install is enough for trace capture integration as well as terminal commands such as browsertrace list, browsertrace show, and browsertrace export. Common local commands include: browsertrace doctor for checking installation and trace storage status, browsertrace doctor --json outputs status as JSON; browsertrace demo runs without an API key or external services and generates a deterministic trace; browsertrace list shows recent run IDs, timestamps, and status, and supports --json, --status, and --limit filters; browsertrace show <run_id> views a run's step timeline in the terminal and supports --json; browsertrace export <run_id> --public -o public.html generates a publicly safe, self-contained HTML report; browsertrace compare supports --json for automation. By default local traces are stored in ~/.browsertrace/, and isolated storage can be used via BROWSERTRACE_HOME; the local UI binds to 127.0.0.1 by default, and the port can be changed with BROWSERTRACE_PORT. When used in your own code, it supports the decorator @trace (works for both sync and async functions), the Playwright shortcuts run.snapshot(page, action=...) and run.snapshot_sync(page, ...) (synchronous Playwright), the context manager (when a with block raises an error, the run is marked as failed and the error is recorded on the last step), and adapter integration methods such as Browser Use, Stagehand, and Skyvern.
Use cases: Suitable for developers who need to debug failed steps in browser automation agents, including troubleshooting Browser Use run failures, comparing failed and successful runs, and generating HTML exports without sensitive information for public bug reports. It is also suitable for use in pytest and CI (such as GitHub Actions, GitLab CI) to generate public.html as a build artifact; BrowserTrace itself does not upload traces.
Limitations: BrowserTrace is a local debugging tool; it does not provide a cloud service and does not automatically upload any traces; public exports omit model I/O, screenshots, and URLs, --redact only omits model I/O, and --public also omits screenshots and URLs. The Python version requirement is 3.11+. Some features (such as the UI) require installing the additional [ui] dependencies. This material does not provide pricing, cost, or information about additional platform support, and no related content is currently available.
