es617/claude-replay

claude‑replay – Turn AI coding sessions into shareable, interactive HTML

What it is – claude-replay is a command‑line (and web‑editor) utility that reads the transcript files produced by a handful of AI‑coding assistants – Claude Code, Cursor, Codex CLI, Gemini CLI, OpenCode, Kimi Code, and Hermes Agent – and converts them into a single, self‑contained HTML replay. The replay can be opened in any browser, embedded in docs, or sent by email, letting readers watch the whole development conversation (including tool calls, reasoning blocks, and file changes) without needing a video.

Why it matters – AI‑driven coding sessions are valuable for teaching, bug reports, demos, and blog posts, but the raw JSONL logs are hard to read and screen‑recordings are large. claude-replay bridges that gap by providing an interactive, lightweight playback that preserves the original structure (user prompts, assistant replies, tool usage) and adds features like speed control, redaction, and theming.

Key features

• Zero‑dependency HTML – the output file bundles all CSS/JS and the compressed transcript, so it works offline and can be hosted anywhere.
• Multi‑agent support – automatically detects the format of seven different agents and normalises their tool‑call names to a common UI.
• Live watch mode – --serve --watch runs a local server that regenerates the replay as the source transcript grows, useful for monitoring long‑running agents.
• Web‑based editor – launching claude-replay with no arguments opens a browser UI where you can browse discovered sessions, edit turns, add bookmarks, tweak themes, and preview the final replay before exporting.
• Redaction & privacy – built‑in rules let you replace secrets (API keys, passwords, etc.) with [REDACTED] or custom text.
• Playback controls – play/pause, step‑by‑step navigation, speed slider (0.5‑5×), toggles for thinking blocks and tool calls, and keyboard shortcuts.
• Theming – several ready‑made themes (tokyo‑night, dracula, monokai, etc.) plus a JSON‑based custom‑theme system.
• Export options – choose which turns to include, filter by timestamps, set initial speed, add chapter bookmarks, and control how timing is derived (real timestamps, synthetic “paced” timing, or a word‑by‑word reveal).

Typical workflow

1. Run an AI coding session with one of the supported agents; the agent writes a transcript file (e.g., ~/.claude/projects/my‑proj/session.jsonl).
2. Generate a replay:

   claude-replay abc123def456 -o demo.html
   

   The tool auto‑finds the transcript based on the ID.
3. Open demo.html in a browser to view the interactive playback, or embed it via an <iframe> in a blog post.
4. For more control, launch the visual editor (claude-replay), edit turns, add bookmarks, pick a theme, then export.

Installation – Available as a global npm package (npm install -g claude-replay) or run ad‑hoc with npx claude-replay. A Docker image (ghcr.io/es617/claude-replay) is also provided for isolated use.

Who should use it

• Developers who want to showcase how an AI assistant helped write or debug code.
• Technical writers / educators looking for an interactive way to demonstrate AI reasoning.
• Bug reporters who prefer a concise replay over a massive log file.
• Teams that need to monitor agent activity in real time on remote machines.

Bottom line – claude-replay turns otherwise opaque AI‑coding logs into a clean, shareable, and interactive experience, making it easier to communicate, teach, and document AI‑augmented development.