简体中文 | English

delete-codex-local-session

一个用于列出、预览并删除本地 Codex 会话的 Python 命令行工具，也可以作为 Codex Skill 可选使用。

本项目只处理本机 CODEX_HOME 或 ~/.codex 下的本地数据，不会删除云端、账号侧或服务端聊天记录。

Python CLI

列出本地会话：

python scripts/list_codex_sessions_by_folder.py

列出本地会话，并显示完整 rollout 文件路径：

python scripts/list_codex_sessions_by_folder.py --show-paths

显示完整标题：

python scripts/list_codex_sessions_by_folder.py --full-titles

包含数据库里存在、但 rollout 文件已缺失的会话：

python scripts/list_codex_sessions_by_folder.py --include-missing

预览某个会话会删除哪些本地数据：

python scripts/delete_codex_local_session.py <session-id>

删除某个本地会话：

python scripts/delete_codex_local_session.py <session-id> --apply

删除时保留 .codex-global-state.json：

python scripts/delete_codex_local_session.py <session-id> --apply --keep-global-state

删除时跳过 SQLite 数据库压缩：

python scripts/delete_codex_local_session.py <session-id> --apply --no-vacuum

默认情况下，--apply 会在删除 SQLite 记录后对有变更的数据库执行 VACUUM，并运行 PRAGMA wal_checkpoint(TRUNCATE) 尝试截断 WAL 文件。--vacuum 参数仍然保留用于兼容旧命令，但现在不再需要显式传入。

命令参数

scripts/list_codex_sessions_by_folder.py

• --codex-home <path>：指定 Codex 本地数据目录，默认使用 CODEX_HOME 或 ~/.codex
• --show-paths：输出完整 rollout 文件路径
• --include-missing：输出数据库中存在但 rollout 文件缺失的会话
• --title-width <number>：设置标题最大显示长度，默认 120
• --full-titles：显示完整标题，不截断

scripts/delete_codex_local_session.py

• <session-id>：要预览或删除的本地会话 ID
• --codex-home <path>：指定 Codex 本地数据目录，默认使用 CODEX_HOME 或 ~/.codex
• --apply：执行真实删除；不传时只预览
• --no-vacuum：删除 SQLite 记录后不执行 VACUUM 和 WAL checkpoint
• --vacuum：兼容旧命令；SQLite 压缩和 WAL checkpoint 现在默认启用
• --keep-global-state：不修改 .codex-global-state.json
• --title-width <number>：设置标题最大显示长度，默认 120
• --full-titles：显示完整标题，不截断

删除范围

删除脚本会按 session ID 清理这些本地数据：

• sessions/ 和 archived_sessions/ 下匹配的 rollout transcript 文件
• session_index.jsonl 中匹配的索引项
• state*.sqlite 中 threads、thread_dynamic_tools、thread_spawn_edges 的匹配记录
• logs*.sqlite 中匹配的日志记录
• generated_images/<session-id>/ 图片目录
• .codex-global-state.json 中与该 session ID 精确匹配的键或值

安全机制

• 默认只预览，不删除
• 只有传入 --apply 才会执行删除
• 默认会对有删除变更的 SQLite 数据库执行 VACUUM 和 WAL checkpoint
• 建议先关闭 Codex app，避免界面缓存旧状态
• 如果 Codex app 或其他进程仍打开数据库，WAL 文件可能无法立即截断
• 如果删除后界面仍显示旧线程，可以先最小化并恢复 Codex app；仍未刷新时再重启

可选 Skill 用法

本仓库保留 Codex Skill 入口，但推荐优先使用 Python CLI。Skill 更适合在 Codex 对话中辅助生成、确认和执行明确的命令。

安装到 Codex skills 目录：

~/.codex/skills/delete-codex-local-session/

目录结构：

delete-codex-local-session/
├── SKILL.md
├── agents/
│   └── openai.yaml
└── scripts/
    ├── list_codex_sessions_by_folder.py
    └── delete_codex_local_session.py

示例：

用 $delete-codex-local-session 列出本地会话 id 和标题
用 $delete-codex-local-session 预览本地会话 019d...
用 $delete-codex-local-session 删除本地会话 019d...

运行要求

• Python 3
• 不依赖第三方 Python 包

仓库内容

• SKILL.md：可选 Skill 入口说明
• agents/openai.yaml：Codex UI 元数据
• scripts/list_codex_sessions_by_folder.py：列出本地会话
• scripts/delete_codex_local_session.py：预览并删除本地会话
• docs/images/：README 示例截图资源

限制

• 仅清理本地数据，不会删除服务端或账号层面的聊天记录
• Codex 本地目录结构、SQLite 表结构和内部存储方式未来可能变化，使用前应先运行预览模式确认结果