Tester Guide

New here? Download and install the extension first.

Basic usage flow

  1. Start recording: Alt/Option + Shift + R
  2. Add voice marker: Alt/Option + Shift + M
  3. Stop recording: Alt/Option + Shift + R
  4. Export your session. There are two export types:
    • Session Report — includes the full video recording. Import it into the TraceGist viewer to review the session visually with timeline, markers, and screenshots. Share this with developers who want to watch the session.
    • Agent Session Export — a structured package without video (interaction timeline, errors, environment snapshot, Playwright script). This is what coding agents consume via the MCP bridge.

Handing off your session

Share the exported TraceGist session zip — that’s the entire artifact. It contains the interaction timeline, captured errors, environment snapshot, and a generated Playwright repro script.

TraceGist viewer

Import a Session Report into the TraceGist viewer to review the session with full video playback, a marker timeline, screenshots, and captured logs. Open the viewer from the extension popup.

Voice notes & transcription

Voice markers (Alt/Option + Shift + M) record audio that ships with your session. Out of the box the audio is not transcribed — the handoff file references a voice.wav and your reviewer (or coding agent) hears it but doesn’t read it. To get text transcripts, pick one:

  • For the extension’s “Analyze with AI” — paste an OpenRouter API key into the extension popup. Your key is stored locally and used only when you run “Analyze with AI”.
  • For the MCP bridge — local Whisper is bundled, so voice-note transcription works on any machine with a C/C++ toolchain. Xcode CLI tools (macOS) and build-essential (Linux) are commonly already installed; on Windows you’ll typically need to install Visual Studio Build Tools explicitly. Forwarding OPENROUTER_API_KEY to the bridge is optional and only used if you want cloud transcription. See the agent integration guide for details.

Analyze with AI

The viewer has an optional “Analyze with AI” feature that generates a structured assessment of the session. It requires an OpenRouter API key — set it once in the extension settings. Your key is stored locally and only used when you trigger analysis.

Settings

Open settings from the extension popup. Key options:

  • OpenRouter API key — required for AI features and (optionally) voice transcription.
  • Transcription mode — choose between local Whisper (via MCP) or OpenRouter for voice note transcription.
  • Deep diagnostics — enables request/response body capture for network calls.
  • Export profile — controls how much detail is included in the agent session export.

For developers: MCP bridge setup

If you want to use TraceGist session packages directly from a coding agent, follow the agent integration guide.