Features

• 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

Use cases

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

Installation

npm install -g claude-replay

Or run directly with npx (zero install):

npx claude-replay

Docker

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

Quick start

# 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

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

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

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

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 <sessionID> > session.jsonl
claude-replay session.jsonl -o replay.html

Web Editor

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.

Usage

claude-replay [--port N]                        Launch the web editor (default)
claude-replay <input> [input2...] [options]     Generate replay from CLI
claude-replay extract <replay.html> [-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.

Commands

editor [file|session-id]

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

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.

Options

| 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 f