Recording & Replay

Every browser automation session is recorded with step-by-step logs, visual diffs, and approval records. These recordings enable debugging, audit trails, and test replay.

Session Recording

When the AI performs browser automation, every action is logged to a session directory under .opta/browser/. Each session gets its own folder (e.g., sess-int-02/) containing all recording artifacts. This happens automatically -- there is no configuration needed to enable recording.

The recording system captures:

Every tool invocation with its arguments and results
Screenshots at key interaction points
Visual diffs comparing before and after states
Policy decisions (approved, denied, auto-approved)
Timing data for each step

Steps Log (steps.jsonl)

The primary recording artifact is steps.jsonl, a newline-delimited JSON file where each line represents one tool invocation. Each entry includes:

steps.jsonl (example entry)

{
  "step": 3,
  "tool": "click",
  "args": { "selector": "[data-testid='submit-button']" },
  "result": { "success": true },
  "timestamp": "2026-03-01T14:23:45.123Z",
  "duration_ms": 142,
  "policy": "auto-approved"
}

The JSONL format is chosen for append-only efficiency -- each step is written as it completes, so recordings survive crashes or interruptions. You can stream the file with standard tools like tail -f to watch automation in progress.

Visual Diff

The visual diff system captures screenshots before and after key interactions and compares them to detect visual changes. Two files track this data:

visual-diff-manifest.jsonl -- maps each diff entry to its before/after screenshot paths and the triggering tool call
visual-diff-results.jsonl -- contains the comparison results, including pixel difference percentage and detected change regions

Visual diffs are useful for verifying that browser interactions had the expected effect. If a click was supposed to open a modal, the diff shows whether the modal actually appeared.

Debugging failed automations

When a browser automation task fails, check the visual diff results first. They often reveal what the AI expected to see versus what actually happened -- a common source of automation failures is pages that load differently than expected.

Recordings Manifest

Each session directory contains a recordings.json file that serves as a manifest for all recording artifacts in that session. It includes:

Session ID and metadata (start time, duration, status)
List of all captured screenshots with paths
Step count and tool call summary
Links to the steps log, visual diff files, and approval log

The manifest provides a quick overview of a session without needing to parse the full JSONL step log.

Approval Log

The file approval-log.jsonl (stored at the browser root level, not per-session) records every policy decision made during browser automation. Each entry captures:

Which tool was invoked
The policy decision (approved, denied, auto-approved, user-approved)
Who approved it (system policy or user confirmation)
Timestamp and session context

This log serves as an audit trail for security review. You can verify that no browser actions were taken without proper authorization.

Run Corpus

The run corpus (.opta/browser/run-corpus/) stores reference recordings that can be used for test replay. The latest.json file points to the most recent complete automation run.

Run corpus recordings are useful for regression testing -- you can replay a previously successful automation sequence to verify that a web application still behaves as expected after changes.

File locations

All browser recording artifacts are stored under .opta/browser/ in the project root. Session directories are named with the pattern sess-int-NN/. The approval log and run corpus are at the browser root level.

Tools

Overview