codex-transcript-viewer

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.

Install

It's on PyPI, so install it with uv or pipx, or run it once without installing anything:

uv tool install codex-transcript-viewer
pipx install codex-transcript-viewer
uvx codex-transcript-viewer <session.jsonl>

For the latest unreleased changes, install straight from GitHub:

uv tool install git+https://github.com/masonc15/codex-transcript-viewer.git

To hack on it, clone the repo and install from the checkout instead, or run it without installing:

git clone https://github.com/masonc15/codex-transcript-viewer.git
uv tool install ./codex-transcript-viewer
uv run --directory ./codex-transcript-viewer codex-transcript-viewer <session.jsonl>

Usage

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

Images are embedded, so the page stays a single file. Images you attached to a prompt are always included, taken from the copy saved in the session log, since the original file is often a temp file that's long gone. Screenshots returned by tools are embedded until they add up to 25 MB, after which the rest show as placeholders and a note at the top says how many were left out. --max-image-mb N changes that budget (0 means no limit), and --no-images replaces every image with a labelled placeholder, which is handy when you want a small page or would rather not share what was on your screen.

Tool output text is embedded in full. Codex already trims what the model sees to roughly 200K characters, so the viewer's own --max-output-chars guard (default 250,000, 0 to disable) only kicks in for something pathological.

If the log contains record types the viewer doesn't know about, it says so on stderr after writing the page, which usually means Codex changed its format.

What the viewer shows