BrowserTrace: local trace viewer for failed Stagehand runs

[aaronlab]

I built BrowserTrace, a small MIT-licensed local trace viewer for failed AI browser-agent runs, and it includes a lightweight Stagehand wrapper.

Why I am sharing it here: when a Stagehand script fails, the useful debugging context is often split across browser state, act / extract / observe calls, model output, screenshots, URLs, and the final exception. BrowserTrace records those calls as a local timeline so the failed step is easier to inspect.

Minimal shape:

from browsertrace import Tracer
from browsertrace.integrations.stagehand import wrap_stagehand

tracer = Tracer()

with tracer.run("stagehand run") as run:
    page = wrap_stagehand(stagehand.page, run)
    await page.goto("https://example.com")
    await page.act("click the checkout button")
    result = await page.extract("get the confirmation message")

The wrapper keeps Stagehand optional and records high-level calls such as goto, act, extract, observe, and click when those methods exist on the wrapped page. BrowserTrace keeps traces local by default and can export a standalone public-safe HTML trace that omits prompts/model I/O, screenshots, and URLs.

Quick no-API trial path from PyPI:

uvx --from "browsertrace[ui]" browsertrace doctor
uvx --from "browsertrace[ui]" browsertrace demo
uvx --from "browsertrace[ui]" browsertrace

Persistent install from PyPI:

pip install "browsertrace[ui]"

Repo: https://github.com/aaronlab/browsertrace
PyPI: https://pypi.org/project/browsertrace/
Stagehand guide: https://aaronlab.github.io/browsertrace/stagehand-debugging.html

Feedback I am looking for from Stagehand users: when a run fails, which artifacts matter most: observe output, selected elements, extracted text, agent state, action retries, screenshots, model output, task prompt, or something else?

No star/upvote ask; I am trying to make the Stagehand failure report useful before expanding the adapter.