csift: 全面的 Claude Code 记录搜索、反查与恢复工具，帮你提前踩完会话文件的坑

wdhwg001 · 发表于 6 天前

「本文非 AI 生成，感谢阅读。如果你觉得有 AI 味，那应该是我脑子过拟合了。」

https://github.com/wdhwg001/csift

你可能觉得这个工具不需要存在。因为你的 Claude Code 的会话文件是明文的 JSONL ，任何一个 grep/ripgrep 都能扫出它的内容，并且 Claude Code 自己知道去搜自己的会话记录。

但这不解决任何实际的问题。比如说：

我的 Claude Code 开着 --dangerously-skip-permissions 把它开的项目文件删了，然后卡在原地说对不起。我让它自己读自己的会话记录把文件倒出来，然后它折腾了半天，发现编辑横跨多个 subagent ，怎么都是残的，到最后又自作主张开始重写。

再比如说：

我给一个搞前端的会话发了点设计图，然后它跨了 compaction 之后像是降智了一样，怎么都找不到那些图，然后还问我要。

又比如说：

我现在有一个 jazzy-twilight-sparkle.md 的 Plan 文件里面有很重要的架构方案，但是这个 Plan 原本的会话叫什么来着？

还有像是：

破 macOS 开了一两个月之后崩了，我之前开着三个活跃会话分别管前端、后端和 debug ，它们都叫啥？他妈的 claude --resume 怎么没个补全的。

以及：

我发誓我真的刚说过这句话，Claude Code 这个稀烂的 Compaction 真的是转头就忘，就不能有一个什么东西能像 codex 和 pi 那样机械保留几个 Turn 吗？

并且：

什么叫你搜了然后和我说，我没说过这句话？我他妈在 AskUserQuestion 里说的！

还有：

让你当 orchestrator 负责盯着那几个活动会话，结果你和我说它们 AskUserQuestion 不被回答的时候根本不落盘，所以你也没办法？或者什么叫“你说的对，我可以从 thinking 里反推出那个会话卡住的原因是要问问题”？

你踩的坑越多，你就越希望有那么一个工具，可以让 Claude Code 不会在你每次骂完了之后说一句 You are absolutely right. ，然后跌跌撞撞地去搓一个临时工具凑合着去看它的会话记录，然后再看漏，再挨你骂，你再吃一句 You are absolutely right.。

所以我做了 csift ，一个至少可以干掉目前我所有痛点的东西。而它的幕后不仅仅是那个 Claude Code 的 2.1.88 ，还有数不清的对新版本的逆向工程和因此被掐断的 Fable / Opus 会话们。

（当然，没人逼着你学一个新 CLI ）

所以它有 agent skill：（记得先装好 csift ，它不带 Binary ）

npx skills add wdhwg001/csift

然后 Claude Code 就会知道如何用 csift 处理它的会话。并且 csift 是支持结构化输出的，Claude 想要随手接一个 jq 也很方便。

带类型的 ripgrep 搜索

老实说 Claude Code 的 Context Engineering 很复杂，而这几乎导致 Claude Code 自己搓出来的工具必然是坏的。

比如我举例子，后台任务完成了的通知用什么 LLM 消息 Role ？

System ？ Tool Response ？

是 User。

Subagent 的返回用什么 Role ？

还是 User。

那么用户在 AskUserQuestion 里的回答是什么？

是 Tool Response。

你要每次都教给 Claude 吗？你要把这种东西写成 Skill 然后期待下一次 Claude 搓出来的临时小工具是对的吗？你要把这些细枝末节的东西塞进 CLAUDE.md 占用空间吗？你要期待着后面某一版 Claude Code 更新的时候把这些频繁改动且从未落进文档的细节大发慈悲地塞进 System Prompt 吗？

别挣扎了，因为我已经试过了——csift 就是踩遍了所有的坑，看遍了 Claude Code 的 minified 代码逻辑之后的工具。它有三个类型：user 、agent 、harness ，然后详细拆了这些分类：

