Zoetrope

这是什么？适合谁？

Zoetrope（furkankly/zoetrope）把 Claude Code 会话实时可视化为流程图，在你的终端或浏览器里。Claude Code 为 ~/.claude/projects/ 下的每个会话写 JSONL 转录；zoetrope 读取它，把会话画成一张图：主 Agent、它派生的 subagent 和 workflow，以及每个运行的工具，实时更新。

它解决的问题：看懂一个复杂的 Agent 会话——主 Agent 派生了哪些子 Agent、每个执行了什么工具、谁卡住了、谁成功了——而不是翻几百行 JSONL。

核心能力：

• 图：每个 Agent 一个节点（主会话、subagent、带子节点的 workflow 组）；每张卡片显示状态、当前工具、工具数、输出 token；边在 Agent 工作时动画、结束时定格
• 时间旅行：live 和 replay 共用一条可拖动的 timeline，按事件索引而非墙钟；seek 回退能看到会话在那一刻的精确状态（Agent 未完成、工具数回落、图收缩）
• 检查：点任意 Agent 看它的 provenance——派生的 prompt、推理、模型、每个工具调用及耗时；zoe inspect 无头打印整棵树

定位：Agent 行为调试、教学演示、以及「这个人跑了一个多小时到底在干嘛」的复盘利器。读-only，零网络。

适合人群：重度 Claude Code 用户；想给团队演示 Agent 工作过程的人；需要 debug Agent 为什么卡住/绕圈的工程师。

准备工作

1. 安装方式（三选一）：
   • Homebrew（macOS/Linux）：brew install furkankly/tap/zoetrope
   • Cargo（需 Rust 工具链）：cargo install zoetrope
   • 预编译二进制：从 release 下载解压，把 zoe 放 PATH
2. 成本：MIT 开源，免费；零网络（依赖树里没有 HTTP client，tokio 未启 net feature）。
3. 无安装即用：浏览器版 zoetrope.furkankly.dev/app 直接拖入转录文件。
4. 时间预算：安装 2 分钟；zoe 启动即用。

快速上手（3 步）

第一步：安装

brew install furkankly/tap/zoetrope    # 命令是 zoe

第二步：跟随当前会话

zoe                 # 跟随当前项目的 live 会话
zoe <dir>           # 跟随另一个项目的会话
zoe <file.jsonl>    # 从头 replay 一段录制
zoe <file.jsonl> --follow   # 在 live 边缘打开录制

第三步：用时间轴回看

space 播放/暂停 · [ ] 上一个/下一个 prompt · End/g 跳到 live · 拖进度条 seek。

成功判定：你看到主 Agent 和它派生的 subagent 组成流程图，工具调用以 chip 形式出现在各自节点下（⚒ bash ×5），并在执行中实时更新。

初级用法

给文件或目录

给一个文件，它读完整转录后继续监听新行；给目录（或不给参数），它找该项目最新会话并 live 跟随。无论哪种启动方式，控制键相同：scrub、follow、pause、跳回 live。

检查单个 Agent

点任意 Agent 看 provenance：派生的 prompt、推理、模型、每个工具调用及耗时。zoe inspect <file.jsonl> 无头打印整棵树，无需 TTY。

会话信息覆盖层

i 键看 mode、permissions、queued ops、file edits、last prompt。

高级玩法

时间旅行的精确性

zoetrope 把转录当append-only 事件日志：tail 文件、防御性解析每行、折叠成 Agent/工具/prompt 的派生模型。模型是「所见事实」的纯函数，所以 seek 回退是精确的。

两时钟分离

内容时间来自转录自己的时间戳；呈现时间是你能控制的 playhead。所有 pacing 决定（速度、gap 压缩、scrub）只动第二个钟，显示选择永远无法改变会话记录的内容。

无网络可证明

依赖树里没有 HTTP client，tokio 未带 net feature，cargo tree 就是证明。这是可检查的性质，不是承诺。

小技巧

1. s 键 gap 压缩：跳过死空气，快进看关键动作。
2. o/f 切换镜头：Overview 看全局，Follow 让镜头跟随刚有动作的 Agent。
3. r 重新布局：图乱了按 r 整理。
4. 浏览版即开即用：不想装就直接 拖转录进浏览器，本地处理。
5. 格式变了也不崩：未识别的 record 跳过而非致命，Claude Code 更新导致渲染异常时开 issue。

常见踩坑

踩坑 1：Claude Code 更新后渲染异常

• 现象：升级 Claude Code 后某些 record 渲染奇怪。
• 原因：JSONL 转录格式是 Claude Code 内部的、未文档化，可能无预警变化。
• 解决：zoetrope 设计为降级而非崩溃（跳过未知 record）；持续异常开 issue。

踩坑 2：以为会联网

• 现象：担心会话数据外发。
• 原因：误解网络行为。
• 解决：依赖树里零 HTTP client、tokio 未启 net，零网络可证明；会话从不出机器。

踩坑 3：误用 zoe 参数

• 现象：给目录想 replay，结果一直在 live 跟随。
• 原因：目录/无参数 = 找最新会话 live 跟随；只有给 .jsonl 文件才是 replay。
• 解决：想 replay 给具体文件路径；--follow 在录制边缘打开。

踩坑 4：期望它读非 Claude Code 会话

• 现象：想可视化 Codex/Cursor 的会话。
• 原因：zoetrope 读的是 Claude Code 的 JSONL 转录格式。
• 解决：目前只支持 Claude Code 会话；其他 Agent 用别的可视化工具（如 AgentTrail）。

踩坑 5：播放速度不适

• 现象：replay 太快/太慢。
• 原因：默认播放速度 8.0。
• 解决：zoe <file> --speed N 调整。

常见问题 FAQ

Q1: zoetrope 和 AgentTrail 有什么区别？

A: 都做 Agent 可视化，但对象和粒度不同。zoetrope 专注 Claude Code 的 JSONL 转录，画「主 Agent + subagent + workflow + 工具」的流程图和时间旅行；AgentTrail 是跨 Agent（Claude Code/Codex/Cursor）的「组件地图 + 文件变更」可观测层。zoetrope 回答「这次会话里谁做了什么」，AgentTrail 回答「项目里 Agent 正在改哪些组件」。

Q2: 数据会离开机器吗？

A: 不会。读-only，零网络（依赖树无 HTTP client），无遥测。

Q3: 支持 replay 还是只支持 live？

A: 两者都支持，且共用同一条 timeline：finished run 按会话自身时间戳重放，running 会话实时跟随。

Q4: 需要安装吗？

A: 可三选一：Homebrew、Cargo、预编译二进制；甚至不装——浏览器版拖转录文件即用（WASM 编译，同样本地处理）。

Q5: 支持哪些平台？

A: macOS（Apple Silicon/Intel）、Linux（musl/arm64/x86_64）、Windows（x86_64）预编译二进制均提供。

进阶学习建议

掌握基础后，建议深入：

1. Agent 行为复盘：把长时间会话 replay 并用时间旅行 seek 回关键决策点，定位「Agent 绕圈/派了多余 subagent」的根因，反哺 prompt 优化。
2. 教学演示：用 zoetrope 把一次真实任务的过程投屏演示，展示 Agent 如何分解任务、调用工具。
3. provenance 审计：用 zoe inspect 无头导出整棵会话树，脚本化分析工具调用耗时与 subagent 结构。

参考链接

• 官方仓库
• 浏览器版
• ratatui（终端 UI 框架）

最后更新：2026-08-27 · 作者：MagicNetWorld · 基于公开资料整理，关键数据经 GitHub API 独立实测核验，AI 辅助生成