codex-session-html

Convert a Codex CLI JSONL session into a self-contained, human-readable HTML transcript. The output is print-friendly and can be converted to PDF with Pandoc or a web browser.

Requirements

• Node.js 24 or newer
• A Codex CLI session file, usually under ~/.codex/sessions/YYYY/MM/DD/*.jsonl

Usage

npm install
npm run build
node dist/src/cli.js ~/.codex/sessions/2026/05/31/rollout-example.jsonl -o session.html

After publishing or installing globally:

codex-session-html ~/.codex/sessions/2026/05/31/rollout-example.jsonl -o session.html

Read from stdin and write to stdout:

cat session.jsonl | codex-session-html > session.html

List recent Codex sessions:

codex-session-html --list

Pick a session interactively:

codex-session-html --pick -o session.html

When run without an input path in an interactive terminal, codex-session-html opens the same picker by default. Prompts are written to stderr, so generated HTML can still be redirected from stdout.

Convert to PDF with Pandoc:

pandoc session.html -o session.pdf

Or open session.html in a browser and print to PDF.

Options

Usage:
  codex-session-html [session.jsonl] [options]
  codex-session-html --list [options]
  codex-session-html --pick [options]

Options:
  -o, --output <path>   Write HTML to a file instead of stdout.
  --title <title>      Override the HTML document title.
  --list               List discovered Codex sessions and exit.
  --pick               Choose a discovered Codex session interactively.
  --limit <count>      Limit discovered sessions. Defaults to 50 for --pick.
  --codex-home <path>  Use a Codex home directory other than ~/.codex.
  --raw                Include collapsible raw JSON for each rendered record.
  --system             Include developer/system prompt messages.
  --help               Show help.

By default, developer/system prompt records are omitted to keep transcripts focused on the human conversation and tool activity. Use --system when you need a complete audit view.

What It Renders

• Session metadata such as session ID, working directory, CLI version, and model provider.
• User and assistant messages from response_item records.
• User and agent messages from event_msg records.
• Function/tool calls and outputs with compact labels.
• Reasoning summaries when present.
• Unknown records as compact JSON blocks, so new Codex event types are not silently dropped.

All text is HTML-escaped before rendering.

Development

npm install
npm test