Build Timeline 是一个用于生成 Claude Code 开发活动可视化时间线的工具。它的核心作用是把 Claude Code 的对话日志和项目的 git 历史转换成一份漂亮的、可交互的独立 HTML 时间线，用于回顾和展示一个项目是如何借助 Claude Code 构建出来的。
用途
当用户希望可视化构建过程、展示项目是如何被构建的、记录开发历史、生成构建过程走查、生成时间线、展示智能体活动、展示 Claude Code 的开发工作流，或回顾某次构建会话中发生了什么时，可以使用该工具。
主要能力
- 解析 Claude Code 存储在 ~/.claude/projects/ 下的 .jsonl 对话日志，识别其中的消息、工具调用、工具结果、文本块等事件类型。
- 提取多种工具调用信息，包括 Agent（智能体派生）、Bash（Shell 命令）、Read、Write、Edit、Glob、Grep、TaskCreate、TaskUpdate、TaskList、SendMessage 等。
- 解析 git 历史，按提交获取哈希、作者、日期、提交信息以及变更文件列表和状态（新增、修改、删除），并统计整体变更。
- 按时间接近度（约 5 分钟内）将对话事件与 git 提交关联起来，把“Claude 在做什么”和“提交了什么”对应上。
- 合并对话事件、git 提交、错误与重试，按时间顺序排列成统一时间线。
- 在启用 --phases 时自动检测阶段，依据 git 提交前缀、智能体命名、超过 30 分钟的时间间隔以及用户消息划分阶段，并为每个阶段分配颜色。
- 生成包含统计栏、阶段筛选按钮、事件卡片等元素的可交互 HTML，输出为独立文件。
使用方式
基本命令为 /build-timeline，可接受以下参数：
- [path]：目标仓库路径，默认为当前工作目录。
- --since <date>：起始日期过滤，支持 ISO 或相对时间（如 "3 days ago"），默认为全部历史。
- --until <date>：结束日期过滤，默认为当前时间。
- --output <path>：输出文件路径，默认为 ./build-timeline.html。
- --phases：根据 git 提交模式和智能体命名自动检测阶段，默认关闭。
- --detailed：包含所有工具调用而非仅主要事件，默认关闭。
- --theme <name>：视觉主题，可选 default、dark、afs，默认 default。
执行流程依次为：确定目标仓库与参数并验证是 git 仓库；定位对话日志目录（仓库路径中 / 替换为 - 并去掉开头 -）；解析对话日志；解析 git 历史；关联事件；检测阶段；构建时间线数据结构；读取 HTML 模板并替换占位符生成 HTML；写出输出文件并向用户报告摘要统计。解析可使用 jq 或 Python，大文件建议流式逐行处理。
示例用法：
- /build-timeline：当前仓库全部历史的时间线。
- /build-timeline --since "1 day ago" --detailed：最近 24 小时的详细时间线。
- /build-timeline /Users/lgonzales/Projects/my-app --theme dark：指定仓库并使用深色主题。
- /build-timeline --since "2026-03-12" --until "2026-03-13" --output build-report.html：限定时间范围并自定义输出文件。
- /build-timeline --phases --output phased-timeline.html：启用阶段检测。
适用场景
- 回顾一次构建会话中发生的智能体派生、命令、文件变更和错误。
- 编写开发历史文档或构建过程走查。
- 展示 Claude Code 的开发工作流程。
- 在调试或需要完整记录时使用 --detailed 模式，默认模式聚焦里程碑事件。
- 大仓库建议使用 --since 限定较近的时间窗口，避免解析全部历史导致缓慢。
- 项目跨多个对话会话时，所有 .jsonl 文件会被解析并按时间合并。
限制
- 对话日志按仓库路径编码后存放在 ~/.claude/projects/ 下，若日志不存在（例如换了机器），时间线会退化为仅基于 git 的模式。
- --phases 在构建使用了约定式提交前缀或命名智能体时效果最好。
- 主题仅提供 default、dark、afs 三种。
- 其他细节（如收费、价格、平台范围等）暂未提供。