Converts Codex CLI JSONL session transcripts into single-file HTML viewers with sidebar navigation, search, and filtering. No external dependencies. Just open the .html in any browser.
See the full demo for more screenshots and a walkthrough of every feature.
git clone https://github.com/masonc15/codex-transcript-viewer.git
uv tool install ./codex-transcript-viewer
Or run directly without installing:
uv run --directory ./codex-transcript-viewer codex-transcript-viewer <session.jsonl>
codex-transcript-viewer <session.jsonl> [output.html]
If you omit the output path it writes <input-stem>.html in the current directory.
Codex stores sessions as JSONL files under ~/.codex/sessions/. Find one and point the tool at it:
codex-transcript-viewer ~/.codex/sessions/2026/02/18/rollout-2026-02-18T10-06-22-019c7149.jsonl
open rollout-2026-02-18T10-06-22-019c7149.html
The HTML output has a sticky sidebar on the left with a scrollable event tree and a main content area on the right. Each event type gets its own visual treatment:
- User messages with green left border
- Final answers highlighted with a subtle green background
- Commentary (intermediary updates) in italic with a muted border
- Reasoning summaries in gray italic
- Tool calls showing the command or JSON arguments
- Tool outputs with click-to-expand for long content
- System events (turn started, aborted, rolled back) in dim text
- Token usage counters
The sidebar supports text search and preset filters (Default, No tools, User only, Answers, All). On mobile the sidebar collapses behind a hamburger menu.
Inspired by the HTML session export in pi, a coding agent by @badlogic.
src/codex_transcript_viewer/
parser.py - JSONL parsing and event extraction
markdown.py - lightweight markdown-to-HTML conversion
formatting.py - timestamp formatting helpers
html_builder.py - assembles the final HTML from events
style.css - all CSS for the viewer
viewer.js - sidebar filtering and navigation
cli.py - command-line entry point