Introducing Codex Transcripts

Codex Transcripts turns Codex CLI sessions into a readable, shareable artifact.

I use Codex CLI a lot, and I’ve started treating the transcript as part of the deliverable. Not just the final diff—also the prompts, the decisions, the tool calls, and the little “wait, not that” corrections.

So I built codex-transcripts: a small CLI that converts Codex session JSONL files into clean, mobile-friendly HTML transcripts.

Two important notes: I can’t take credit for the core idea (this project is directly inspired by Simon Willison’s claude-code-transcripts), and if you haven’t read Simon’s post, it’s a great explanation of why transcripts matter (not just how to export them): https://simonwillison.net/2025/Dec/25/claude-code-transcripts/

Repo: https://github.com/brucehart/codex-transcripts

The problem is that “the work” moved into the conversation

More and more, my coding sessions look like a prompt, a plan, tool calls, patches, test runs, and a couple of course corrections—and that becomes the best record of what happened and why.

But Codex stores sessions as JSONL under ~/.codex/sessions/, and JSONL is not a great interface for humans.

Codex Transcripts converts JSONL into a small static site

Point it at a session and it generates an index.html summary + timeline (with counts and jump links) plus page-001.html, page-002.html, and so on for the paginated full transcript.

It’s intentionally boring tech: static HTML, no backend. Open it locally, host it anywhere, or share it.

The features are all about legibility

The things I care about when I’m trying to reconstruct a session are where the session started (cwd, timestamps, basic metadata), what tools ran (shell commands, patch application, etc.), where the “long explanations” are buried, and whether I can jump to the moment that matters without scrolling forever.

So the tool leans into that with three modes: local (default) scans ~/.codex/sessions and lets you pick a recent session interactively, json converts a specific JSONL file, and all converts everything into a browsable archive grouped by project.

And the output tries to make tool activity first-class (because that’s where most of the truth is).

Search works when you host it

The generated pages include a simple client-side search UI that fetches the paginated HTML pages and highlights matches.

It intentionally doesn’t run on file:// URLs (browser security makes that a pain), but it works fine if you serve the files over HTTP (including via gists).

Sharing via GitHub Gists is the killer feature

Like Simon’s tool, codex-transcripts can publish the generated HTML to a GitHub Gist and give you a preview link via gistpreview.github.io.

If you’ve ever wanted to share “here’s exactly what I asked for,” “here’s what the tool actually did,” or “here’s the patch it applied,” this is a surprisingly nice workflow.

Quick start

If you already use uv:

uvx codex-transcripts

Or install it:

uv tool install codex-transcripts

Examples:

# Pick a local session
codex-transcripts

# Convert a specific session file
codex-transcripts json ~/.codex/sessions/2025/12/24/rollout-...jsonl -o ./output

# Convert and share as a gist
codex-transcripts local --gist

# Convert everything into an archive
codex-transcripts all -o ./codex-archive --open

The longer-term itch: one transcript archive across tools

Long-term, I want something that treats transcripts as a first-class dataset across all of these tools: Codex CLI, Claude Code, and whatever else I end up using next.

I’d love an archive where you can search across everything you’ve done, correlate transcripts with file changes over time, track metrics like token usage and “token efficiency,” and get recommendations for using models more cost-effectively.

The fun (and slightly dangerous) version is a CLI orchestrator that plans, routes sub-tasks to different models/providers based on the job, and keeps a high-fidelity audit trail.

Maybe that gets you a big cost reduction and better outcomes.

But also: models are improving and getting cheaper so fast that it’s not obvious a complex optimization layer will be worth maintaining. I’m watching that curve before I go build something huge.

Short-term: help Codex Transcripts summarize itself

In the near term, I want to make codex-transcripts better at answering the question:

“What happened here?”

One idea I’m planning to try: run a fast/cheap model (Gemini Flash-class) over a transcript to produce a compact summary of tasks performed, files changed, tools used (and patterns), and token usage (where available).

If you have ideas for features that would make this more useful—especially if you’ve built anything like this—please reach out or open an issue/PR.

Repo again: https://github.com/brucehart/codex-transcripts

And seriously, go read Simon’s original: https://simonwillison.net/2025/Dec/25/claude-code-transcripts/