用了这款开源工具，我终于能看透Claude Code的思考过程
先聊聊一个真实的崩溃现场
想象一下这个场景：你让 Claude Code 重构一个模块，任务跑了 20 分钟，耗费了 80k Token，但最终交付的结果却令人失望。
问题究竟出在哪里？是 prompt 写得不够清晰，某个 tool call 反复失败，还是 AI agent 在某个步骤陷入了死循环？
当你打开 .jsonl 文件的那一刻，面对上万行 JSON 数据，眼睛瞬间就花了。
这正是 claude-trace-replay 想要解决的核心痛点——让 Claude Code 的每一次执行过程清晰可见。
项目是什么
简单来说，claude-trace-replay 是一个开源的 Claude Code trace 可视化与回放工作台。它专门解析 Claude Code 生成的 .jsonl session 文件，将每一个 event——包括 tool call、思考块、文件读写、terminal 命令、diff 差异——转化为一套可交互、可回放、可对比的可视化界面。
无需外部服务，不用上传任何数据，本地即可运行，5 分钟就能上手体验。
加载一个 .jsonl trace 后，Session Overview 直接呈现 token 总量、消息数、模型版本、工具使用等全局数据
它能做什么
? Agent Flow 动画回放
这是最直观的核心功能。将 session 中 user → agent → tool → assistant 的完整协作链路以动画形式一步步回放。你可以清晰看到主 agent 在某个步骤调用了哪个工具、工具返回了什么内容、assistant 如何利用这个结果继续推进任务。不再是静态的日志，而是一场可以随时暂停和回溯的推理大戏。
Agent Flow 视图：工具调用返回时的节点高亮与链路动画，清晰展示 Bash 命令执行的上下文
Assistant 回复时的 agent 流图状态，可以看到信息如何从工具结果流向最终回复
? Token 消耗深度分析
每一轮对话消耗了多少 input token 和 output token？哪一步是成本高峰？Token Analytics 视图直接给出可视化的 spike 分析——当费用突然飙升时，找到那个 turn 点进去查看具体发生了什么。
Token Usage 视图：按轮次展示 input/output token 趋势，成本高峰一眼可见
? 可搜索的时间线（Searchable Timeline）
所有 tool call、思考过程、文件读取、terminal 命令、diff 结果按时间轴平铺排列，支持搜索与过滤。无需再手动翻阅 JSONL 文件，直接在 UI 中 Ctrl+F 即可定位到某个特定操作。
Session Timeline：所有事件按时间轴排列，工具调用、diff、文件读写一目了然
⚖️ 双 Session 对比（Session Compare）
这个功能专治“为什么这次比上次效果差”的困惑。选择两个 session，直接对比 message 数量、token 消耗、工具调用次数、模型版本等关键指标。同一个任务，换了 prompt 或换了模型，差异一目了然。
Session Compare：并排对比两次运行的关键指标，prompt 改动带来的效果差异清晰可见
? AI 复盘分析（AI Retrospective）
加载完一个 session 后，工具会自动生成一份复盘报告：这次 session 的优势在哪里、哪些步骤值得优化、下次可以如何改进。这不是泛泛而谈，而是基于真实 trace 数据的精准分析。
AI Analysis 视图：基于 trace 数据自动生成的复盘建议，包括优势识别和优化方向
? Prompt 审查（Prompt Review）
专门分析 prompt 质量和 agent 协作模式，帮助你理解为什么某些 prompt 能驱动更高效的工具调用链，从而优化你的提示词策略。
所有工作台视图一览
| 视图 | 能学到什么 |
|---|---|
| Session Overview | Token、消息数、模型、耗时、工具使用的全局概览 |
| Session Timeline | 按时间轴查看工具调用、diff、file read、terminal 输出 |
| Agent Flow | user → agent → tool → assistant 的动画协作图 |
| Conversation Flow | 消息的父子结构及深度可视化 |
| Token Usage | 每轮消耗趋势、成本高峰识别 |
| AI Analysis | AI 自动生成的复盘建议与优化方向 |
| Prompt Optimizer | prompt 质量审查与协作模式评估 |
| Session Compare | 两个 session 的 diff 对比 |
| Real-Time Log | 原始事件流实时查看 |
5 分钟快速上手
git clone https://github.com/harrylettering/claude-trace-replay.git
cd claude-trace-replay
npm install
./start.sh打开 https://localhost:3000，把你生成的 Claude Code .jsonl 文件拖进去——就这么简单。
Claude Code 的 session 文件存放在哪里？
~/.claude/projects/<你的项目路径>/.jsonl 技术栈
这个项目本身也是一个值得参考的前端工程范例——
- React 18 + TypeScript 5，全量类型覆盖
- Vite 5 构建，开发体验流畅
- React Flow / XYFlow 驱动 Agent Flow 的动态图可视化
- Recharts 处理 Token 分析图表
- Framer Motion 提供流畅的动画过渡
- Zustand 管理全局 session 状态
- Tailwind CSS 样式系统
为什么值得关注
如今 Claude Code 已经成为许多工程师日常开发的主力工具，但它的“可观测性”一直是一个盲区——你知道它完成了任务，却不知道它如何完成、为什么有时格外缓慢、为什么有时偏离方向。
claude-trace-replay 做的事情，本质上就是把 AI coding agent 的行为从“黑盒”变成“透明玻璃盒”。
这对以下几类人特别有价值：
- 天天使用 Claude Code 的独立开发者：定位那个让 token 暴涨的 turn，下次巧妙避开
- 在团队中推广 AI 编码工作流的开发者：把真实 trace 变成可共享的协作复盘材料
- 研究 agent 行为的工程师：深入理解 LLM agent 在真实任务中的决策路径
- 希望优化 prompt 的人：对比两个 session，清晰看到 prompt 差异带来的行为变化
开源，MIT 协议，欢迎贡献
项目在 GitHub 完全开源，遵循 MIT 协议。目前有几个方向特别欢迎社区参与：
- Parser 改进：支持更多 trace 格式和字段解析
- 大 session 性能优化：超长 session 的渲染与可视化密度提升
- 更多 Flow 布局模式：复杂 agent 链的可视化排布优化
- 样例数据集：让首次打开工具的用户能立即看到效果
把 AI coding session 从原始日志变为可视化工作台——因为你的时间不应该浪费在阅读 JSONL 上。