Keep Codex Fast：让 Codex 本地状态保持轻快的安全维护技能

一句话定位

Keep Codex Fast 是一个面向 Codex 重度用户的本地状态维护 Skill：先检查、先交接、先备份，再把旧会话、日志、临时工作区等“拖慢体验”的本地状态安全归档。

基础信息卡片

解决什么问题

Codex 用久之后，很多人会遇到一种不太容易定位的“变重”：

• 长对话越积越多；
• 经常恢复旧线程；
• 同时维护多个仓库；
• 本地终端、开发服务器、日志、工作区持续堆积；
• 想清理，又担心误删历史上下文。

Keep Codex Fast 关注的不是“让模型回答更快”，而是整理 Codex 在本机留下的运行状态。它的核心原则很克制：

Make handoffs first. Archive, don’t delete. Apply changes only when you are ready.

也就是：先做交接文档，归档而不是删除，只有在你确认准备好时才真正应用改动。

这对长期使用 Codex 做开发的人很实用。因为真正让人犹豫清理的，往往不是文件本身，而是旧会话里还藏着项目决策、排错过程、失败命令和下一步计划。Keep Codex Fast 把“清理”拆成了更安全的流程：先看清楚，再保留可恢复的上下文，最后再归档。

核心功能

  flowchart TD
    A[Codex 本地状态变重] --> B[只读检查]
    B --> C[生成维护报告]
    C --> D{是否还有重要旧会话?}
    D -- 有 --> E[创建 handoff 交接文档]
    E --> F[备份重要状态]
    D -- 没有 --> F
    F --> G[归档旧会话/旧工作区]
    G --> H[轮转大日志]
    H --> I[清理失效项目引用]
    I --> J[再次检查并确认结果]

这张流程图里最关键的是第一步：默认只读检查。Keep Codex Fast 不会一上来就移动文件或删除历史，而是先报告本地状态，让你知道问题主要来自哪里。

1. 默认只读报告

项目 README 明确说明：默认模式只做报告，不写文件、不创建备份、不移动目录，也不会修改本地 Codex 状态。它会帮助你看到哪些本地状态增长明显，例如活跃会话、归档会话、日志、旧工作区、失效项目引用以及较重的 Node/开发进程。

这让第一次使用的心理负担比较低：你可以先把它当成一次体检，而不是一次清理操作。

2. Handoffs First：先交接，再归档

Keep Codex Fast 特别强调 handoff 文档。所谓 handoff，就是一份小型连续性笔记，记录：

• 当前在做什么；
• 已经改了什么；
• 哪些文件重要；
• 已经跑过哪些命令或检查；
• 还有什么错误、警告或未决问题；
• 下一步应该怎么继续。

有了这份文档，你就可以把沉重的旧聊天归档，然后在新的 Codex 会话里从 handoff 继续，不必一直依赖越来越长的历史线程。

3. 备份优先，归档而不是删除

真正执行维护时，Keep Codex Fast 的策略也是保守的：先备份重要状态，再把旧会话、旧工作区、大日志移动到归档位置。它处理的是“从热路径移走”，而不是“永久删除”。

根据项目说明，它可以处理的内容包括：

• 旧的非置顶活跃会话；
• 过期 worktrees；
• 较大的 logs_2.sqlite* 日志文件；
• config.toml 中失效或临时项目引用；
• Windows \\?\C:\... 这类扩展路径不一致问题；
• 较重的 Node/开发进程报告。

4. 手动应用，不建议自动清理

项目也给出了一个很重要的边界：周期性维护更适合做“提醒”和“报告”，不适合自动执行清理。原因很简单，自动化并不知道哪些旧会话对你仍然重要，也不知道 handoff 是否已经准备好。

所以更稳妥的方式是：定期检查，人工确认，然后在 Codex 关闭或明确等待 Codex 退出后再应用维护。

适合谁

Keep Codex Fast 更适合这些 Codex 用户：

• 每天高频使用 Codex 做开发；
• 经常跨多个仓库工作；
• 习惯保留很长的历史会话；
• 经常恢复旧线程继续排错或开发；
• 本地同时运行多个终端、服务或 worktree；
• 想清理 Codex 本地状态，但不想冒丢上下文的风险。

如果你只是偶尔打开 Codex 问几个问题，可能暂时感受不到它的价值。但只要 Codex 已经成为日常开发工作流的一部分，这类“本地状态维护”就会越来越重要。

快速上手

在 Codex 中可以直接让它安装这个 Skill：

Install the keep-codex-fast skill from https://github.com/vibeforge1111/keep-codex-fast

安装后，先做一次只读检查：

Use $keep-codex-fast to inspect my Codex local state and recommend a safe maintenance plan.

如果检查结果显示有旧会话值得归档，先为还可能继续的项目创建 handoff：

Create a comprehensive handoff document for this repo/session before I archive Codex history.

Include:
- repo/path and branch
- current goal
- what we already completed
- files touched or investigated
- commands/tests already run
- known errors, warnings, or failing checks
- open decisions
- constraints, user preferences, and do-not-touch areas
- the next 3-7 concrete steps

Also include a reactivation prompt I can paste into a fresh Codex chat so it can continue from this handoff without relying on the old chat context.

确认重要会话都有交接文档后，再考虑应用安全维护：

Use $keep-codex-fast to apply safe Codex maintenance.

Before changing anything, confirm that important active repo chats have handoff docs or do not need them.

Then back up first, archive instead of deleting, move stale worktrees, rotate large logs, prune dead config references, and verify the result.

If Codex is currently running, do not mutate local state. Tell me to close Codex first.

如果你想直接运行脚本，项目也提供了命令行方式：

python scripts/keep_codex_fast.py

只读报告之外，还可以按需使用：

python scripts/keep_codex_fast.py --details
python scripts/keep_codex_fast.py --backup-only
python scripts/keep_codex_fast.py --apply --archive-older-than-days 10 --worktree-older-than-days 7
python scripts/keep_codex_fast.py --apply --wait-for-codex-exit

结论

Keep Codex Fast 的价值不在于做一次“激进清理”，而在于把 Codex 本地维护变成一个可控流程：先报告，先交接，先备份，再归档。

对重度 Codex 用户来说，旧会话和本地状态既是负担，也是资产。这个项目提供的思路很实用：把真正有价值的上下文沉淀成 handoff，把不需要长期留在热路径里的状态移出去，让新的 Codex 会话重新变轻。

如果你已经明显感觉 Codex 本地使用体验变重，Keep Codex Fast 值得先跑一次只读检查。即使暂时不执行清理，它也能帮你看清楚：到底是哪些本地状态在增长，以及后续应该怎样安全地处理。