claude-replay

Claude Replay

Claude Code 会话的可观测性层——跨项目搜索、分析和可视化。

---

Claude Code 的 --resume/--continue 和 /rewind 可以恢复当前所在的会话。Claude Replay 则补足了它们做不到的部分：它会被动接入每个会话，将发生的情况记录到本地 SQLite 存储中，并让所有项目中的每个历史会话都可搜索、比较、衡量和导出。它提供全文搜索、单个会话的洞察指标、结束原因分类（会话为何结束）、会话差异对比、Web 仪表板和终端 UI——这些都不是 Claude Code 原生具备的功能。

Claude Code session
        |
   hooks (PreToolUse · PostToolUse · Stop)
        |
        v
   ~/.claude-replay/sessions.db   ← events + checkpoints
        |
   +----+--------------------+
   |          |              |
 MCP tools  Dashboard      TUI
 (resume)   :8766          (browse)

被动钩子负责写入。MCP 工具、Web 仪表板和终端 UI 负责读取。任何数据都不会离开你的设备。

---

如何与 Claude Code 原生功能互补

Claude Replay 是增强功能——它叠加在内置功能之上，而不是取而代之。

你想要……	使用
恢复 / 继续当前会话	原生功能 claude --continue、--resume
撤销会话中的文件和对话变更	原生功能 /rewind
按内容、工具或结果搜索所有历史会话	Replay search
查看会话为何结束及单个会话的指标	Replay status / replay_insights
并排比较两次运行	Replay diff
可视化会话时间线 / 浏览所有项目	Replay 仪表板 + TUI
将会话导出为 HTML / JSON / Markdown	Replay export --format

可以将原生的恢复/回退视为恢复功能，将 Replay 视为对完整历史记录的可观测性。

---

架构

被动钩子将数据写入 SQLite。MCP 工具从 SQLite 读取数据。仪表板 + TUI 对 SQLite 中的数据进行可视化。整个系统就是如此。

层	文件	作用
存储	claude_replay/store.py	所有数据库访问——会话、事件、检查点
钩子	claude_replay/hooks.py	记录工具调用 + 自动创建检查点，由 claude-replay hook <type> 调度
恢复	claude_replay/resume.py	根据会话生成恢复摘要
导出	claude_replay/export.py	将会话渲染为独立的 HTML 跟踪记录
服务端	claude_replay/server.py	Starlette 应用——MCP SSE + JSON API + 静态仪表板
TUI	claude_replay/tui.py + tui_client.py	通过 JSON API 浏览会话的 Textual 界面
CLI	claude_replay/cli.py	所有子命令

端口 8766 刻意比 Claude Bridge 的 8765 高一个端口，这样这两个同类服务就能并行运行而不会冲突。

---

快速开始

1. 安装

pip install claude-replay

或者从克隆的仓库安装，方便进行开发：

git clone https://github.com/constripacity/Claude-Replay.git
cd Claude-Replay
pip install -e .[dev]              # editable install with test/lint deps
pip install -e .[tui]             # add the terminal UI deps (textual, httpx)

如果 pip install -e 在你的环境中安装失败（某些环境中已知的 hatchling 可编辑安装问题），请直接安装依赖： pip install mcp starlette uvicorn anyio textual httpx。

2. 安装钩子

此操作会将三个钩子合并到 ~/.claude/settings.json，从而将 Replay 接入 Claude Code。此操作可重复执行，不会影响其他工具的钩子。

claude-replay install

✓ Installed Claude Replay hooks into ~/.claude/settings.json
  PreToolUse  → claude-replay hook pre-tool
  PostToolUse → claude-replay hook post-tool
  Stop        → claude-replay hook stop

从现在起，每个 Claude Code 会话都会自动记录。随时可以使用 claude-replay uninstall 移除钩子（它只会移除 Replay 的钩子）。

确认钩子确实已接入——这才是关键的检查：

claude-replay doctor

Claude Replay — doctor

  ✓ Hooks installed: PreToolUse / PostToolUse / Stop are in settings.json
  ✓ Hook command on PATH: claude-replay → …/claude-replay
  ✓ Database: ~/.claude-replay/sessions.db
  ✓ Sessions recorded: 3 sessions; most recent 5m ago

All good — Replay is installed and recording. ✓

如果 doctor 警告 claude-replay 不在 PATH 中，钩子就无法运行，也不会记录任何内容——请将安装目录添加到 PATH，然后重新运行检查。

3. 启动服务（仪表板 + MCP 工具）

claude-replay serve                 # defaults: 127.0.0.1:8766
claude-replay serve --port 9000     # custom port
claude-replay serve --host 0.0.0.0  # bind all interfaces

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Claude Replay — Session checkpoint & recovery server
  Version: 0.4.1
  DB: ~/.claude-replay/sessions.db
  http://localhost:8766/             ← Dashboard
  http://localhost:8766/sse          ← MCP config
  http://localhost:8766/api/state    ← JSON state
  http://localhost:8766/status       ← Health check
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

4.（可选）向 Claude Code 注册 MCP 工具

这样，正在运行的 Claude Code 会话就可以直接调用 replay_resume、replay_checkpoint 等工具。有两种方式：

SSE（与仪表板一起运行——需要运行 claude-replay serve）：

claude mcp add --transport sse -s user claude-replay http://localhost:8766/sse

stdio（无需服务进程——客户端会按需启动 Replay）：

claude mcp add -s user claude-replay -- claude-replay mcp
# or, without installing: uvx claude-replay mcp

