claude-replay

社区工具 — 与 Anthropic 无关联或官方认可。

AI 编码会话（coding sessions）对开发很有帮助，但难以分享。录屏文件体积庞大，而转录文本又难以导航。

claude-replay 将 Claude Code、Cursor、Codex CLI、Gemini CLI 和 OpenCode 的会话日志转换为交互式、可分享的 HTML 回放文件。生成的回放是一个独立的 HTML 文件，没有任何外部依赖 —— 您可以通过电子邮件发送它、托管在任何地方，或者嵌入到文档中。使用 --serve --watch 实时监控代理会话的运行过程。

在线试用 · 实时演示

Claude Code、Cursor、Codex CLI、Gemini CLI 和 OpenCode 会在磁盘上存储对话记录。claude-replay 自动检测格式并将其转换为适合博客文章、演示和文档的可视化回放。

来源	转录文件位置
Claude Code	~/.claude/projects/<project>/
Cursor	~/.cursor/projects/<project>/agent-transcripts/<id>/
Codex CLI	~/.codex/sessions/<date>/
Gemini CLI	~/.gemini/tmp/<projectHash>/chats/
OpenCode	通过 opencode export <sessionID> 导出

功能特性

• 独立的 HTML 输出（无依赖）
• 带速度控制的交互式回放
• 折叠/展开工具调用和思考块（Claude 的内部推理轨迹）
• 书签 / 章节
• 导出前的敏感信息隐藏
• 多种颜色主题
• 类终端的从下到上滚动
• 可通过 iframe 嵌入
• 实时监控模式 —— 实时监控代理会话 (--serve --watch)
• 基于 Web 的编辑器界面，用于可视化会话编辑和预览

使用场景

claude-replay 适用于以下场景：

• 博客文章 —— 以交互方式展示 AI 辅助开发会话
• 文档 —— 嵌入 AI 调试会话或代码讲解
• 演示 —— 分享可复现的会话，无需视频
• 错误报告 —— 附加回放文件而不是冗长的日志
• 教学 —— 逐步讲解 AI 推理和工具使用
• 实时监控 —— 在远程机器或容器中实时查看代理会话

安装

npm install -g claude-replay

或者直接使用 npx 运行（零安装）：

npx claude-replay

Docker

docker run --rm --init -p 7331:7331 \
  -v ~/.claude/projects:/root/.claude/projects:ro \
  ghcr.io/es617/claude-replay

打开 http://localhost:7331 访问 Web 编辑器。会话目录以只读方式挂载。

CLI 使用方式：

docker run --rm --init \
  -v ~/.claude/projects:/root/.claude/projects:ro \
  -v $(pwd):/output \
  ghcr.io/es617/claude-replay \
  /root/.claude/projects/my-project/session.jsonl -o /output/replay.html

快速开始

# 启动 Web 编辑器（默认）
claude-replay

# 通过会话 ID 生成回放（自动查找文件）
claude-replay abc123def456 -o replay.html

# 或者传递完整路径
claude-replay ~/.claude/projects/-Users-me-myproject/session-id.jsonl -o replay.html

# 将多个会话合并为一个回放
claude-replay session1-id session2-id -o combined.html

运行 claude-replay 不带参数时，会打开一个基于浏览器的编辑器，自动发现您的 Claude Code 和 Cursor 会话。您可以从中浏览、编辑、预览并导出可视化回放。

对于 CLI 使用，您可以仅传递会话 ID —— claude-replay 会搜索 ~/.claude/projects/、~/.cursor/projects/、~/.codex/sessions/ 和 ~/.gemini/tmp/ 找到匹配的文件。或者直接传递会话文件的完整路径。

Cursor

也支持 Cursor 转录文件 —— 格式会自动检测。Cursor 转录文件不包含时间戳，因此回放默认使用匀速计时（参见 计时模式）。

