Codex Cleaner

面向 Codex 本地数据的安全优先清理、归档与恢复工具。

CLI 默认使用英语。通过 --lang zh-CN 或 CODEX_CLEANER_LANG=zh-CN 可切换到简体中文。

通过 npx 运行

npx @betterlmy/codex-cleaner

安全模型

• 所有修改命令默认只做 dry-run，只有提供 --apply 才执行。
• 只清理版本化 Catalog 明确列出的路径，未知路径保持保护。
• 拒绝符号链接、路径穿越、特殊文件和 Codex 数据根目录。
• 检测到 Codex 正在运行时拒绝修改。
• 已校验归档默认保存在 CODEX_HOME 之外的 ~/.codex-cleaner。
• 恢复前校验 manifest 和每个文件的 SHA-256。
• 恢复冲突默认拒绝；--replace 会先归档当前冲突数据。
• MVP 保护认证、配置、skills、hooks、memories、当前运行包、状态数据库和已归档会话。
• 会话整理调用 Codex 自身的 archive 和 unarchive，不修改私有 SQLite Schema。

原生会话归档用于减少活跃历史杂乱，不承诺释放磁盘空间。MVP 不承诺对 codex delete 永久删除的会话进行自动恢复。

常用命令

# 交互菜单，默认英语
npx @betterlmy/codex-cleaner

# 中文只读扫描
npx @betterlmy/codex-cleaner --lang zh-CN scan

# 推荐安全类别的 dry-run
npx @betterlmy/codex-cleaner --lang zh-CN clean

# 指定类别并在归档后实际清理
npx @betterlmy/codex-cleaner --lang zh-CN clean --category temp model-cache --apply

# 查看和恢复归档
npx @betterlmy/codex-cleaner --lang zh-CN archives list
npx @betterlmy/codex-cleaner --lang zh-CN restore ARCHIVE_ID
npx @betterlmy/codex-cleaner --lang zh-CN restore ARCHIVE_ID --apply

# 通过官方 Codex CLI 整理会话
npx @betterlmy/codex-cleaner --lang zh-CN sessions list
npx @betterlmy/codex-cleaner --lang zh-CN sessions archive THREAD_UUID --apply
npx @betterlmy/codex-cleaner --lang zh-CN sessions unarchive THREAD_UUID --apply

# 环境诊断
npx @betterlmy/codex-cleaner --lang zh-CN doctor

全局路径参数：

--codex-home PATH
--cleaner-home PATH
--codex-bin PATH

Codex 目录解析顺序为 --codex-home、CODEX_HOME、~/.codex。Cleaner 状态目录解析顺序为 --cleaner-home、CODEX_CLEANER_HOME、~/.codex-cleaner。

WSL2 默认只操作 WSL 用户的 Codex 目录；如需查看 Windows 侧目录，必须显式传入路径。

清理类别

| ID | 风险 | 行为 | | --- | --- | --- | | temp | 安全 | 已知 Codex 临时数据和未完成 staging。 | | model-cache | 安全 | 可重建的模型元数据和远程插件目录缓存。 | | shell-snapshots | 需复核 | 自动生成的 shell 环境快照。 | | logs | 需复核 | 文本诊断日志。 | | log-databases | 需复核 | SQLite 日志数据库及 WAL/SHM 旁路文件。 | | plugin-cache | 需复核 | 下载的插件缓存。 |

scan 会展示受保护类别，但这些类别不能被文件系统清理命令选择。

开发

要求 Node.js 20.17.0 或更高版本。

npm install
npm run typecheck
npm test
npm run check
npm pack

本地 npx 验证：

npm pack
npx --yes ./betterlmy-codex-cleaner-0.1.0.tgz --help

测试只使用独立临时 Codex 目录，不会访问真实 ~/.codex。

文档

• English README
• 软件设计

许可证

MIT