使用 claude mcp list 验证：claude-replay 应显示 ✓ Connected。在已经运行的会话中，输入 /mcp 重新握手。

---

会话意外结束时

# What's the state of the last session?
claude-replay status

# Print a paste-ready resume brief (most recent session, or pass an id)
claude-replay resume
claude-replay resume <session-id>

# Browse every recorded session in the terminal
claude-replay tui                   # needs `claude-replay serve` running

# Export a session as a self-contained HTML trace
claude-replay export                # → ~/.claude-replay/exports/<id>.html

将 resume 的输出粘贴到新的 Claude Code 会话中，它就能从意外结束的会话停下的地方继续——包括目标、已完成的工作、接下来的任务，以及涉及的文件。

---

MCP 工具

每个已连接的 Claude Code 会话都会获得以下十种工具：

工具	描述
replay_status	当前会话摘要——目标、状态、结束原因、事件/检查点数量、最近活动
replay_checkpoint	立即为当前会话创建检查点，并可附加备注
replay_resume	为会话生成结构化恢复摘要（默认：最近的会话）
replay_sessions	列出最近的会话，包含状态、模型、时长、检查点数量
replay_insights	单会话指标：结束原因、时长、工具调用次数、错误率、涉及的文件、常用工具
replay_stats	跨会话分析：工具调用次数、错误率、会话结束原因、工具使用情况、按项目汇总
replay_search	跨会话全文搜索，支持筛选条件（工具、原因、日期、项目），并按匹配次数排序
replay_diff	比较两个会话：指标差异，以及各自涉及的文件
replay_tag	为会话命名并添加/移除标签，以便之后检索
replay_export	将会话渲染为独立的跟踪记录（html / json / md），并返回路径

---

CLI 参考

命令	功能
claude-replay install	将 Replay 的钩子合并到 ~/.claude/settings.json 中（可重复执行）
claude-replay uninstall	仅移除 Replay 的钩子
claude-replay status	快速查看当前/最近的会话及其洞察指标
claude-replay sessions [--limit N]	列出最近的会话（包含名称和标签）
claude-replay search <query> [--tool T] [--cause C] [--since 7d] [--project P]	使用筛选条件进行全文搜索（省略 query 可按筛选条件浏览）
claude-replay diff <session-a> <session-b>	并排比较两个会话
claude-replay resume [session_id]	输出恢复摘要（默认：最近的会话）
claude-replay export [session_id] [--output DIR] [--format html|json|md]	渲染跟踪记录
claude-replay tag [session_id] [--name N] [--add a,b] [--remove c] [--clear]	为会话命名或添加标签
claude-replay prune [--older-than 30d] [--yes]	删除近期没有活动的会话（具有破坏性）
claude-replay serve [--host H] [--port P]	启动 MCP + 仪表板服务（端口 8766）
claude-replay mcp	通过 stdio 提供 MCP 工具（用于 uvx claude-replay mcp / MCP 客户端）
claude-replay tui [--url URL]	启动终端会话浏览器
claude-replay reset [--yes]	删除所有记录的会话（具有破坏性）
claude-replay hook <pre-tool|post-tool|stop>	内部命令——由 Claude Code 的钩子调用

---

仪表板与 TUI

Web 仪表板（运行 claude-replay serve，然后打开 http://localhost:8766/）：一个原生 JavaScript 视图，每 2 秒轮询一次，包含会话列表（带结束方式徽标和标签）、实时搜索框、每个会话的时间线，以及一键式“复制恢复摘要”/“导出 HTML”。无需 CDN，也无需构建步骤。

终端 UI（claude-replay tui）：采用相同深色主题的 Textual 浏览器。包含会话侧边栏、实时事件流，以及显示会话结束方式、标签、最新检查点和已修改文件的详情检查器。按键：

↑↓ navigate   Tab switch panel   Space pause
r  resume (copies the brief to your clipboard)
e  export HTML trace
?  help        q quit

TUI 通过 HTTP 与服务通信。请先启动 claude-replay serve（默认使用 http://127.0.0.1:8766；使用 --url 指定其他地址）。

---

配置

环境变量	默认值	用途
CLAUDE_REPLAY_DB	~/.claude-replay/sessions.db	SQLite 存储位置
CLAUDE_SESSION_ID / CLAUDE_CODE_SESSION_ID	—	会话标识（Claude Code 会在钩子负载中设置此值）；若未设置，则依次回退到这些环境变量的值，再回退到项目目录的哈希值
CLAUDE_REPLAY_CORS_ORIGIN	仅限 localhost	为服务添加以逗号分隔的额外 CORS 来源
CLAUDE_REPLAY_NO_DASHBOARD	—	设置后禁用静态仪表板挂载（仅 MCP/JSON）

按照设计，钩子路径优先离线运行：不会进行任何网络调用，并能在远低于 50 ms 的时间内完成，只需执行一次 SQLite 写入。每个事件的大型工具负载会截断至 8 KB，以保持数据库精简。

---

开发

pip install -e .[dev]               # or install deps directly (see install note)
python -m pytest                    # full suite
ruff check .

测试使用隔离的 tmp_path SQLite 数据库（fresh_db 固件），绝不会触及你实际的 ~/.claude-replay/sessions.db。有关范围和编码规则，请参阅 CONTRIBUTING.md。

---

许可证

MIT，参见 LICENSE。

与 Claude Bridge 同属一个系列。由 Constripacity 旗下团队打造。