export_codex_chats 1.0.0

Export Codex chat sessions as standalone HTML transcripts.

export_codex_chats

Export local Codex CLI sessions to a standalone HTML transcript.

The generated HTML includes:

• user prompts
• agent responses
• visible error events
• tool invocations and outputs
• Markdown rendering
• syntax-highlighted code blocks
• client-side dark/light mode toggle
• client-side show/hide tools toggle

Installation

pip install .

For development:

pip install ".[dev]"

Usage

export_codex_chats SESSION_UUID
export_codex_chats SESSION_UUID --dark
export_codex_chats SESSION_UUID --title "Shrinking review"
export_codex_chats SESSION_UUID -o existing_exports/
export_codex_chats SESSION_UUID -o report.html
export_codex_chats SESSION_UUID --from-msg 10 --to-msg 25
export_codex_chats SESSION_UUID --show-tools --collapse-codes
export_codex_chats SESSION_UUID --no-tools
export_codex_chats SESSION_UUID --plain-path
export_codex_chats

If SESSION_UUID is omitted, the tool opens an interactive selector showing recent local Codex sessions.

By default, the exporter reads sessions from ~/.codex/sessions/. It also uses ~/.codex/history.jsonl to derive friendlier session labels for interactive selection when they are available.

Useful options:

• --title TITLE: use an explicit page title instead of Codex chat <UUID>
• --from-msg N: export starting at message N
• --to-msg N: export ending at message N
• --plain-path: print the saved file as a plain path instead of a file:// URI
• --dark: start in dark mode
• --show-tools: make tool boxes visible on initial page load
• --no-tools: omit tool invocations and outputs from the export entirely
• --collapse-codes: collapse code blocks on initial page load

When --no-tools is used, tool cards are not written into the HTML at all, the tool-visibility button is omitted from the header, and visible message numbers are compacted to match the exported transcript. Each card still keeps its original transcript number in hidden metadata for stable internal reference.

Output path rules:

• Omit --output to write <session_id>.html in the current directory.
• If --output names an existing directory, the export is written there as <session_id>.html.
• Otherwise, --output must be an explicit file path with an extension, and its parent directory must already exist.
• The exporter does not create directories.

By default, the command prints the saved file as a file:// URI rather than a plain path. That makes the result clickable in many terminals while still being easy to copy and paste. Use --plain-path if you prefer the raw filesystem path for scripts or shell composition.

Development

Run the test suite from the repository root with:

./run_tests.sh

In CI-style environments, USE_INSTALLED_PACKAGE=1 makes the tests run against an installed package instead of directly from the checkout.

Remove generated artifacts with:

./clean.sh

Run the static checks with:

ruff check .
pyright

Build and verify release artifacts with:

python -m build --no-isolation
python -m twine check dist/*

Build OS packages with:

./package_os.sh

Note: installing the sdist in an isolated build environment may download the build backend (hatchling). For offline checks, preinstall the build backend and use --no-build-isolation.

OS Packages

This repository includes a helper for building .deb and .rpm packages using fpm.

The exporter intentionally does not try to generate an AI-derived title. If you want help naming a session, a simple workaround is to resume the chat with Codex and ask it for a concise title, then pass that title explicitly with --title.

Requirements:

• fpm
• dpkg-deb
• rpmbuild
• python -m build

The script builds a wheel, stages it into pkgroot/usr/, and emits both package formats into os-packages/.

The generated OS packages use distro-native Python package dependencies:

• python3-markdown
• python3-prompt-toolkit
• python3-pygments

along with the base python3 runtime.