Claude Code 的会话记录存在哪

Claude Code 把每个会话存成 home 目录下的一个 JSONL 文件：

~/.claude/projects/<项目目录>/<会话 id>.jsonl

<会话 id> 就是传给 claude --resume 的 UUID。部分 CLI 版本还会维护 sessions-index.json；Sessions Viewer 扫描 JSONL 不要求这个索引存在。

项目目录名怎么来的

Claude Code 把项目的绝对路径里每一个 / 换成 -，开头那个也换，得到目录名：

/Users/me/apps/blog   →   -Users-me-apps-blog

Windows 的路径分隔符和盘符冒号也会替换（E:\work\blog → E--work-blog）。名称中本来就有短横线时，编码不能反向还原；确认项目应优先看记录里的 cwd，不要只猜目录名。

Claude Code 的一条记录长什么样

一行一个 JSON 对象，用 type 区分：

{"type":"user","message":{"role":"user","content":[{"type":"text","text":"..."}]}}
{"type":"assistant","message":{"role":"assistant","content":[{"type":"thinking","thinking":"..."},{"type":"tool_use","name":"Edit","input":{}}]}}

整段对话都在 message.content 这个数组的块里：

块 type	内容
text	普通文本
thinking	扩展思考（模型产生了才有）
tool_use	一次工具调用：name 加一个 input 对象
tool_result	结果，靠 tool_use_id 和调用配对
image	粘贴的图是 source.base64，引用的是 source.url

记录层面还有别的 type，比如会话被改过名字时的 custom-title。

结构化 diff

文件编辑的 tool_result 回来时常常带一个 structuredPatch 字段：已经按 hunk 切好的 diff，而不是一坨文本。有这个字段，编辑才能渲染成真正的 diff。

在终端里读 Claude Code 会话

提取用户和助手的文本，不包含工具和图片：

jq -r 'select(.type=="user" or .type=="assistant")
  | .message.content
  | if type=="string" then . else .[]? | select(.type=="text") | .text end' \
  ~/.claude/projects/-Users-me-apps-blog/<会话 id>.jsonl

统计调用过哪些工具，按次数排：

jq -r '.message.content[]? | select(.type=="tool_use") | .name' \
  ~/.claude/projects/*/*.jsonl | sort | uniq -c | sort -rn

找出动过某个文件的会话：

grep -l "src/api.ts" ~/.claude/projects/*/*.jsonl

怎么恢复这个会话

在项目目录运行 claude --resume SESSION_ID，需要已安装 Claude Code。也可以使用应用的终端或内置对话。继续对话可能调用配置的服务商，并追加新记录。

依据与限制

实现依据：Claude Code 适配器。上游：Claude Code 文档。

**参考范围：**2026-10-05 对照 Sessions Viewer 0.6.0 的适配器源码核对，不代表验证过每个 CLI 版本。Shell 示例使用 macOS/Linux 路径，需要 jq（opencode 用 sqlite3）；占位符要替换成实际值，自定义目录以你的配置为准。提取文本不等于完整还原工具、图片或会话树当前分支。命令回归使用可下载的合成样本，不读取私人会话；验证边界见能力与证据矩阵。浏览历史与恢复、编辑数据不同，见隐私与数据处理。

找不到记录？按排障清单检查。

或者用应用打开

具体步骤和手动／GUI 取舍见 Claude Code 搜索、导出与恢复流程。

Sessions Viewer 直接读这些文件。已记录且受支持的思考块、配对工具、structuredPatch diff 和图片呈现为可读视图，历史浏览不重写原文件。选中 Claude Code 后，⌘⇧F 跨其项目搜索标题与用户提问；见搜索与展示限制。它同时还读 Codex、Grok Build、Kimi Code、Pi、Antigravity CLI 和 opencode。