claude-replay

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, OpenCode, Kimi Code, and Hermes Agent 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.

Try it online · Live demo

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

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/, ~/.gemini/tmp/, and the Hermes SQLite databases (~/.hermes/) 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

Kimi Code

Kimi Code (Moonshot AI) transcripts are supported — the format is auto-detected. Kimi Code stores sessions as wire.jsonl under ~/.kimi-code/sessions/, with each subagent in its own agents/<name>/ directory; the web editor discovers the main session alongside any subagents. Thinking blocks and tool calls are rendered natively.

Hermes Agent

Hermes Agent (Nous Research) sessions are supported two ways. On Node 22.5+, claude-replay reads the live SQLite store directly — no export needed:

# By session ID (searches ~/.hermes/state.db and ~/.hermes/profiles/*/state.db)
claude-replay 20260819_142844_43efe7 -o replay.html

# Or by virtual path
claude-replay ~/.hermes/state.db#session:<id> -o replay.html

Exported files also work: hermes sessions export --session-id <id> --format jsonl out.jsonl, then replay out.jsonl (auto-detected). Tool names (terminal, patch, read_file, etc.) are mapped to Claude Code equivalents for consistent rendering; reasoning blocks are shown as thinking. The web editor lists Hermes sessions grouped by profile.

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/, ~/.gemini/tmp/, and the Hermes SQLite databases (~/.hermes/), 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/, ~/.gemini/tmp/, and the Hermes SQLite databases (~/.hermes/) 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