Metadata-Version: 2.4
Name: export_codex_chats
Version: 1.0.0
Summary: Export Codex chat sessions as standalone HTML transcripts.
Project-URL: Homepage, https://github.com/vsego/export_codex_chats
Project-URL: Bug Tracker, https://github.com/vsego/export_codex_chats/issues
Project-URL: Changelog, https://github.com/vsego/export_codex_chats/blob/master/CHANGELOG.md
Author-email: Vedran Sego <vsego@vsego.org>
License-Expression: MIT
Keywords: chat,codex,export,html
Classifier: Environment :: Console
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: markdown>=3.8
Requires-Dist: prompt-toolkit>=3.0.0
Requires-Dist: pygments>=2.19.0
Provides-Extra: dev
Requires-Dist: build; extra == 'dev'
Requires-Dist: coverage; extra == 'dev'
Requires-Dist: hatch; extra == 'dev'
Requires-Dist: hatchling; extra == 'dev'
Requires-Dist: pyright; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Requires-Dist: twine; extra == 'dev'
Description-Content-Type: text/markdown

# 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

```bash
pip install .
```

For development:

```bash
pip install ".[dev]"
```

## Usage

```bash
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:

```bash
./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:

```bash
./clean.sh
```

Run the static checks with:

```bash
ruff check .
pyright
```

Build and verify release artifacts with:

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

Build OS packages with:

```bash
./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.
