Claude Code Trace 可视化神器：Token 分析 + Agent 回放 + Session 对比，全有了

har
0 阅读5分钟

用了这个开源工具，我终于看懂了 Claude Code 在"想什么"

Claude Code 每次跑完任务，你只看到一个结果。
但它在过程中做了什么？Token 为什么爆了？哪一步跑偏了？
claude-trace-replay 让这一切可见。

先聊一个真实的崩溃现场

你让 Claude Code 重构一个模块，任务跑了 20 分钟，Token 用了 80k，最后给了你一个并不满意的结果。

你想知道哪里出了问题——是 prompt 写得不够清楚？某个 tool call 反复失败？还是 agent 在某一步陷入了循环？

打开 .jsonl 文件……一万行 JSON，眼睛开始模糊。

这就是 claude-trace-replay 想解决的问题。

项目是什么

claude-trace-replay 是一个开源的 Claude Code trace 可视化与回放工作台。

它接受 Claude Code 原生生成的 .jsonl session 文件，把里面的每一个 event——tool call、思考块、文件读写、terminal 命令、diff——变成一个可交互、可回放、可对比的可视化界面。

不需要任何外部服务，不上传任何数据，本地跑，5 分钟内上手。

Session Overview 加载一个 .jsonl trace 后，Session Overview 直接呈现 token 总量、消息数、模型版本、工具使用等全局数据

它能做什么

🎬 Agent Flow 动画回放

这是最直观的功能：把 session 里 user → agent → tool → assistant 的整个协作链路，以动画形式一步步回放出来。

你能看到主 agent 在某一步调用了哪个工具、工具返回了什么、assistant 是怎么利用这个结果继续推进的。不再是静态的日志，而是一场可以暂停和回溯的侦探剧。

Agent Flow - Bash Return Agent Flow 视图：工具调用返回时的节点高亮与链路动画，清晰展示 Bash 命令执行的上下文

agent-flow-assistant.png Assistant 回复时的 agent 流图状态，可以看到信息如何从工具结果流向最终回复

📊 Token 消耗分析

每一轮对话消耗了多少 input token、output token？哪一步是成本高峰？

Token Analytics 视图直接给你可视化的 spike 分析——费用突然变高？找到那个 turn，看看发生了什么。

Token Usage Token Usage 视图：按轮次展示 input/output token 趋势，成本高峰一眼可见

🔍 Searchable Timeline

把所有 tool call、思考过程、文件读取、terminal 命令、diff 结果，按时间轴平铺排列，支持搜索和过滤。

你不需要翻 JSONL，直接在 UI 里 Ctrl+F 就能定位到某个特定操作。

session-timeline.png Session Timeline：所有事件按时间轴排列，工具调用、diff、文件读写一目了然

⚖️ Session Compare

这是专门为"为什么这次比上次效果差"而设计的功能。

选两个 session，直接对比 message 数量、token 消耗、工具调用次数、模型版本……同一个任务，换了 prompt 或换了模型，差异一目了然。

session-compare.png Session Compare：并排对比两次运行的关键指标，prompt 改动带来的效果差异清晰可见

🤖 AI Retrospective

加载完一个 session 后，工具会自动给你生成一份复盘报告：这次 session 的优势在哪里、哪些步骤值得优化、下次可以怎么改进。

不是泛泛而谈，是基于真实 trace 数据的分析。

AI Analysis AI Analysis 视图：基于 trace 数据自动生成的复盘建议，包括优势识别和优化方向

📝 Prompt Review

专门分析 prompt 质量和 agent 协作模式，帮你理解为什么某些 prompt 能驱动更高效的工具调用链。

所有工作台视图一览

视图能学到什么
Session OverviewToken、消息数、模型、耗时、工具使用的全局概览
Session Timeline按时间轴的工具调用、diff、file read、terminal 输出
Agent Flowuser → agent → tool → assistant 的动画协作图
Conversation Flow消息的父子结构和深度可视化
Token Usage每轮消耗趋势、成本高峰识别
AI AnalysisAI 自动生成的复盘建议
Prompt Optimizerprompt 质量审查和协作模式评估
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

打开 http://localhost:3000，把你的 Claude Code .jsonl 文件拖进去，就这么简单。

Claude Code 的 session 文件在哪里？

~/.claude/projects/<你的项目路径>/<session-id>.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 链的可视化排布
  • 样例数据集：让第一次打开工具的用户直接能看到效果

如果这个工具帮你在某次 debug 中节省了时间，给个 Star ⭐ 是最好的反馈——它能帮更多有同样困扰的人找到这个项目。

→ github.com/harryletter…

把 AI coding session 从原始日志变成可视化工作台——因为你的时间不应该花在读 JSONL 上。

avatar
文章
阅读
粉丝