Turning Claude Code Sessions into HTML Replays

2 minute read

Claude Code sessions are great for development, but hard to share.

Screen recordings are bulky, static, and you can’t search or skip ahead. Copy-pasting raw transcripts is noisy — tool calls, thinking blocks, and responses all run together. The most interesting part of a session isn’t just the final output — it’s the reasoning: which tools the agent called, in what order, and why.

I’ve been writing a series of posts about giving AI agents direct access to hardware through MCP, and every article includes demos of the agent interacting with real devices. I wanted to show the full sessions — not just cherry-picked screenshots — but there wasn’t a good way to do that.

The logs are already there

Claude Code stores complete session transcripts as JSONL files in ~/.claude/projects/. These logs already contain everything needed to reconstruct a session:

User prompts
Assistant responses (with markdown formatting)
Tool calls and their results
Thinking blocks
Timestamps for every interaction

The data is all there. It just needs a player.

So I built one

claude-replay is a small CLI tool that converts these logs into interactive HTML replays. It works with sessions from Claude Code — both the terminal CLI and the VS Code extension — and also supports Cursor transcripts.

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

The output is a single self-contained HTML file — no external dependencies, no framework, no server. You can email it, host it on GitHub Pages, or embed it in a blog post, or link to it. For platforms that don’t support iframes (like dev.to or Medium), you can host the replay and embed it via CodePen.

Here’s what that looks like:

Hit play, step through with arrow keys, or click the progress bar to jump around. Expand tool calls to see inputs and results. Collapse thinking blocks if you want to focus only on the conversation.

Use cases

The obvious one is blog posts and documentation — embed a session instead of stitching together screenshots. But the use case I didn’t expect was knowledge sharing in teams.

When you’re working with AI agents, the interesting artifact isn’t just the code that got written — it’s the session that produced it. How did the agent approach the problem? What tools did it reach for? Where did it struggle? A replay captures all of that in a format someone else can actually step through.

Instead of “hey, look at this cool thing the agent did” in Slack followed by a wall of text, you send a replay.

Features

Interactive playback with speed control (0.5x to 5x)
Collapse/expand tool calls and thinking blocks
Bookmarks and chapters for long sessions
Keyboard shortcuts (space, arrow keys)
Multiple themes (dracula, monokai, github-light, and more)
Automatic secret redaction
Self-contained — zero external dependencies

Getting started

# Install globally
npm install -g claude-replay

# Or run directly with npx
npx claude-replay session.jsonl -o replay.html

# Find your session logs
ls ~/.claude/projects/*/

A few useful options:

# Only include turns 5-15, start at 2x speed
claude-replay session.jsonl --turns 5-15 --speed 2.0 -o replay.html

# Add chapter markers
claude-replay session.jsonl --mark "3:Flash firmware" --mark "7:BLE scan" -o replay.html

# Use a different theme
claude-replay session.jsonl --theme dracula -o replay.html

Enrico Santagati