Launch feedback: what browser-agent failures should BrowserTrace capture?

[aaronlab]

BrowserTrace is in its first public launch-ready shape. This issue collects workflow feedback from people building browser agents, not stars/upvotes.

Browser Use is the primary feedback path now. Stagehand, Skyvern, Playwright + LLM, and computer-use workflows are still supported as secondary integrations.

Try first:

• Live demo: https://aaronlab.github.io/browsertrace/
• Browser Use guide: https://aaronlab.github.io/browsertrace/browser-use-debugging.html
• Debugging walkthrough: https://aaronlab.github.io/browsertrace/debug-browser-agent-failure.html
• Failure patterns: https://aaronlab.github.io/browsertrace/browser-agent-failure-patterns.html
• PyPI: https://pypi.org/project/browsertrace/
• Release: https://github.com/aaronlab/browsertrace/releases/tag/v0.1.19
• Public-safe demo export: https://github.com/aaronlab/browsertrace/releases/download/v0.1.19/browsertrace-demo-public.html

Current demo story:

Browser Use tries to upload file:///tmp/browsertrace-report.html, navigates to the local file path instead, and the upload preview never appears. BrowserTrace replays the screenshot, URL, action, model output, status, and first red step so the failure is inspectable.

Current comparison path:

browsertrace compare <failed_run_id> <success_run_id>
browsertrace compare <failed_run_id> <success_run_id> --json

Fastest local path from PyPI:

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

Persistent install from PyPI:

pip install "browsertrace[ui]"
browsertrace doctor
browsertrace demo
browsertrace

For public-safe trace sharing:

browsertrace export <run_id> --public -o public.html

--public omits prompt/model I/O, screenshots, and URLs from the standalone HTML export. For security-sensitive reports or changes, or anything that includes private trace data, use the Security Policy before sharing details publicly: https://github.com/aaronlab/browsertrace/blob/main/SECURITY.md

If you build with Browser Use, Stagehand, Skyvern, Playwright + LLMs, or computer-use stacks, please share:

• What failed run was hardest for you to debug?
• What data did you wish you had captured?
• Which framework/runtime should BrowserTrace support better first?
• Would a portable HTML export be enough for sharing failures, or do you need hosted links?
• Which fields should be redacted before public sharing?
• For failed-vs-good Browser Use runs, which final-result fields should comparison separate: extracted content, tool output, final result, retry/repair attempts, or one normalized summary?

Concrete traces, screenshots, sanitized snippets, and anonymized examples are especially useful.

For small docs fixes while discussing feedback, use the current good-first issue queue and First PR Recipe:

• good first issue Good for newcomers
• Current good-first issue: Docs: add browsertrace compare expected-output example #371
• https://github.com/aaronlab/browsertrace/blob/main/CONTRIBUTING.md#first-pr-recipe

[aaronlab]

Historical note (2026-05-11): this earlier launch update is superseded by the PyPI release v0.1.16.
Current quick trial path: uvx --from "browsertrace[ui]" browsertrace doctor, uvx --from "browsertrace[ui]" browsertrace demo, then uvx --from "browsertrace[ui]" browsertrace.
Persistent install: pip install "browsertrace[ui]". Current release: https://github.com/aaronlab/browsertrace/releases/tag/v0.1.16.

Update for local trials before PyPI publishing is enabled:

uvx --from "browsertrace[ui] @ git+https://github.com/aaronlab/browsertrace@v0.1.10" browsertrace demo
uvx --from "browsertrace[ui] @ git+https://github.com/aaronlab/browsertrace@v0.1.10" browsertrace

The live walkthrough is still the fastest first look: https://aaronlab.github.io/browsertrace/debug-browser-agent-failure.html

Feedback that is most useful right now: which fields should BrowserTrace capture first for Browser Use, Stagehand, Skyvern, or Playwright + LLM runs?

[aaronlab]

Computer-use feedback path added:

• Guide: https://aaronlab.github.io/browsertrace/computer-use-agent-debugging.html
• Runnable no-browser example: python examples/computer_use_loop_example.py
• Examples matrix: https://github.com/aaronlab/browsertrace/tree/main/examples

The new example records a generic observe-decide-act loop and marks the model-selected click as the failed step. This should make feedback from custom computer-use/browser-agent builders more concrete: which observation, decision, action, and redaction fields should be captured by default?

[aaronlab]

Historical note (2026-05-11): this earlier launch update is superseded by the PyPI release v0.1.16.
Current quick trial path: uvx --from "browsertrace[ui]" browsertrace doctor, uvx --from "browsertrace[ui]" browsertrace demo, then uvx --from "browsertrace[ui]" browsertrace.
Persistent install: pip install "browsertrace[ui]". Current release: https://github.com/aaronlab/browsertrace/releases/tag/v0.1.16.

Launch/status update: v0.1.15 is published with Browser Use run-hook support.\n\nRelease: https://github.com/aaronlab/browsertrace/releases/tag/v0.1.15\nBrowser Use guide: https://aaronlab.github.io/browsertrace/browser-use-debugging.html\n\nThis matters for Browser Use users whose apps pass lifecycle hooks directly to agent.run(on_step_start=..., on_step_end=...): BrowserTrace now exposes create_run_hooks(...) for that path, while keeping the existing attach_tracer(agent, ...) adapter for callback-style agents.\n\nCurrent verified trial path before PyPI publishing:\n\nbash\nuvx --from "browsertrace[ui] @ git+https://github.com/aaronlab/browsertrace@v0.1.15" browsertrace doctor\nuvx --from "browsertrace[ui] @ git+https://github.com/aaronlab/browsertrace@v0.1.15" browsertrace demo\nuvx --from "browsertrace[ui] @ git+https://github.com/aaronlab/browsertrace@v0.1.15" browsertrace\n\n\nFeedback still wanted: for Browser Use failures, which fields are most useful at failure time: task text, memory, extracted content, selected elements, retry state, screenshots, model actions, or final result?

