claude-notes: claude code sessions to html
June 2025
Claude Code is fast, but it’s hard to look back. I found myself frequently wanting to show a colleague the exact “messy middle” of a session—the specific tool call or terminal output that finally led to a solution.
But Claude stores everything as raw .jsonl files in ~/.claude/projects/. Not exactly something you can link in a PR.
claude-notes is a local CLI tool that turns those JSON lines into readable, searchable, and shareable HTML.
Debugging Replay: Seeing the Process
The value isn’t just in the final code; it’s in the process. By converting the transcript into a clean HTML view, I can “replay” the debugging logic:
- Which bash commands did the agent run?
- What were the specific tool outputs it reacted to?
- Where did it hallucinate, and how was it corrected?
A Modern Python Workflow
I built this with Python, Rich (for the terminal view), and Jinja2 (for the HTML output). The distribution is built for modern developer speed using uvx. No environment setup, no pip install.
Render to HTML:
uvx claude-notes show --format html --output session.html
Quick Terminal Replay:
uvx claude-notes show
Actual Exported Session
Below is a live export of a Claude Code session. You can open it full screen.
…
Implementation
Nothing fancy. Python with Rich for terminal rendering and Jinja2 for HTML templates. Point it at a project directory, it finds the JSONL files and renders them.
I use it mostly to replay my own sessions. Go back to see how something was debugged. Or export to HTML and send to someone when I want to show them an interesting conversation.
claude-notes was the starting point. The need to share sessions led to claudebin — a web platform where sessions become permanent, searchable, embeddable URLs with a single command.
Stay curious ☕