codex-transcripts

Convert Codex CLI session files (JSONL) to clean, mobile-friendly HTML pages with pagination.

Installation

Install with uv:

uv tool install codex-transcripts

Or run without installing:

uvx codex-transcripts --help

Usage

This tool converts Codex session files into browsable multi-page HTML transcripts.

Commands:

• local (default) – select from local Codex sessions stored in ~/.codex/sessions
• json – convert a specific JSONL session file (or URL)
• all – convert all local sessions to a browsable HTML archive

Quickest way to view a recent local session:

codex-transcripts

Output options

All commands support these options:

• -o, --output DIRECTORY – output directory (default: ./transcripts and open browser)
• -a, --output-auto – auto-name output subdirectory based on session filename
• --repo OWNER/NAME – GitHub repo for commit links (auto-detected from git push output if not specified)
• --open – open the generated index.html in your default browser (default if no -o specified)
• --gist – upload the generated HTML files to a GitHub Gist and output a preview URL
• --json – include the original session file in the output directory

The generated output includes:

• index.html – an index page with a timeline of prompts and commits
• page-001.html, page-002.html, etc. – paginated transcript pages

Local sessions

Local Codex sessions are stored as JSONL files in ~/.codex/sessions.

codex-transcripts
# or explicitly:
codex-transcripts local

Use --limit to control how many sessions are shown (default: 10):

codex-transcripts local --limit 20

Converting from JSONL files

Convert a specific session file directly:

codex-transcripts json /path/to/session.jsonl -o output-directory/

The json command can also take a URL to a JSON/JSONL file.

Publishing to GitHub Gist

Use --gist to upload your transcript and get a shareable preview URL:

codex-transcripts --gist
codex-transcripts json session.jsonl --gist

Requirements: The --gist option requires the GitHub CLI (gh) to be installed and authenticated.

Converting all sessions

Convert all local Codex sessions to a browsable HTML archive:

codex-transcripts all

Options:

• -s, --source DIRECTORY – source directory (default: ~/.codex/sessions)
• -o, --output DIRECTORY – output directory (default: ./codex-archive)
• --include-agents – include agent-* session files (excluded by default)
• --dry-run – show what would be converted without creating files
• --open – open the generated archive in your default browser
• -q, --quiet – suppress all output except errors

Acknowledgements

Vibecoded by codex in 15 mins by copy-clonning simonw's claude-code-transcripts.