Codex Convos

Convert local Codex session archives from ~/.codex/sessions into readable Markdown transcripts.

The converter reads a Codex .jsonl session file and renders:

• user messages
• Codex messages
• shell commands run
• command status, exit code, and captured output

This is useful when you want a readable record of a Codex session after restarting your machine, resuming a session, or closing the TUI.

Here's an example of working on some changes on Codex Convos itself.

Below you can see part of the exported conversation, Codex comments in yellow, user comments in blue.

It collapses low value read/discovery "noise" commands (such as sed, rg etc) which it uses to read files and those are then viewable by expanding the section.

Other more useful commands to view are not shown in a collapsed area.

Repository Layout

• codex_session_to_markdown.py: converts one Codex session .jsonl file into Markdown
• list-codex-convos.sh: prints recent Codex session .jsonl files using cached AI summaries from codex-history
• get-codex-convo.sh: exports a chosen session, or the newest matching one by default
• list-and-open-codex-convo.sh: interactive fzf picker that exports the selected session and opens it
• ~/.cache/codex-convos/convos/: default output directory for generated Markdown transcripts

Requirements

• Python 3
• Codex CLI sessions already present under ~/.codex/sessions
• fzf if you want the interactive getcc selector function
• optional: codex-history installed, by default at ~/Projects/codex-history

If codex-history is available, codex-convos uses its cached AI summaries for the picker labels. If it is not available, codex-convos falls back to the original behavior of showing the first user prompt.

You can override the default codex-history location by setting CODEX_HISTORY_REPO.

OS Compatibility

The scripts are intended to work on both Linux and macOS.

• --open prefers Google Chrome on both platforms and falls back to the platform default opener if Chrome is unavailable
• the getcc shell helper below is written to work in zsh as well as bash

Basic Usage - Shell Integration

Add this to your shell config, for example ~/.bashrc or ~/.zshrc and change ~/Projects/codex-convos as needed:

function getcc() {
    ~/Projects/codex-convos/list-and-open-codex-convo.sh --days 14
}

After reloading your shell:

getcc

That shows the 10 most recent session files in fzf, lets you choose one, then exports it to:

~/.cache/codex-convos/convos/<same-session-name>.md

The fzf list is newest-first, with the newest session at the top and initially selected. The orange timestamp shown is the session file's modified time, so the displayed order matches the sort order. Each entry is shown like:

12th Apr @ 14:59:32 : Investigated ai-chat-service authorization failures across token, config, and SDK env.

On selecting one of the Codex conversations it converts it to Markdown and opens it in Chrome.

You can also run the wrapper directly:

~/Projects/codex-convos/list-and-open-codex-convo.sh --days 14
~/Projects/codex-convos/list-and-open-codex-convo.sh --days 30 --limit 50

Basic Usage - Individual Files

Export the newest available session file:

~/Projects/codex-convos/get-codex-convo.sh

Convert a specific session file:

~/Projects/codex-convos/get-codex-convo.sh \
  ~/.codex/sessions/2026/04/11/<filename>.jsonl

Export a session and open the generated Markdown in Chrome:

~/Projects/codex-convos/get-codex-convo.sh --open \
  ~/.codex/sessions/2026/04/11/<filename>.jsonl

List the 10 newest session files with a readable label and the underlying path:

~/Projects/codex-convos/list-codex-convos.sh
~/Projects/codex-convos/list-codex-convos.sh --days 7
~/Projects/codex-convos/list-codex-convos.sh --limit 20 --refresh

When codex-history is present:

• --days N only considers sessions from the last N days
• --limit N changes how many recent sessions are listed
• --refresh forces the AI summary cache to be regenerated instead of reusing any cached summary

When codex-history is not present:

• codex-convos falls back to its original first-prompt labels
• --days N and --limit N still work in that fallback mode
• --refresh is accepted but has no effect in fallback mode, because there is no AI summary cache to refresh

Argument behavior in both modes:

• no --days and no --limit means --days 14 --limit 1000
• --days N with no --limit means every session in the last N days
• --limit N with no --days means the most recent N sessions with no day filter
• --days N --limit M means sessions in the last N days capped at M

Export the newest session within a date window:

~/Projects/codex-convos/get-codex-convo.sh --days 7
~/Projects/codex-convos/get-codex-convo.sh --days 30 --limit 20 --open

If you want direct control of the underlying Python converter, it still works:

python3 ~/Projects/codex-convos/codex_session_to_markdown.py \
  ~/.codex/sessions/2026/04/11/<filename>.jsonl \
  -o ~/.cache/codex-convos/convos/session.md

You can also skip command history and export only the conversation:

python3 ~/Projects/codex-convos/codex_session_to_markdown.py \
  ~/.codex/sessions/2026/04/11/<filename>.jsonl \
  --skip-commands \
  -o ~/.cache/codex-convos/convos/session.md