Skip to content

Local React Viewer

Use the local React viewer when a replay report is too dense for CLI output but you still want everything to stay on your machine. The preferred human entrypoint is now replaylab app, which starts a localhost-only browser UI over your .replaylab store and lets you select reports without assembling capsule/report paths manually.

The report view and report export-viewer commands remain useful when you need one self-contained .html file. You can open that file directly in a browser; no upload, account, or Node install is required for normal use.

The dependency-free static HTML commands remain available as a fallback: replaylab report export-html and replaylab report diff-html.

Setup

Start from a replayable capsule and report. The no-key quickstart creates both:

uv run replaylab run \
  --project-name dogfood-mvp \
  --auto-patch-integrations auto \
  --capture-payload-policy full \
  -- python examples/dogfood_mvp/app.py

uv run replaylab capsule list --local-store-root .replaylab

Pick the child provider capsule whose integrations include openai, requests, and auto_patch.

Replay it:

uv run replaylab replay <child_capsule_id> \
  --local-store-root .replaylab \
  --auto-patch-integrations auto \
  --report-id replay_dogfood_mvp \
  -- python examples/dogfood_mvp/app.py

Open A Report Viewer

To browse all local artifacts first, run:

uv run replaylab app --local-store-root .replaylab

The app shows explicit start points for the latest failed regression replay, latest regression replay, and latest captured run, deduplicating the start strip when the newest replay is also the newest failure. It then loads diagnosis and artifact actions for the selected item. It accepts either the internal replay ID or the report artifact directory when opening report details, which keeps named reports such as replay_pydantic_ai_realism usable from the UI and API. ReplayLab projects local storage into product artifacts first: one captured run owns its regression replays, live experiments, generated regressions, and exports. Experiment-created capsules remain inspectable as live-experiment traces, but they link back to the baseline captured run instead of appearing as new primary captured runs.

ReplayLab recovers run profiles from existing artifact metadata and detects provider labels from captured boundaries, so realistic framework projects can use openai or requests as detected facts instead of asking the user to pick providers. The normal app path is button-driven: run deterministic regression replay, start a confirmed live experiment against current providers, compare to capture, generate a provider replay guard, export a report, or capture again when a recovered profile exists. Fresh captures store run profile metadata automatically; older captures without that metadata show app-managed regression replay setup candidates and a Regression replay with detected setup action when ReplayLab can infer a runnable project module. Completed live experiments remain attached to the captured run in the Live experiments tab with their labels, hypotheses, applied variant summaries, and comparison verdicts. The live experiment workbench can apply supported changes to scenario input, canonical provider instructions, user input, model parameters, tool choice, response format, response-mode intent, and tool declaration descriptions or schemas before the live run. It also previews OpenAI, Anthropic, and Gemini conversions with compatibility reports; preview-only conversions can be selected for inspection while the live run stays blocked. Captured-run pages and inspectors now include a Local workflow hub that keeps the complete loop discoverable after refresh: trace readiness, latest regression replay, latest live experiment, generated provider replay guard or diagnostic provider replay guard history, export/upload-preview status, and the next recommended app action. The generated-regression tab shows guard mode, source replay, generated path, hash, size, pytest result, and a copyable generated-test location. Captured-run pages render a split-pane trace explorer with Agent run, logical steps, LLM/API calls, LLM requested tool rows, and Provider protocol tool result rows in the trace skeleton, plus a selected-node detail pane for formatted redacted Input/Output panels, assistant messages, tool data, and collapsed Replay data for hashes and payload refs. The Captured runs route keeps the run list visible while opening the selected run in a right-side inspector, which is the fastest way to compare recent captures by timestamp, status, and provider calls. The app uses the same packaged React assets as exported viewers, but fetches secret-safe summaries and redacted local previews from local /api/... endpoints instead of embedding one report payload. It returns structured step status instead of raw child stdout/stderr.

If you already have a capsule and want the same local loop from a script, use the guided workflow:

