zoetrope

zoetrope 是一款开源工具，旨在以直观的动态流程图形式，实时展示 Claude Code 的会话过程。它通过读取 Claude Code 在本地生成的 JSONL 转录文件，将复杂的代理交互、子代理生成及工具调用转化为清晰的视觉图表。无论是正在运行的会话还是已完成的记录，zoetrope 都能提供“时间旅行”般的回溯与检查能力，且全程只读、离线、零网络请求。

核心可视化功能

• 动态代理图谱：
  • 节点代表代理：清晰展示主会话、生成的子代理以及嵌套的工作流组。
  • 状态实时反馈：每个节点卡片显示当前状态、正在使用的工具、工具调用次数及输出 Token 数。
  • 动画效果：代理工作时边线流动动画，完成后静止，直观呈现工作进度。
  • 工具调用芯片：以芯片形式展示工具调用（如 ⚒ bash ×5），并在执行期间显示滴答动画，最终以 ✓ 或 ✗ 标记结果。
• 智能视图管理：当图表超出屏幕范围时，自动显示小地图（Minimap）辅助导航。

“时间旅行”与回放控制

zoetrope 独创了基于事件索引而非挂钟时间的 Timeline 机制：

• 统一的时间轴：实时会话与历史回放共用同一个可拖动的时间轴。
• 事件驱动缩放：繁忙的一分钟会占据更多空间，而空闲时间可以被压缩，确保关键操作不被遗漏。
• 精确回溯：向后拖动播放头，图表会精确还原到该时刻的状态——代理取消完成、工具计数减少、图表结构缩小，仿佛时光倒流。
• 灵活控制：支持暂停、步进、跳跃至实时边缘，以及可选的空闲时间压缩。

深度检查与调试

• 点击洞察：点击任意代理节点，即可查看其来源提示词、推理过程、所用模型及每次工具调用的详细时间戳。
• 会话全景：叠加显示会话模式、权限状态、排队操作、文件编辑记录及最后一条提示词。
• 无头模式：通过 zoe inspect 命令可在终端中以文本树状结构打印完整会话信息，便于在无图形界面环境下调试。

隐私与安全：可证明的零网络

• 纯本地运行：zoetrope 仅读取 ~/.claude/projects/ 下的本地文件，没有任何数据离开你的机器。
• 技术验证：其依赖树中不包含任何 HTTP 客户端，tokio 也在禁用 net 功能的情况下引入。用户可以通过 cargo tree 自行验证这一安全属性。
• 只读访问：不对原始转录文件进行任何修改，确保数据的完整性与安全性。

安装与使用

1. 安装方式

• Homebrew (macOS/Linux):

  brew install furkankly/tap/zoetrope
  

• Cargo (Rust):

  cargo install zoetrope
  

• 预编译二进制:
  从 GitHub Releases 下载对应平台（macOS, Linux, Windows）的二进制文件，解压后将 zoe 加入 PATH。
• 浏览器免安装:
  直接访问 zoetrope 网页版，将 JSONL 转录文件拖放到页面即可生成图表。

2. 基本用法

# 实时跟随正在运行的会话
zoe

# 回放已完成的会话
zoe /path/to/session.jsonl

# 无头模式检查会话
zoe inspect /path/to/session.jsonl

工作原理

zoetrope 将 Claude Code 的转录文件视为一个仅追加的事件日志。它通过 tail 命令监听文件变化，防御性地解析每一行，并将其折叠为代理、工具调用和提示词的派生模型。由于模型是所见事实的纯函数，因此向后查找具有数学上的精确性。其核心渲染引擎被封装为一个可移植库，同时支撑着原生终端应用和 WebAssembly 浏览器应用。