user .message    发在输入框的那个
      .answer    AskUserQuestion 里的回答
      .rejection 所有的有理由拒绝
agent .message    Claude 做完之后说的那段总结，以及所有真说给用户的话
      .thinking    打开 --verbose 之后重写的那个 reasoning ，不是 The question asks 起手的那个
      .tool.use    Function Tool 调用
      .tool.result  Function Tool 返回
      .communication.inbox  别的 Claude 或者 Subagent 发来的消息
      .communication.sent SendMessage 发出去的
      .communication.signal 控制信号
harness .notification.workflow
      .notification.monitor
      .notification.subagent
      .notification.background-command
      .notification.task
      .compaction.summary
      .compaction.boundary
      .command.invocation
      .command.stdout
      .interrupt.user
      .interrupt.tool
      .schedule.wakeup
      .schedule.continuation
      .meta.hook
      .meta.loop

它是一个帮你踩完了所有的坑的搜索工具，而且因为是 Rust 写的，所以搜巨大的 JSONL 也不到一秒。

可靠的图片转存

你发给 Claude Code 的图片其实每一个都被存成了 Base64 ——但如果你向上翻，然后让 Claude Code 去找一个 [Image #39]，那它大概率会折腾半天然后给你交白卷，或者跌跌撞撞充满惊奇地烧半天 Token 去研究，因为图片在里面的存储结构并不很直观， #39 也不是一个唯一 ID 。

所以我填了这个坑，有 csift ，你可以直接把 JSONL 里面的图片转出来。

Plan 查询和反查

字面意思。Plan 文件的名字是第一次调用 EnterPlanMode 才生成的，csift 支持根据一个 Plan 的名字找到这个会话，或者根据一个会话找到它的 Plan 。

从 Session 里恢复文件

我希望你永远都不会用到它。但如果你真的丢了文件，而 Claude Code 读过它或者写过它，你可以试着用 csift 把它还原。

csift 支持还原到特定的时间点，支持导出 Diff 为 Patch ，并且支持识别 Claude Code 的 File Modified 提醒。

真的，我希望你永远都不会用到它，但我用到了。

查看过往的 User ↔ Agent 来回

我讨厌 Claude Code 的上下文压缩已经很久了。如果 AI 跑了几个小时，横跨好几次上下文压缩，那么你回来的时候会发现它简直像弱智一样，你说过的话大概率忘得一干二净，记得你让它做什么是它给你最后的尊重。

所以我就做了这个东西，它用来做成 hook 食用。

它和 Compaction 的目标几乎是完全正交的。上下文总结负责把任务继续下去，而 csift 负责告诉 AI ，人类会记得哪些曾经发生过什么东西。

这个补全设计至少收获了 100% 的 Claude 的好评。

其他功能

还有其他的一些东西，比如搜一些目录里的所有会话，比如让 Claude Code 自己知道自己的 session ID 是什么（包括 subagent——Claude Code 里没有任何办法让一个 subagent 知道自己的 session ID ，但 csift 提供了一个用 @trap 配合一个魔术词的方案，是唯一解），比如看整个 session 的 subagent 拓扑。

还有那个 AskUserQuestion 不落盘的事情，csift 的 skill 里给了一个标准答案，Claude Code 可以照抄它的 hooks 方案去创建一个附属 JSONL ，并且 csift 也支持搜它。

差不多就这些。自己用了几个月了，一边用一边打磨，现在发出来开源。

感谢阅读，有空试试的话，欢迎告诉我你的感想，也欢迎 Issue 和 PR 。

对了，看到这句话之后记得去给你的 Claude Code 加一句 "cleanupPeriodDays": 730,，不然它默认会删超过 30 天没动的会话文件。

（对我知道 codex 也是 “c”-sift…但是我目前主力不是 codex ，所以它和其他的 Harness 后面再说。）