# BrowserTrace

BrowserTrace is an MIT-licensed local flight recorder for AI browser agents.
It records browser-agent runs as step timelines with screenshots, URLs, actions,
model input/output, status, and errors.

Use BrowserTrace when debugging Browser Use, Stagehand, Playwright + LLM scripts,
Skyvern-style workflows, or custom computer-use agents where logs are not enough
to explain why a browser run failed.

## Important Links

- GitHub repository: https://github.com/aaronlab/browsertrace
- Live demo page: https://aaronlab.github.io/browsertrace/
- Raw exported trace: https://aaronlab.github.io/browsertrace/trace.html
- Debugging walkthrough: https://aaronlab.github.io/browsertrace/debug-browser-agent-failure.html
- Comparison guide: https://aaronlab.github.io/browsertrace/compare-browser-agent-debugging.html
- Browser Use guide: https://aaronlab.github.io/browsertrace/browser-use-debugging.html
- Stagehand guide: https://aaronlab.github.io/browsertrace/stagehand-debugging.html
- Skyvern guide: https://aaronlab.github.io/browsertrace/skyvern-debugging.html
- Playwright + LLM guide: https://aaronlab.github.io/browsertrace/playwright-llm-debugging.html
- Computer-use agent guide: https://aaronlab.github.io/browsertrace/computer-use-agent-debugging.html
- Integrations: https://aaronlab.github.io/browsertrace/integrations.html
- Examples: https://github.com/aaronlab/browsertrace/tree/main/examples
- Launch kit: https://aaronlab.github.io/browsertrace/launch/
- Press kit: https://aaronlab.github.io/browsertrace/launch/press-kit.md
- Release: https://github.com/aaronlab/browsertrace/releases/tag/v0.1.14
- Public-safe demo export: https://github.com/aaronlab/browsertrace/releases/download/v0.1.14/browsertrace-demo-public.html
- Launch discussion: https://github.com/aaronlab/browsertrace/discussions/6
- Good first issue: https://github.com/aaronlab/browsertrace/issues/34
- Integration request: https://github.com/aaronlab/browsertrace/issues/new?template=integration_request.yml
- Playwright + LLM feedback: https://github.com/aaronlab/browsertrace/issues/12
- Custom computer-use feedback: https://github.com/aaronlab/browsertrace/issues/3

## Core Capabilities

- Capture screenshots and URLs at each agent step.
- Store action labels, model inputs, model outputs, status, and error messages.
- Inspect runs in a local web UI.
- Export a self-contained HTML trace for sharing with teammates or issues.
- Use `browsertrace export <run_id> --public -o public.html` before public
  sharing to omit prompt/model I/O, screenshots, and URLs.
- Run a deterministic no-API-key failure demo for quick evaluation.

## Quickstart

```bash
uvx --from "browsertrace[ui] @ git+https://github.com/aaronlab/browsertrace@v0.1.14" browsertrace doctor
uvx --from "browsertrace[ui] @ git+https://github.com/aaronlab/browsertrace@v0.1.14" browsertrace demo
uvx --from "browsertrace[ui] @ git+https://github.com/aaronlab/browsertrace@v0.1.14" browsertrace list
uvx --from "browsertrace[ui] @ git+https://github.com/aaronlab/browsertrace@v0.1.14" browsertrace
```

Persistent install from the GitHub release tag before PyPI publishing is
enabled:

```bash
pip install "browsertrace[ui] @ git+https://github.com/aaronlab/browsertrace@v0.1.14"
browsertrace doctor
browsertrace demo
browsertrace
```

`browsertrace doctor` prints local install and trace-store status without
requiring an existing database.

Then open `http://127.0.0.1:3000` and inspect the failed checkout-agent run.

## Positioning

BrowserTrace is not a hosted observability platform. It is a local-first,
open-source debugging tool for the browser state and model decisions around
AI browser-agent failures.