开源一个 Codex 本地历史管理 CLI：从 list 到安全 purge

Codex 用久之后，本地对话历史会慢慢堆起来。这个问题本身不复杂，但清理起来并不适合靠手动改文件解决：本地数据可能分布在 SQLite、JSON、JSONL 和其他状态文件里，漏删会留下残留，误删又会破坏 Codex 的本地状态。

我最近开源了一个小工具 codex-history，它解决的是一个很具体的问题：先找到本地 Codex 对话，再用可确认、可验证的方式清理受支持的本地数据。

它不是服务端删除工具，也不是用来绕过 Codex 官方能力的工具。我的目标更保守：在本机数据结构受支持时，提供一个比手动编辑 ~/.codex 更清晰的本地清理流程。

为什么要做这个工具

我遇到的场景是：想清理某个项目相关的 Codex 会话，但不想打开本地数据库和状态文件一点点找。更麻烦的是，Codex 本地历史不是单个文件能概括的。对话列表、会话记录、全局状态、日志和一些派生文件之间可能存在引用关系。

所以我没有把这个工具设计成"传一个路径然后递归删除"的脚本，而是拆成几个明确步骤：

先检查当前数据结构是否支持。
再列出可读的本地会话。
用标题、首条用户消息、预览或 cwd 缩小范围。
删除前展示计划并要求确认。
删除后扫描受支持的本地存储，确认已知引用是否移除。

这就是 codex-history 的主线。

安装和第一步检查

安装方式：

bash 复制代码

npm install -g @liuyoumi/codex-history

也可以不安装直接运行：

bash 复制代码

npx @liuyoumi/codex-history doctor

我建议第一步永远先跑：

bash 复制代码

codex-history doctor

下面的示例截图来自临时 demo --codex-home，不包含真实用户数据：

doctor 的作用是确认当前 Codex 本地数据结构是否被这个版本支持。如果不支持，删除命令会拒绝执行，而不是猜测数据应该怎么删。

用 list 找到目标

最基础的命令是：

bash 复制代码

codex-history list

默认输出会尽量保持短，一行一条：

如果本地历史很多，可以先用关键词缩小范围：

bash 复制代码

codex-history list --grep "Purge"

这里有一个刻意的限制：--grep 只匹配显示标题、首条用户消息和预览，不匹配 thread id 或 cwd，也不会搜索完整对话正文。

原因很简单：这个工具首先是清理工具，不是全文检索工具。删除前的筛选应该足够可解释，不应该因为某个完整上下文里隐藏的词，把用户没有意识到的会话带进删除计划。

按项目路径筛选可以用 --cwd：

bash 复制代码

codex-history list --cwd codex-history --pretty=medium

--cwd 支持路径片段，所以可以输入完整路径，也可以输入项目名的一部分。

purge 为什么要确认

删除单条会话：

bash 复制代码

codex-history purge 019e7047

交互式流程会先展示解析到的目标，并要求输入短 id：

这个确认不是形式主义。purge 是不可撤销的本地破坏性操作，所以工具会要求用户在最后一步重新确认"我要删的就是这一条"。

多条删除和过滤式删除也支持：

bash 复制代码

codex-history purge 019e6885 019e6874
codex-history purge --cwd /Users/me/Projects/example
codex-history purge --grep "Astro"
codex-history purge --archived

批量或过滤式删除要求输入 purge-selected。如果任意一个目标不存在、不唯一，或者命中当前 active thread，整个批量计划会在修改数据前拒绝执行，不会部分删除。

脚本里可以加 --force：

bash 复制代码

codex-history purge 019e6885 --force

但 --force 只跳过交互确认，不会跳过数据结构校验、active thread 保护和删除后的验证。

purge-orphans 解决什么

除了正常会话，有时本地还可能留下孤儿数据。比如 threads 表还记录着某个会话，但 rollout 文件已经不存在；或者日志数据库里还有 thread id，但主线程记录已经没有了。

对应命令是：

bash 复制代码

codex-history purge-orphans

它会先展示计划、影响的 SQLite 行数、将删除的文件数量和估算的本地磁盘空间影响。确认时需要输入 purge-orphans。

发布前可以补一张计划截图，但不要为了截图去真实用户目录里制造破坏性场景。建议使用 fixture、复制后的沙盒数据，或显式临时 --codex-home。

设计取舍

第一，未知数据结构直接 fail closed。Codex 本地数据结构可能随版本变化，工具不能在未知结构上猜测删除。

第二，不做模糊删除。传入 id 或短 id 前缀时，必须解析到唯一目标。删除命令里"差不多匹配到了"是危险设计。

第三，--grep 不做全文检索。筛选删除目标时，我更看重结果可解释，而不是尽可能多地匹配。

第四，删除后做引用验证。删除执行完不代表清理成功，工具还会扫描受支持的本地存储，看目标 thread id 是否仍有已知引用。

适合群体

经常使用 Codex Desktop 或 Codex CLI 的用户。
想按项目或关键词清理本地 Codex 历史的人。
不想手动编辑 ~/.codex 的人。
希望删除前能看到明确目标和确认流程的人。

项目地址

GitHub: github.com/liuyoumi/co...

npm: www.npmjs.com/package/@li...

如果你也在用 Codex，并且遇到过本地历史不好清理的问题，可以试试看。更欢迎提 issue，尤其是不同平台或 Codex 版本下的反馈；觉得这个方向有用的话，也欢迎给个 Star 支持后续维护。