claude-replay ~/.cursor/projects/*/agent-transcripts/<id>/<id>.jsonl -o replay.html

Codex CLI

也支持 Codex CLI（OpenAI）转录文件 —— 格式会自动检测。Codex 工具调用（exec_command、apply_patch）会被映射到其 Claude Code 等效项（Bash、Edit/Write），以便以相同的差异视图和命令预览呈现。

claude-replay ~/.codex/sessions/2026/03/12/rollout-<id>.jsonl -o replay.html

Gemini CLI

也支持 Gemini CLI 转录文件 —— 格式会自动检测。Gemini 将会话存储为单个 JSON 文件（非 JSONL），其中包含内联的思考块和工具调用。工具名称会被映射到其 Claude Code 等效项（run_shell_command → Bash、read_file → Read 等），以确保一致的渲染效果。

claude-replay ~/.gemini/tmp/<projectHash>/chats/session-<id>.json -o replay.html

您也可以通过会话 ID 搜索：

claude-replay <session-id> -o replay.html  # 自动搜索 ~/.gemini/tmp/

OpenCode

也支持 OpenCode 转录文件 —— 格式会自动检测。OpenCode 将会话存储在 SQLite 数据库中，因此您需要先使用 OpenCode CLI 导出会话。思考/推理块会原生渲染。

# 从 OpenCode 导出会话，然后回放
opencode export <sessionID> > session.jsonl
claude-replay session.jsonl -o replay.html

Web 编辑器

默认体验。通过运行 claude-replay 不带参数启动：

claude-replay
claude-replay --port 8080

编辑器提供：

• 会话浏览器 —— 自动发现 ~/.claude/projects/、~/.cursor/projects/、~/.codex/sessions/ 和 ~/.gemini/tmp/ 中的会话，并提供文件夹导航以查找其他位置存储的会话文件
• 轮次编辑器 —— 包括/排除轮次，编辑用户提示，展开助手块（只读），添加书签
• 选项面板 —— 主题、速度、思考/工具调用切换、隐藏规则、标签
• 实时预览 —— 随编辑更新，渲染与 CLI 相同的输出
• 导出 —— 下载最终的 HTML 回放文件

编辑器在 127.0.0.1 上运行本地服务器（仅限本地访问，不会暴露到网络）。它不会修改原始的 JSONL 文件 —— 所有编辑都保存在内存中，仅影响导出的输出。

使用方法

claude-replay [--port N]                        启动网页编辑器（默认）
claude-replay <input> [input2...] [options]     通过命令行生成回放
claude-replay extract <replay.html> [-o output.jsonl] [--format jsonl|json]

每个 <input> 可以是会话文件路径或会话 ID。如果它不是现有的文件路径，则被视为会话 ID。claude-replay 会在 ~/.claude/projects/、~/.cursor/projects/、~/.codex/sessions/ 和 ~/.gemini/tmp/ 中搜索匹配的会话文件。您可以在 Claude Code 中运行 /status 来找到当前的会话 ID。

多个输入会被合并为一个回放（最多 20 个）。当所有会话都有时间戳时，对话将按时间顺序排序；否则使用命令行顺序。这在接收计划创建新会话时非常有用 —— 将会话链接起来以在一个回放中获取完整的故事。

命令

editor [file|session-id]

启动基于网页的回放编辑器。可以选择传递文件路径或会话 ID 以在启动时自动加载。参见上面的 Web 编辑器。

claude-replay editor                              # 空白编辑器
claude-replay editor ~/.claude/projects/.../session.jsonl  # 自动加载文件
claude-replay editor abc123                       # 按会话 ID 自动加载

extract

从先前生成的回放 HTML 文件中提取嵌入的对话数据。默认输出 JSONL 格式（每行一个对话，书签嵌入其中）。使用 --format json 获取旧版 JSON 格式。

claude-replay extract replay.html -o session.jsonl            # JSONL（默认）
claude-replay extract replay.html -o data.json --format json  # JSON

# 循环：提取后使用不同选项重新生成
claude-replay extract replay.html -o session.jsonl
claude-replay session.jsonl -o new-replay.html --theme dracula

提取的 JSONL 可以重新输入到 claude-replay 中以使用不同选项重新生成。书签作为每个对话的 bookmark 字段保留。

选项

标志	描述
-o, --output FILE	输出 HTML 文件（默认：标准输出）
--turns N-M	仅包含第 N 到第 M 个对话
--exclude-turns N,N,...	按索引排除特定对话
--from TIMESTAMP	开始时间过滤（ISO 8601 格式）
--to TIMESTAMP	结束时间过滤（ISO 8601 格式）
--speed N	初始播放速度，例如 2.0（默认：1.0）
--no-thinking	默认隐藏思考块
--no-tool-calls	默认隐藏工具调用块
--mark "N:Label"	在第 N 个对话处添加书签/章节（可重复）
--bookmarks FILE	包含书签的 JSON 文件 [{turn, label}]
--no-auto-redact	禁用自动敏感信息屏蔽
--redact "text"	将文本的所有出现替换为 [REDACTED]（可重复）
--redact "text=repl"	将文本的所有出现替换为自定义内容（可重复）
--title TEXT	页面标题（默认：从输入路径派生）
--description TEXT	链接预览的元描述（默认：Interactive AI session replay）
--og-image URL	链接预览的 OG 图片 URL（默认：托管默认值）。始终包含默认图片；如需使用自己的图片，请托管并传递 URL。
--user-label NAME	用户消息的标签（默认：User）
--assistant-label NAME	助手消息的标签（默认：自动检测）
--timing MODE	时间戳模式：auto、real、paced（默认：auto）
--theme NAME	内置主题（默认：tokyo-night）
--theme-file FILE	自定义主题 JSON 文件（覆盖 --theme）
--no-minify	使用未压缩模板（默认：如果可用则压缩）
--no-compress	嵌入原始 JSON 而非压缩数据（适用于较旧浏览器）
--open	在默认浏览器中打开生成的 HTML
--serve	在本地 HTTP 服务器上提供回放服务，而不是写入文件
--watch	监视输入文件的变化并自动重新生成
--list-themes	列出可用的内置主题并退出
--port N	编辑器/服务服务器的端口（默认：7331 编辑器，7332 服务）

示例

# 回放第 5 到第 15 个对话，速度为 2 倍
claude-replay session.jsonl --turns 5-15 --speed 2.0 -o replay.html

# 按时间范围过滤
claude-replay session.jsonl --from "2026-02-26T02:00" --to "2026-02-26T03:00" -o replay.html

# 清洁输出：无思考块，无工具调用
claude-replay session.jsonl --no-thinking --no-tool-calls -o replay.html

# 使用不同的主题
claude-replay session.jsonl --theme dracula -o replay.html

# 输出到标准输出以进行进一步处理
claude-replay session.jsonl --turns 1-5 > snippet.html

# 将多个会话链接成一个回放
claude-replay abc123 def456 ghi789 -o combined.html

# 实时预览：提供服务并在变化时自动重新加载
claude-replay session.jsonl --serve --watch

# 提供服务但不监视（一次性预览）
claude-replay session.jsonl --serve

# 监视并在变化时写入文件
claude-replay session.jsonl --watch -o replay.html

时间模式

--timing 标志控制播放速度的计算方式：

模式	行为
auto	如果有真实时间戳则使用，否则回退到 paced（默认）
real	使用转录中的原始时间戳
paced	根据内容长度生成合成时间

paced 模式创建演示风格的时间安排 —— 类似于幻灯片演示或视频字幕的时间安排。块显示速度随文本长度缩放。这是 Cursor 转录（没有时间戳）的默认设置，也可以用于 Claude Code 转录以实现更流畅的演示：

# 即使对于 Claude Code 转录也使用 paced 时间
claude-replay session.jsonl --timing paced -o demo.html

播放器控件

生成的 HTML 文件是一个完全独立的交互式播放器：

• 播放/暂停 —— 自动逐块推进对话
• 向前/向后步进 —— 在对话内逐块导航
• 进度条 —— 点击跳转到任意点；会话计时器显示经过/总时间
• 速度控制 —— 0.5x 到 5x 播放速度
• 切换复选框 —— 显示/隐藏思考块和工具调用

键盘快捷键

键	动作
Space / K	播放 / 暂停
→ / L	向前步进（块）
← / H	向后步进（块）
Shift+→ / Shift+L	跳转到下一个对话
Shift+← / Shift+H	跳转到上一个对话
T	跳转到下一个思考/工具块
Shift+T	跳转到上一个思考/工具块

主题

内置主题

claude-replay --list-themes

可用主题：tokyo-night（默认）、monokai、solarized-dark、github-light、dracula、bubbles。

自定义主题

创建一个包含 CSS 颜色值的 JSON 文件：

{
  "bg": "#0d1117",
  "bg-surface": "#161b22",
  "bg-hover": "#1c2128",
  "text": "#e6edf3",
  "text-dim": "#7d8590",
  "text-bright": "#ffffff",
  "accent": "#ff7b72",
  "accent-dim": "#c9514a",
  "green": "#3fb950",
  "blue": "#58a6ff",
  "orange": "#d29922",
  "red": "#f85149",
  "cyan": "#39d2c0",
  "border": "#30363d",
  "tool-bg": "#0d1117",
  "thinking-bg": "#0b0f14"
}

claude-replay session.jsonl --theme-file my-theme.json -o replay.html

任何缺失的键值都会从 tokyo-night 默认值中填充，因此你只需指定想要更改的颜色。

对于高级自定义，可以添加一个 extraCss 键，使用任意 CSS 规则覆盖布局、字体或其他样式：

{
  "bg": "#ffffff",
  "text": "#1c1e21",
  "extraCss": ".assistant-text { border-radius: 12px; border: 1px solid #ddd; }"
}

参见内置的 bubbles 主题，了解如何使用 extraCss 实现完全自定义布局的示例。

主题变量参考

变量	用途
bg	主背景
bg-surface	控制栏、提升表面
bg-hover	悬停状态
text	主文本
text-dim	次要文本、时间戳、标签
text-bright	用户输入、强调文本
accent	提示符号、进度条、激活状态
accent-dim	激活按钮背景
green	工具结果
blue	工具调用指示器
orange	（保留用于警告）
red	（保留用于错误）
cyan	工具名称
border	边框和分隔线
tool-bg	工具调用块背景
thinking-bg	思考块背景

嵌入

输出是一个没有外部依赖的单个 HTML 文件。可以通过 iframe 将其嵌入博客文章或文档中：

<iframe src="replay.html" width="100%" height="600" style="border: 1px solid #333; border-radius: 8px;"></iframe>

工作原理

1. 解析器 逐行读取 JSONL 转录文件，处理 Claude Code 的流式格式（单个助手消息可能以多行形式出现，内容块逐步增加）。
2. 将对话分组为：用户消息 + 助手响应（文本、工具调用、思考块）+ 工具结果。
3. 渲染器 压缩解析后的对话（deflate + base64），并将其注入 HTML 模板。
4. 播放器 是纯 JavaScript 实现 —— 不使用框架，也不发送外部请求。数据在加载时通过浏览器原生的 DecompressionStream API 解压缩。

输出优化

生成的 HTML 文件使用两层优化（零外部依赖）：

• 压缩的 CSS/JS —— 播放器模板通过 esbuild 进行压缩（混淆变量名，移除空白）。使用 --no-minify 参数可生成可读的输出。
• 压缩的数据 —— 转录 JSON 使用 deflate 压缩并 base64 编码，通常可减少输出大小约 60-70%。浏览器在加载时通过 DecompressionStream 原生解压缩（支持 Chrome 80+、Firefox 113+、Safari 16.4+）。对于旧版浏览器，使用 --no-compress 参数嵌入原始 JSON。

开发

编辑 template/player.html 后重新构建压缩模板：

npm install    # 安装 esbuild（开发依赖）
npm run build  # 生成 template/player.min.html

压缩模板在 CI 中构建，并包含在 npm 发布版本中。如果没有压缩模板，CLI 会自动回退到未压缩模板。

敏感信息屏蔽

默认情况下，claude-replay 会在所有嵌入文本中扫描常见的敏感信息模式，并在写入输出 HTML 之前 将其替换为 [REDACTED]。这意味着你的会话中的敏感信息（API 密钥、令牌、连接字符串等）不会出现在生成的文件中。

检测到的模式包括：

• API 密钥 (sk-..., sk-ant-..., key-...)
• AWS 访问密钥 ID (AKIA...)
• Bearer 和 JWT 令牌
• 数据库连接字符串 (postgres://..., mongodb://... 等)
• 私钥块 (-----BEGIN ... PRIVATE KEY-----)
• 通用键值对秘密 (api_key=..., auth_token: ...)
• 环境变量秘密 (PASSWORD=..., TOKEN=...)
• 长十六进制令牌（40+ 字符）

重要提示： 基于模式的屏蔽是一种尽力而为的安全网 —— 无法捕获每一种可能的秘密格式。始终在公开分享前检查生成的 HTML。

禁用屏蔽（例如用于内部/私有回放）：

claude-replay session.jsonl --no-auto-redact -o replay.html

支持的转录格式

Claude Code

每行一个 JSON 对象，包含 type 字段（user, assistant, system, progress 等）。包括时间戳、思考块和工具调用及结果。

Cursor

每行一个 JSON 对象，包含顶级 role 字段。无时间戳。思考以内联文本形式显示。格式自动检测 —— 无需标志。

Codex CLI

基于事件的 JSONL，包含类型化事件（session_meta, response_item, event_msg 等）。包括时间戳。工具调用（exec_command, apply_patch）映射为 Claude Code 等效项以实现一致渲染。Codex 的加密推理块被跳过；注释消息显示为思考块。格式自动检测 —— 无需标志。

Gemini CLI

单个 JSON 文件，包含 sessionId 字段和 messages 数组，数组中包含 user 和 gemini 类型的条目。包括时间戳、内联思考块（thoughts）和工具调用及嵌套结果。工具名称（run_shell_command, read_file, edit_file 等）映射为 Claude Code 等效项以实现一致渲染。格式自动检测 —— 无需标志。

要求

• Node.js 18+
• 零运行时依赖（esbuild 仅为开发依赖，用于构建压缩模板）

隐私

回放文件嵌入了 完整会话转录，包括源代码、文件路径、工具输入/输出和思考痕迹。在公开分享前请检查生成的 HTML —— 它可能包含专有代码、内部路径或其他敏感信息。默认启用的敏感信息屏蔽功能会捕获常见的凭据模式，但不会过滤代码或文件内容。

转录数据存储为 HTML 文件中的压缩 blob。编辑播放器 JavaScript 以隐藏或过滤对话仅影响渲染 —— 原始数据仍保留在 blob 中并可恢复。要排除敏感内容，请在生成时使用 CLI 标志（例如 --turns, --exclude-turns）。使用 --redact 在生成时删除特定字符串（用户名、路径、项目名称）。始终在公开分享前检查生成的回放。

许可证

MIT

快速上手指南：claude-replay

claude-replay 是一个社区工具，用于将 Claude Code、Cursor、Codex CLI、Gemini CLI 和 OpenCode 的会话日志转换为交互式、可分享的 HTML 回放文件。以下是快速上手指南。

---

环境准备

系统要求

• Node.js: 18 或更高版本（推荐使用 LTS 版本）
• 操作系统: 支持 macOS、Linux 和 Windows（WSL2 推荐）
• 依赖项: 无外部依赖（零依赖）

前置依赖

确保已安装 Node.js。如果未安装，可以通过以下方式安装：

# 使用 nvm 安装 Node.js（推荐）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.5/install.sh | bash
nvm install --lts

国内用户可以使用淘宝镜像加速：

npm config set registry https://registry.npmmirror.com

---

安装步骤

全局安装

通过 npm 全局安装 claude-replay：

npm install -g claude-replay

零安装运行

如果不希望全局安装，可以直接使用 npx 运行：

npx claude-replay

Docker 安装（可选）

如果需要使用 Docker，可以拉取官方镜像：

docker run --rm --init -p 7331:7331 \
  -v ~/.claude/projects:/root/.claude/projects:ro \
  ghcr.io/es617/claude-replay

启动后访问 http://localhost:7331 即可使用 Web 编辑器。

---

基本使用

启动 Web 编辑器

运行以下命令启动默认的 Web 编辑器：

claude-replay

编辑器会自动扫描 ~/.claude/projects/、~/.cursor/projects/ 等目录中的会话文件，支持可视化浏览、编辑和导出。

生成单个回放文件

通过会话 ID 或文件路径生成 HTML 回放文件：

# 按会话 ID 自动生成
claude-replay abc123def456 -o replay.html

# 指定完整路径
claude-replay ~/.claude/projects/-Users-me-myproject/session-id.jsonl -o replay.html

合并多个会话

将多个会话合并为一个回放文件：

claude-replay session1-id session2-id -o combined.html

实时监控会话

使用 --serve --watch 实时监控会话运行：

claude-replay session.jsonl --serve --watch

自定义主题和速度

生成回放时可以指定主题和播放速度：

claude-replay session.jsonl --theme dracula --speed 2.0 -o replay.html

---

以上是 claude-replay 的快速上手指南，更多高级功能请参考官方文档或 README 文件。