[aaronlab]

Launch/status update: BrowserTrace is now published on PyPI as browsertrace==0.1.16.

Current quick trial path:

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

Persistent install path:

pip install "browsertrace[ui]"
browsertrace doctor
browsertrace demo
browsertrace

Useful links:

• PyPI: https://pypi.org/project/browsertrace/
• Release: https://github.com/aaronlab/browsertrace/releases/tag/v0.1.16
• Live demo: https://aaronlab.github.io/browsertrace/
• Public-safe demo export: https://github.com/aaronlab/browsertrace/releases/download/v0.1.16/browsertrace-demo-public.html

Feedback still wanted: for Browser Use, Stagehand, Skyvern, Playwright + LLM, or custom computer-use failures, which browser state or model-decision fields are missing when you debug a failed run? No stars/upvotes requested; workflow feedback is the useful thing.

[aaronlab]

Launch/status update (2026-05-11): BrowserTrace is now current at browsertrace==0.1.17.

Quick trial path:

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

Persistent install:

pip install "browsertrace[ui]"

Release: https://github.com/aaronlab/browsertrace/releases/tag/v0.1.17
Public-safe demo export: https://github.com/aaronlab/browsertrace/releases/download/v0.1.17/browsertrace-demo-public.html

The latest release includes the Stagehand evidence summary from #238, so Stagehand-shaped observe / action results can show compact selector, description, and method evidence alongside the recorded step.

Useful feedback is still workflow-specific: for Browser Use, Stagehand, Skyvern, Playwright + LLM, or custom computer-use failures, which fields are missing when you debug a failed run: selected elements/selectors, screenshots, video path, model output, extracted content, retry state, task prompt, or error boundaries?

[aaronlab]

Computer-use/browser-agent research note (2026-05-11): google-gemini/gemini-cli#22232 is a useful persistent-browser recovery failure shape to keep in mind for BrowserTrace-style traces.

External thread:
google-gemini/gemini-cli#22232

Relevant signal:

• The failure is not just "browser launch failed"; it is profile lock/session recovery around persistent browser contexts.
• Lock-file and process-name checks can be misleading. A fast CDP attach/probe with clear timeout/error boundaries is often more useful than trusting profile lock artifacts alone.
• Recovery may involve multiple artifacts and actions: existing browser process, remote-debugging endpoint, profile path, SingletonCookie/SingletonLock/SingletonSocket state, isolated-session fallback, user approval, and forced reset.

Implication for BrowserTrace/custom computer-use debugging:

• Future traces for persistent browser agents should preserve launch/connect/recovery events, not only browser steps after a page is open.
• Useful fields would include session_mode, user_data_dir or a redacted profile id, browser/session/target id when available, CDP endpoint/probe timing, timeout/error, detected process ids, recovery action, approval source, and final connection state.
• Keep profile paths and process details redacted or opt-in for public exports, because they can expose local usernames, workspace paths, or machine-specific state.
• Do not treat screenshot or URL capture as the first trace boundary. For persistent sessions, the debugging boundary can start earlier: profile selection, connect attempt, lock/probe result, and recovery path.

No external reply posted because the upstream issue is labeled maintainer-only; this is an internal failure-shape note for future adapter design.

[aaronlab]

Launch/status update (2026-05-13): BrowserTrace is now current at browsertrace==0.1.20.

Quick trial path:

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

Persistent install:

pip install "browsertrace[ui]"

What changed since the earlier PyPI launch:

• Browser Use-first positioning is now the main story.
• The live demo uses the local HTML upload navigation failure shape.
• browsertrace compare <failed_run_id> <success_run_id> reports the first divergent step for a failed-vs-good run pair.
• v0.1.20 also exposes the compare payload at GET /api/compare/<failed_run_id>/<success_run_id> while the local UI is running.

Useful feedback is still workflow-specific: for Browser Use failures, which evidence would make a failed-vs-good comparison actionable first: final result, extracted content, tool output, retry/repair attempts, selected element summaries, version/config metadata, or something else?

Release: https://github.com/aaronlab/browsertrace/releases/tag/v0.1.20
Live demo: https://aaronlab.github.io/browsertrace/

No stars/upvotes requested; concrete Browser Use failure shapes are the useful feedback.

[aaronlab]

Maintainer update: several recent contributions came from docs/examples around Browser Use, Playwright + LLM, Stagehand, and Skyvern debugging.

If you forked or tried BrowserTrace for a real browser-agent failure, the most useful feedback is concrete run-shape feedback rather than a generic +1. I am trying to learn:

• which agent stack you used
• what failed
• which trace field was missing
• whether failed-vs-good comparison would have helped
• what would make the export easier to share safely

Concrete failure shapes are more useful than broad feature requests. Please avoid sharing private traces directly; use public-safe exports or describe the missing fields instead.