Raw capture — raw/claude-replay.md

url: https://github.com/es617/claude-replay date_fetched: 2026-07-05 backfilled: true

Community tool — not affiliated with or endorsed by Anthropic.

AI coding sessions are great for development, but hard to share. Screen recordings are bulky and transcripts are hard to navigate.

claude-replay turns Claude Code, Cursor, Codex CLI, Gemini CLI, and OpenCode session logs into interactive, shareable HTML replays. The generated replay is a single self-contained HTML file with no external dependencies — you can email it, host it anywhere, or embed it in documentation. Use --serve --watch to monitor agent sessions live as they run.

Claude Code, Cursor, Codex CLI, Gemini CLI, and OpenCode store conversation transcripts on disk. claude-replay auto-detects the format and converts them into visual replays suitable for blog posts, demos, and documentation.

Source	Transcript location
Claude Code	`~/.claude/projects/<project>/`
Cursor	`~/.cursor/projects/<project>/agent-transcripts/<id>/`
Codex CLI	`~/.codex/sessions/<date>/`
Gemini CLI	`~/.gemini/tmp/<projectHash>/chats/`
OpenCode	Export via `opencode export <sessionID>`

Self-contained HTML output (no dependencies)
Interactive playback with speed control
Collapse/expand tool calls and thinking blocks (Claude's internal reasoning traces)
Bookmarks / chapters
Secret redaction before export
Multiple color themes
Terminal-style bottom-to-top scroll
File activity sidebar — see which files were touched and navigate to their tool calls
Embeddable via iframe
Live watch mode — monitor agent sessions in real time (--serve --watch)
Web-based editor UI for visual session editing and preview

claude-replay is useful for:

Blog posts— show AI-assisted development sessions interactively
Documentation— embed AI debugging sessions or code walkthroughs
Demos— share reproducible sessions without video
Bug reports— attach a replay instead of long logs
Teaching— step through AI reasoning and tool usage
Live monitoring— watch agent sessions in real time on remote machines or containers

npm install -g claude-replayOr run directly with npx (zero install):

claude-replay docker run --rm --init -p 7331:7331 \ -v ~/.claude/projects:/root/.claude/projects:ro \ ghcr.io/es617/claude-replay

Open http://localhost:7331 for the web editor. Session directories are mounted read-only.

For CLI usage:

docker run --rm --init \ -v ~/.claude/projects:/root/.claude/projects:ro \ -v $(pwd):/output \ ghcr.io/es617/claude-replay \ /root/.claude/projects/my-project/session.jsonl -o /output/replay.html

Launch the web editor (default)

claude-replay

Generate a replay by session ID (auto-finds the file)

claude-replay abc123def456 -o replay.html

Or pass the full path

claude-replay ~/.claude/projects/-Users-me-myproject/session-id.jsonl -o replay.html

Chain multiple sessions into one replay

claude-replay session1-id session2-id -o combined.html

Running `claude-replay` with no arguments opens a browser-based editor that auto-discovers your Claude Code and Cursor sessions. From there you can browse, edit, preview, and export replays visually.

For CLI usage, you can pass just a session ID — claude-replay will search `~/.claude/projects/`, `~/.cursor/projects/`, `~/.codex/sessions/`, and `~/.gemini/tmp/` to find the matching file. Or pass the full path to a session file directly.

Cursor transcripts are also supported — the format is auto-detected. Cursor transcripts don't include timestamps, so playback uses paced timing by default (see Timing modes).

`claude-replay ~/.cursor/projects/*/agent-transcripts/<id>/<id>.jsonl -o replay.html`Codex CLI (OpenAI) transcripts are also supported — the format is auto-detected. Codex tool calls (`exec_command`, `apply_patch`) are mapped to their Claude Code equivalents (`Bash`, `Edit`/`Write`) so they render with the same diff views and command previews.

`claude-replay ~/.codex/sessions/2026/03/12/rollout-<id>.jsonl -o replay.html`Gemini CLI transcripts are also supported — the format is auto-detected. Gemini stores sessions as single JSON files (not JSONL) with inline thinking blocks and tool calls. Tool names are mapped to their Claude Code equivalents (`run_shell_command` → `Bash`, `read_file` → `Read`, etc.) for consistent rendering.

`claude-replay ~/.gemini/tmp/<projectHash>/chats/session-<id>.json -o replay.html`You can also search by session ID:

`claude-replay <session-id> -o replay.html  # searches ~/.gemini/tmp/ automatically`OpenCode transcripts are supported — the format is auto-detected. OpenCode stores sessions in a SQLite database, so you'll need to export the session first using the OpenCode CLI. Thinking/reasoning blocks are rendered natively.

Export a session from OpenCode, then replay it

opencode export > session.jsonl claude-replay session.jsonl -o replay.html

The default experience. Launch it by running `claude-replay` with no arguments:

claude-replay claude-replay --port 8080

The editor provides:

- **Session browser**— auto-discovers sessions from- `~/.claude/projects/`,- `~/.cursor/projects/`,- `~/.codex/sessions/`, and- `~/.gemini/tmp/`, plus a folder navigator for session files stored elsewhere
- **Turn editor**— include/exclude turns, edit user prompts, expand assistant blocks (read-only), add bookmarks
- **Options panel**— theme, speed, thinking/tool call toggles, redaction rules, labels
- **Live preview**— updates as you edit, renders the same output as the CLI
- **Export**— download the final HTML replay

The editor runs a local server on `127.0.0.1` (localhost only, not exposed to the network). It never modifies your original JSONL files — all edits are held in memory and only affect the exported output.

claude-replay [--port N] Launch the web editor (default) claude-replay [input2...] [options] Generate replay from CLI claude-replay extract [-o output.jsonl] [--format jsonl|json]

Each `<input>` can be a session file path or a session ID. If it is not an existing file path, it is treated as a session ID. claude-replay searches `~/.claude/projects/`, `~/.cursor/projects/`, `~/.codex/sessions/`, and `~/.gemini/tmp/` for a matching session file. You can find your current session ID in Claude Code by running `/status`.

Multiple inputs are concatenated into a single replay (up to 20). When all sessions have timestamps, turns are sorted chronologically; otherwise command-line order is used. This is useful when accepting a plan creates a new session — chain the sessions to get the full story in one replay.

Launches the web-based replay editor. Optionally pass a file path or session ID to auto-load it on startup. See Web Editor above.

claude-replay editor # empty editor claude-replay editor ~/.claude/projects/.../session.jsonl # auto-load file claude-replay editor abc123 # auto-load by session ID

Extract the embedded turn data from a previously generated replay HTML file. Outputs JSONL by default (one turn per line, bookmarks embedded). Use `--format json` for the legacy JSON format.

claude-replay extract replay.html -o session.jsonl # JSONL (default) claude-replay extract replay.html -o data.json --format json # JSON

Round-trip: extract, then regenerate with different options

claude-replay extract replay.html -o session.jsonl claude-replay session.jsonl -o new-replay.html --theme dracula

The extracted JSONL can be fed back into `claude-replay` to regenerate with different options. Bookmarks are preserved as a `bookmark` field on each turn.

| Flag | Description | 
|---|---|
| `-o, --output FILE` | Output HTML file (default: stdout) | 
| `--turns N-M` | Only include turns N through M | 
| `--exclude-turns N,N,...` | Exclude specific turns by index | 
| `--from TIMESTAMP` | Start time filter (ISO 8601) | 
| `--to TIMESTAMP` | End time filter (ISO 8601) | 
| `--speed N` | Initial playback speed, e.g. `2.0`(default: 1.0) | 
| `--no-thinking` | Hide thinking blocks by default | 
| `--no-tool-calls` | Hide tool call blocks by default | 
| `--font-size SIZE` | Font size: `small`,`normal`,`large`(default:`normal`) | 
| `--mark "N:Label"` | Add a bookmark/chapter at turn N (repeatable) | 
| `--bookmarks FILE` | JSON file with bookmarks `[{turn, label}]` | 
| `--no-auto-redact` | Disable automatic secret redaction | 
| `--redact "text"` | Replace all occurrences of text with `[REDACTED]`(repeatable) | 
| `--redact "text=repl"` | Replace all occurrences of text with custom replacement (repeatable) | 
| `--title TEXT` | Page title (default: derived from input path) | 
| `--description TEXT` | Meta description for link previews (default: `Interactive AI session replay`) | 
| `--og-image URL` | OG image URL for link previews (default: hosted default). A default image is always included; to use your own, host it and pass the URL. | 
| `--user-label NAME` | Label for user messages (default: `User`) | 
| `--assistant-label NAME` | Label for assistant messages (default: auto-detected) | 
| `--timing MODE` | Timestamp mode: `auto`,`real`,`paced`(default:`auto`) | 
| `--theme NAME` | Built-in theme (default: `tokyo-night`) | 
| `--theme-file FILE` | Custom theme JSON file (overrides `--theme`) | 
| `--no-minify` | Use unminified template (default: minified if available) | 
| `--no-compress` | Embed raw JSON instead of compressed data (for older browsers) | 
| `--open` | Open the generated HTML in the default browser | 
| `--serve` | Serve the replay on a local HTTP server instead of writing to file | 
| `--watch` | Watch input files for changes and auto-regenerate | 
| `--list-themes` | List available built-in themes and exit | 
| `--port N` | Port for the editor/serve server (default: 7331 editor, 7332 serve) |

Replay turns 5 through 15 at 2x speed

claude-replay session.jsonl --turns 5-15 --speed 2.0 -o replay.html

Filter by time range

claude-replay session.jsonl --from "2026-02-26T02:00" --to "2026-02-26T03:00" -o replay.html

Clean output: no thinking, no tools

claude-replay session.jsonl --no-thinking --no-tool-calls -o replay.html

Use a different theme

claude-replay session.jsonl --theme dracula -o replay.html

Pipe to stdout for further processing

claude-replay session.jsonl --turns 1-5 > snippet.html

Chain multiple sessions into one replay

claude-replay abc123 def456 ghi789 -o combined.html

Live preview: serve and auto-reload on changes

claude-replay session.jsonl --serve --watch

Serve without watching (one-shot preview)

claude-replay session.jsonl --serve

Watch and write to file on changes

claude-replay session.jsonl --watch -o replay.html

The `--timing` flag controls how playback speed is derived:

| Mode | Behavior | 
|---|---|
| `auto` | Uses real timestamps if available, falls back to `paced`(default) | 
| `real` | Uses original timestamps from the transcript | 
| `paced` | Generates synthetic timing based on content length | 

`paced` mode creates presentation-style timing — similar to how slides appear in a presentation or subtitles are timed in a video. Block reveal speed scales with text length. This is the default for Cursor transcripts (which have no timestamps) and can also be used with Claude Code transcripts for smoother demos:

Use paced timing even for Claude Code transcripts

claude-replay session.jsonl --timing paced -o demo.html

The generated HTML file is a fully self-contained interactive player:

- **Play/Pause**— auto-advances through turns with block-by-block animation
- **Step forward/back**— navigate one block at a time within turns
- **Progress bar**— click to jump to any point; session timer shows elapsed/total time
- **Speed control**— 0.5x to 5x playback speed
- **Toggle checkboxes**— show/hide thinking blocks and tool calls

| Key | Action | 
|---|---|
| `Space`/`K` | Play / Pause | 
| `→`/`L` | Step forward (block) | 
| `←`/`H` | Step back (block) | 
| `Shift+→`/`Shift+L` | Jump to next turn | 
| `Shift+←`/`Shift+H` | Jump to previous turn | 
| `T` | Jump to next thinking/tool block | 
| `Shift+T` | Jump to previous thinking/tool block | 

`claude-replay --list-themes`Available themes: `tokyo-night` (default), `monokai`, `solarized-dark`, `github-light`, `dracula`, `bubbles`.

Create a JSON file with CSS color values:

{ "bg": "#0d1117", "bg-surface": "#161b22", "bg-hover": "#1c2128", "text": "#e6edf3", "text-dim": "#7d8590", "text-bright": "#ffffff", "accent": "#ff7b72", "accent-dim": "#c9514a", "green": "#3fb950", "blue": "#58a6ff", "orange": "#d29922", "red": "#f85149", "cyan": "#39d2c0", "border": "#30363d", "tool-bg": "#0d1117", "thinking-bg": "#0b0f14" }

`claude-replay session.jsonl --theme-file my-theme.json -o replay.html`Any missing keys are filled from the `tokyo-night` defaults, so you only need to specify the colors you want to change.

For advanced customization, add an `extraCss` key with arbitrary CSS rules to override layout, fonts, or any other styles:

{ "bg": "#ffffff", "text": "#1c1e21", "extraCss": ".assistant-text { border-radius: 12px; border: 1px solid #ddd; }" }

See the built-in `bubbles` theme for an example of a fully custom layout using `extraCss`.

## Theme variables reference

| Variable | Used for | 
|---|---|
| `bg` | Main background | 
| `bg-surface` | Controls bar, elevated surfaces | 
| `bg-hover` | Hover states | 
| `text` | Primary text | 
| `text-dim` | Secondary text, timestamps, labels | 
| `text-bright` | User input, emphasized text | 
| `accent` | Prompt symbol, progress bar, active states | 
| `accent-dim` | Active button backgrounds | 
| `green` | Tool results | 
| `blue` | Tool call indicators | 
| `orange` | (reserved for warnings) | 
| `red` | (reserved for errors) | 
| `cyan` | Tool names | 
| `border` | Borders and separators | 
| `tool-bg` | Tool call block background | 
| `thinking-bg` | Thinking block background | 

The output is a single HTML file with no external dependencies. Embed it in blog posts or docs with an iframe:

`<iframe src="replay.html" width="100%" height="600" style="border: 1px solid #333; border-radius: 8px;"></iframe>`- **Parser**reads the JSONL transcript line by line, handling Claude Code's streaming format (where a single assistant message appears as multiple lines with incremental content blocks)
- Turns are grouped as: user message + assistant response (text, tool calls, thinking blocks) + tool results
- **Renderer**compresses the parsed turns (deflate + base64) and injects them into the HTML template
- The **player**is vanilla JS — no frameworks, no external requests. Data is decompressed at load time using the browser-native`DecompressionStream`API

Generated HTML files use two layers of optimization (zero external dependencies):

- **Minified CSS/JS**— the player template is minified with esbuild (mangled variable names, whitespace removed). Use- `--no-minify`for readable output.
- **Compressed data**— transcript JSON is deflate-compressed and base64-encoded, typically reducing output size by ~60-70%. The browser decompresses it natively at load time using- `DecompressionStream`(Chrome 80+, Firefox 113+, Safari 16.4+). For older browsers, use- `--no-compress`to embed raw JSON.

To rebuild the minified template after editing `template/player.html`:

npm install # installs esbuild (devDependency) npm run build # generates template/player.min.html ``` The minified template is built in CI and included in npm releases. Without it, the CLI falls back to the unminified template automatically.

By default, claude-replay scans all embedded text for common secret patterns and replaces them with [REDACTED] before they are written into the output HTML. This means secrets from your session (API keys, tokens, connection strings, etc.) never end up in the generated file.

Detected patterns include:

API keys (sk-...,sk-ant-...,key-...)
AWS access key IDs (AKIA...)
Bearer and JWT tokens
Database connection strings (postgres://...,mongodb://..., etc.)
Private key blocks (-----BEGIN ... PRIVATE KEY-----)
Generic key/value secrets (api_key=...,auth_token: ...)
Environment variable secrets (PASSWORD=...,TOKEN=...)
Long hex tokens (40+ characters)

Important: Pattern-based redaction is a best-effort safety net — it cannot catch every possible secret format. Always review the generated HTML before sharing publicly.

To disable redaction (e.g. for internal/private replays):

claude-replay session.jsonl --no-auto-redact -o replay.htmlOne JSON object per line with a type field (user, assistant, system, progress, etc.). Includes timestamps, thinking blocks, and tool calls with results.

One JSON object per line with a top-level role field. No timestamps. Thinking appears as inline text. The format is auto-detected — no flags needed.

Event-based JSONL with typed events (session_meta, response_item, event_msg, etc.). Includes timestamps. Tool calls (exec_command, apply_patch) are mapped to Claude Code equivalents for consistent rendering. Codex's encrypted reasoning blocks are skipped; commentary messages are shown as thinking blocks. The format is auto-detected — no flags needed.

Single JSON file with a sessionId field and a messages array containing user and gemini typed entries. Includes timestamps, inline thinking blocks (thoughts), and tool calls with nested results. Tool names (run_shell_command, read_file, edit_file, etc.) are mapped to Claude Code equivalents for consistent rendering. The format is auto-detected — no flags needed.

Node.js 18+
Zero runtime dependencies (esbuild is a dev-only dependency for building the minified template)

Replay files embed the full session transcript, including source code, file paths, tool inputs/outputs, and thinking traces. Review the generated HTML before sharing publicly — it may contain proprietary code, internal paths, or other sensitive information. Secret redaction (enabled by default) catches common credential patterns but does not filter code or file contents.

The transcript data is stored as a compressed blob inside the HTML file. Editing the player JavaScript to hide or filter turns only affects rendering — the original data remains in the blob and can be recovered. To exclude sensitive content, use the CLI flags at generation time (e.g. --turns, --exclude-turns). Use --redact to strip specific strings (usernames, paths, project names) at generation time. Always review the generated replay before sharing publicly.