uv run replaylab workflow local <child_capsule_id> \
  --local-store-root .replaylab \
  --auto-patch-integrations auto \
  --report-id replay_dogfood_guided \
  --viewer-output replay-viewer.html \
  --generate-test \
  --run-generated-test \
  -- python examples/dogfood_mvp/app.py

This command replays the app, compares the report, writes and opens the React viewer, and optionally generates/runs pytest. Use report view report when you already have a report and only need to open that report in the viewer.

Run:

uv run replaylab report view report \
  .replaylab/replays/replay_dogfood_mvp/report.json \
  --capsule <child_capsule_id> \
  --local-store-root .replaylab \
  --output replay-viewer.html

Expected output:

ReplayLab viewer ready
HTML: replay-viewer.html
Capsule: <child_capsule_id>
Report: replay_dogfood_mvp
Comparison: succeeded
Boundaries: 2
Problems: 0
Browser: opened file:///...

Use --no-open-browser when running this command in CI, a scenario, or a headless shell. The file is still written and can be opened manually.

You should see:

  • a top-level diagnosis that tells you whether the replay is clean or where the first divergence happened
  • expected-vs-actual call evidence and a first recommended action for failed replays
  • a "What to do next" section with copyable command blocks
  • report status and capsule-to-report comparison status
  • capsule ID, run ID, project, environment, providers, and integrations
  • replay summary counts
  • a boundary table with outcome, provider, operation, resource, request hash, and payload availability
  • quick filters for all rows, problems, replayed rows, mismatches, and extra/missing rows
  • filters for outcome, provider, operation, and text search
  • grouped next commands for inspection, comparison, diffing, replay, and regression generation

This matters because replay failures are easier to understand when you can scan outcomes, filter the boundary list, and keep the exact next command visible.

replaylab report export-viewer report ... remains available when a script should only write the HTML file without opening a browser.

Open A Diff Viewer

When you have a baseline report and a candidate report, export a diff viewer:

uv run replaylab report view diff \
  .replaylab/replays/replay_before/report.json \
  .replaylab/replays/replay_after/report.json \
  --output replay-diff-viewer.html

Expected output when the candidate is clean or improved:

ReplayLab diff viewer ready
HTML: replay-diff-viewer.html
Comparison: succeeded
Browser: opened file:///...

If the candidate regresses, ReplayLab still writes replay-diff-viewer.html and exits 1, matching replaylab report diff semantics. Open the file to see improved outcomes, regressions, changed failures, unchanged failures, incompatibilities, a candidate got better/worse/same diagnosis, diff filters, search, and grouped next commands.

The diff viewer also shows the optional AI next command:

uv run replaylab report diff-explain \
  .replaylab/replays/replay_before/report.json \
  .replaylab/replays/replay_after/report.json \
  --dry-run

Use it after deterministic report diff when you want advisory plain-language context. The viewer does not call AI itself.

Use replaylab report export-viewer diff ... when you need a non-opening diff export for automation.

Secret Safety

The local app can render explicit redacted payload previews in the captured-run trace inspector so you can see what went into and came out of LLM/API/tool protocol calls. It presents formatted views first and keeps raw JSON/text collapsed as replay/debug data. It still does not render unredacted payloads, API keys, raw headers, source bodies, framework bodies, or raw child stdout/stderr.

Exported viewers embed inspection summaries and replay-report summaries only. They do not render payload file contents, API keys, raw headers, source bodies, or framework request and response bodies.

Request hashes and payload availability booleans are shown so you can diagnose matching problems without exposing private data.

Next Step

Once the report is clean, generate a provider replay guard:

uv run replaylab generate-test <child_capsule_id> \
  --output tests/regression/test_dogfood_replay.py \
  --fixture-root tests/fixtures/replaylab/capsules \
  --app-root . \
  --auto-patch-integrations auto \
  -- python examples/dogfood_mvp/app.py