Metadata-Version: 2.4
Name: codex-export
Version: 0.1.0
Summary: Convert Codex Desktop session files to HTML conversions
License-Expression: Apache-2.0
Requires-Dist: click>=8.1.8
Requires-Dist: jinja2>=3.1.6
Requires-Dist: markdown>=3.8
Requires-Dist: questionary>=2.1.1
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# codex-export

把 Codex Desktop 的本地 `.jsonl` 会话记录，以及导出的 `.json` / `.jsonl` session 文件，转换成适合浏览的 HTML export 页面，整体交互和结构参考 `claude-code-transcripts-main`，但解析逻辑适配 Codex 客户端真实 session 格式。

## 安装

如果你只是想直接安装这个命令行工具，推荐：

```bash
git clone git@github.com:allojohn/codex-transcripts.git
cd codex-transcripts
uv tool install .
```

安装完成后可以运行：

```bash
codex-export --help
```

如果 `codex-export` 找不到，通常是因为 `~/.local/bin` 还没加到 `PATH`。可以执行：

```bash
uv tool update-shell
```

如果你是在本仓库里做开发，再使用：

```bash
uv sync
```

然后用开发模式运行：

```bash
uv run codex-export --help
```

## 用法

直接从本地最近会话里挑选：

```bash
uv run codex-export
uv run codex-export local
```

转换指定会话文件：

```bash
uv run codex-export json ~/.codex/sessions/2026/03/31/rollout-xxxx.jsonl -o ./output
uv run codex-export json ~/.codex/sessions/2026/03/31/rollout-xxxx.jsonl --open
```

也支持从 URL 直接拉取 JSON/JSONL：

```bash
uv run codex-export json https://example.com/session.jsonl -o ./output
```

上传到 GitHub Gist 并拿到预览链接：

```bash
uv run codex-export json ~/.codex/sessions/2026/03/31/rollout-xxxx.jsonl --gist
uv run codex-export --gist
```

批量生成归档：

```bash
uv run codex-export all -o ./codex-archive
uv run codex-export all --dry-run
```

如果没有传 `-o/--output`，`local` 和 `json` 会默认写到临时目录；当没有传 `-o`、没有启用 `--gist`、也没有启用 `-a/--output-auto` 时，会自动打开结果页。

## 命令

- `local` / 默认命令：从 `~/.codex/sessions` 读取最近本地会话
- `json`：转换指定 `.json` / `.jsonl` 文件，或远程 URL
- `all`：转换本地全部会话，生成可浏览 archive

Codex 没有对应 Claude 项目里的 `web` 会话 API 导入能力，所以这里没有实现 `web` 子命令。

## 输出选项

`local` 和 `json` 支持这些选项：

- `-o, --output DIRECTORY`：输出目录；默认写到临时目录
- `-a, --output-auto`：自动按 session 文件名创建子目录
- `--source PATH`：仅 `local` 支持，自定义本地会话目录
- `--limit INTEGER`：仅 `local` 支持，控制交互列表里展示多少个最近会话
- `--open`：生成后打开 `index.html`
- `--gist`：上传 HTML 到 GitHub Gist 并输出 `gisthost.github.io` 预览链接
- `--json`：把原始 session 文件一起复制到输出目录

生成结果的页面结构是：

- `index.html`：索引页，只展示每个 turn 的 user 摘要
- `page-001.html`、`page-002.html` ...：完整消息分页，包含 assistant、tool call、tool result、commentary 等完整内容

## 批量归档

`all` 命令会生成三层结构：

- 总索引页：列出所有 workspace
- 每个 workspace 的索引页：列出该 workspace 下的 sessions
- 每个 session 的 export 页面

默认会排除 agent / subagent sessions；只有加上 `--include-agents` 才会把这些会话也纳入归档。

`all` 支持这些选项：

- `--source DIRECTORY`：源目录，默认 `~/.codex/sessions`
- `-o, --output DIRECTORY`：输出目录，默认 `./codex-archive`
- `--include-agents`：包含 agent / subagent sessions
- `--dry-run`：只预览会转换哪些内容，不写文件
- `--open`：生成后打开 archive 首页
- `-q, --quiet`：安静模式，只输出错误

## 当前支持

- `local`：交互式选择最近本地会话
- `json`：转换本地或远程 `.json` / `.jsonl`
- `all`：按 workspace 分组生成 archive
- `-a / --output-auto`
- `--json`
- `--open`
- `--gist`：上传生成的 HTML 到 GitHub Gist，并输出 `gisthost.github.io` 预览链接
- 多页转写：按 Codex turn 分页
- Gist 预览修复：自动注入相对链接修复脚本，保证分页和锚点在 `gisthost.github.io` 下可用

## 给 Agent 的一句话说明

可以直接把下面这段话复制给 agent：

> Read `/Users/allojohn/www.allojohn.com/code.allojohn.com/codex-transcripts/README.md` to learn how `codex-export` works. Then ask me which Codex session I want to convert, whether I want local HTML, gist HTML, archive output, or just the source JSONL copied out, and run the right command for me.

如果你想让 agent 更主动一点，也可以用这个版本：

> Read `/Users/allojohn/www.allojohn.com/code.allojohn.com/codex-transcripts/README.md` and use it to operate `codex-export` for me. First ask me which session I want to export and whether I want `index.html` plus paged export files locally, a GitHub Gist preview link, a full archive, or the original session JSONL copied into the output directory. Then run the correct command and tell me where the result was generated.

## 已知限制

- `local` / `all` 目前只扫描 Codex 本地 `.jsonl` 会话目录，不读 SQLite 历史库
- `reasoning.encrypted_content` 不会解密，只会显示可见 summary
- 一些 `event_msg` 是 `response_item` 的重复镜像，页面里会去重并优先展示最终可读消息
- `--gist` 依赖 `gh` 已安装且完成 `gh auth login`
- `web` 子命令未实现，因为目前没有对应的 Codex Web session 导入接口
