expect-succ

expect-succ

expect-succ records a browser session, captures page artifacts, combines the recording with microphone audio, and asks Gemini to produce a concise debugging report.

It is intended for quick local bug reports: run the CLI against a URL, reproduce the behavior in the opened browser, narrate what you are seeing, then close the browser window. expect-succ writes the session artifacts and report under .succ/sessions.

Requirements

• Node.js 22 or newer
• pnpm
• ffmpeg on your PATH
• Playwright browser dependencies
• A Gemini API key with access to a model that accepts video input

Setup

Install dependencies:

pnpm install

Build the CLI:

pnpm build

Set your Gemini API key:

export GEMINI_API_KEY="..."

The default Gemini model is gemini-2.5-flash. Override it when needed:

export GEMINI_MODEL="gemini-flash-latest"

Usage

Install the coding-agent skill:

expect-succ init "your-gemini-api-key"

Record and analyze a session:

expect-succ http://localhost:3000/ledger

Skip microphone recording:

expect-succ http://localhost:3000/ledger --no-audio

Record and combine without analysis:

expect-succ http://localhost:3000/ledger --no-analyze

Re-run analysis for an existing session:

expect-succ replay .succ/sessions/2026-04-07T18-02-44-652Z

Output

Each recording creates a timestamped directory under .succ/sessions containing:

• artifacts.ndjson: console logs, network requests, and page errors captured during the run
• Playwright video output
• microphone audio when enabled
• combined.mp4: merged video and audio
• report.md: Gemini analysis report when analysis is enabled
• manifest.json: session metadata when the run completes successfully

Development

Run the type and lint checks:

pnpm check

Run tests:

pnpm test

Build generated output:

pnpm build