Claude 代码日志

一个 Python 命令行工具，可将 Claude 代码转录 JSONL 文件转换为可读的 HTML 和 Markdown 格式。

浏览器日志演示：

浏览器日志

TUI 演示：

TUI

项目概述

📋 查看变更日志 - 了解每次发布的新内容

该工具会生成简洁、极简风格的 HTML 页面，按时间顺序展示用户提示和助手回复。它旨在创建可读性高的 Claude 代码交互日志，支持处理单个文件以及整个项目目录结构。

📄 查看 HTML 示例输出 - 下载由本项目开发过程中生成的真实示例（文件较大，约 100 MB）

快速入门

TL;DR：运行以下命令，即可浏览从您的整个 Claude 代码存档中生成的页面：

uvx claude-code-log@latest --open-browser

主要特性

• 交互式 TUI（终端用户界面）：实时导航、摘要及快速导出 HTML 和恢复会话等功能，方便浏览和管理 Claude 代码会话
• 项目目录结构处理：可处理整个 ~/.claude/projects/ 目录，并生成关联的索引页
• 单个会话文件：为每个会话生成独立的 HTML 文件，并提供导航链接
• 单个文件或目录处理：可转换单个 JSONL 文件或指定目录
• 会话导航：交互式目录，包含会话摘要和快速跳转功能
• Token 使用跟踪：显示单条消息及会话总 token 消耗量
• 运行时消息过滤：基于 JavaScript 的过滤功能，可显示或隐藏不同类型的消息（用户、助手、系统、工具使用等）
• 按时间顺序排列：所有会话中的消息均按时间戳排序
• 交互式时间轴：根据消息时间生成可缩放的交互式时间轴，便于直观地浏览对话
• 跨会话摘要匹配：正确将异步生成的摘要与其原始会话关联
• 日期范围过滤：可通过自然语言（如“今天”、“昨天”、“上周”）按日期范围筛选消息
• 丰富消息类型：支持用户/助手消息、工具使用/结果、思考内容、图片等多种消息类型
• 系统命令可见性：以可展开详情的形式显示系统命令（如 init），并进行结构化解析
• Markdown 渲染：服务端使用 mistune 进行 Markdown 渲染，并支持语法高亮
• 浮动导航：始终可用的返回顶部按钮和过滤控件
• CLI 界面：基于 Click 的简单命令行工具

解决了哪些问题？

该工具可以帮助您回答以下问题：

• “如何回顾我所有的 Claude 代码对话？”
• “我昨天/上周与 Claude 一起做了什么？”
• “我的 Claude 代码会话花费了多少？”
• “如何搜索我的整个 Claude 代码历史记录？”
• “Claude 在这个项目中使用了哪些工具？”
• “如何与他人分享我的 Claude 代码对话？”
• “我的项目开发时间线是怎样的？”
• “如何分析我的 Claude 代码使用模式？”

使用方法

交互式 TUI（终端用户界面）

TUI 提供了一个交互式界面，用于浏览和管理 Claude 代码会话，具备实时导航、会话摘要和快速操作功能。

# 启动所有项目的 TUI（默认行为）
claude-code-log --tui

# 启动特定项目目录的 TUI
claude-code-log /path/to/project --tui

# 启动特定 Claude 项目的 TUI
claude-code-log my-project --tui  # 自动转换为 ~/.claude/projects/-path-to-my-project

TUI 功能：

• 会话列表：交互式表格，显示会话 ID、摘要、时间戳、消息数量和 token 使用情况
• 智能摘要：优先显示 Claude 生成的摘要，而非第一条用户消息，以便更好地识别会话
• 工作目录匹配：自动查找并打开与当前工作目录匹配的项目
• 快速操作：
  • h：在浏览器中生成并打开会话 HTML
  • m：在浏览器中生成并打开会话 Markdown
  • v：在嵌入式查看器中查看会话 Markdown（含目录）
  • c：使用 claude -r <sessionId> 在 Claude 代码中恢复会话
  • r：从文件中重新加载会话数据
  • p：切换到项目选择视图
  • H/M/V：强制重新生成 HTML/Markdown（开发用隐藏快捷键）
• 项目统计信息：实时显示总会话数、消息数、token 数量以及日期范围
• 缓存集成：利用现有缓存系统实现快速加载，并自动验证缓存有效性
• 键盘导航：使用方向键导航，按 Enter 键展开行详情，按 q 键退出
• 行展开：按下 Enter 键可展开选中行，显示完整摘要、第一条用户消息、工作目录以及详细的 token 使用情况

默认行为（处理所有项目）

# 处理 ~/.claude/projects/ 中的所有项目（默认行为）
claude-code-log

# 显式处理所有项目
claude-code-log --all-projects

# 处理所有项目并在浏览器中打开
claude-code-log --open-browser

# 按日期范围处理所有项目
claude-code-log --from-date "yesterday" --to-date "today"
claude-code-log --from-date "last week"

# 跳过单个会话文件（仅创建合并转录）
claude-code-log --no-individual-sessions

这将生成：

• ~/.claude/projects/index.html - 包含项目卡片和统计信息的顶级索引页
• ~/.claude/projects/project-name/combined_transcripts.html - 各个项目的单独页面（这些页面可能达到数 MB）
• ~/.claude/projects/project-name/session-{session-id}.html - 单个会话页面
• ~/.claude/projects/project-name/session-{session-id}.md - Markdown 版本（通过 TUI 按需生成）

单个文件或目录处理

# 单个文件
claude-code-log transcript.jsonl

# 特定目录
claude-code-log /path/to/transcript/directory

# 自定义输出位置
claude-code-log /path/to/directory -o combined_transcripts.html

# 转换后在浏览器中打开
claude-code-log /path/to/directory --open-browser

# 按日期范围过滤（支持自然语言）
claude-code-log /path/to/directory --from-date "yesterday" --to-date "today"
claude-code-log /path/to/directory --from-date "3 days ago" --to-date "yesterday"

项目层级输出

在处理所有项目时，该工具会生成：

~/.claude/projects/
├── index.html                           # 主索引页，包含项目卡片
├── project1/
│   ├── combined_transcripts.html        # 合并后的项目页面
│   ├── session-{session-id}.html        # 单个会话页面
│   ├── session-{session-id}.md          # Markdown 格式版本（可通过 TUI 按需生成）
│   └── session-{session-id2}.html       # 更多会话页面...
├── project2/
│   ├── combined_transcripts.html
│   └── session-{session-id}.html
└── ...

索引页功能

• 项目卡片：每个项目以可点击卡片形式展示，并附带统计信息。
• 会话导航：可展开的会话列表，包含摘要和快速访问单个会话文件的链接。
• 汇总统计：总项目数、转录文件数以及消息数量，并显示 token 使用情况。
• 近期活动：按最后修改日期排序的项目列表。
• 快速导航：一键访问合并后的转录或单个会话。
• 清晰 URL：将目录名转换为易读的项目名称。

支持的消息类型

• 用户消息：常规用户输入和提示。
• 助手消息：Claude 的回复，并显示 token 使用情况。
• 总结消息：会话总结，支持跨会话匹配。
• 系统命令：如 init 等命令，以可展开详情的形式呈现，并进行结构化解析。
• 工具使用：工具调用记录，附带可折叠详情及特殊的 TodoWrite 渲染。
• 工具结果：工具执行结果，包含错误处理。
• 思考内容：Claude 的内部推理过程。
• 图片：粘贴的图片和截图。

HTML 输出特性

• 响应式设计：适用于桌面端和移动端。
• 运行时消息过滤：通过 JavaScript 控制显示/隐藏不同类型的消息，并实时更新计数。
• 会话导航：交互式目录，包含会话摘要和时间戳范围。
• Token 使用显示：跟踪单条消息及会话级别的 token 消耗。
• 语法高亮：代码块经过正确格式化，并支持 Markdown 渲染。
• Markdown 支持：服务器端渲染，使用 mistune 库，支持：
  • 标题、列表、强调、删除线。
  • 代码块和内联代码。
  • 链接、图片和表格。
  • GitHub Flavored Markdown 特性。
• 可折叠内容：工具使用、系统命令及长内容以可展开部分呈现。
• 悬浮控件：始终可见的筛选按钮、详情切换按钮以及返回顶部导航。
• 跨会话功能：总结内容可在异步会话之间正确匹配。

Markdown 输出特性

Markdown 导出提供了一种轻量级、便携的 HTML 替代方案：

• GitHub-Flavored Markdown：兼容 GitHub、GitLab 等 Markdown 渲染器。
• 层次化结构：会话按标题组织，并附带可折叠详情。
• 消息摘要：章节标题包含消息预览，便于快速导航。
• 代码保留：通过 fenced code blocks 提供语法高亮提示。
• 嵌入式查看器：TUI 内置 Markdown 查看器，带有目录。
• 图片支持：可配置图片处理方式（占位符、内嵌 base64 或引用文件）。

安装

使用 pip 安装：

pip install claude-code-log

或直接使用 uvx 运行（无需单独安装步骤）：

uvx claude-code-log@latest

或从源码安装：

git clone https://github.com/daaain/claude-code-log.git
cd claude-code-log
uv sync
uv run claude-code-log

贡献

请参阅 CONTRIBUTING.md，了解开发环境搭建、测试及架构文档。

待办事项

• 添加教程叠加层。
• 如果存在，集成 claude-trace 请求日志。
• 将图片转换为 WebP 格式，因为截图通常是巨大的 PNG 文件——这可能需要频繁重复操作（因此也需要缓存机制），并且依赖复杂的编译库（除非有高效的纯 Python 图像处理库？或者 WASM？）。
• 为内置工具添加特殊格式：Glob、Grep、LS、MultiEdit、NotebookRead、NotebookEdit、WebFetch、TodoRead、WebSearch。
• 添加类似每日摘要的 ccusage 功能，或许还可以基于 Claude 生成的会话摘要，提供一些文本总结？
• 从 @claude Github Actions 导入日志。
• 从 @claude Github Actions 流式获取日志，参考 octotail。
• 将 CLI 封装为 Github Action，在 Cladue Github Action 执行后运行，并处理其 输出。
• 将过滤后的用户消息输入到无头 Claude CLI 中，以提炼会话中的用户意图。
• 在 Python（CLI）端也进行消息类型过滤，而不仅仅是 UI 层面。
• 添加极简主题，并实现浅色与深色模式；在炫酷主题中添加渐变背景动画。
• 是否需要对钩子进行特殊处理？
• 实现并行处理，目前仅使用一个 CPU 核心，速度较慢。
• 合并 Git 工作树目录。

claude-code-log 快速上手指南

claude-code-log 是一个 Python CLI 工具，可将 Claude Code 的对话记录（JSONL 格式）转换为易读的 HTML 和 Markdown 格式，支持交互式终端界面（TUI）、时间线浏览、Token 统计及消息过滤。

环境准备

• 操作系统：Linux / macOS / Windows
• Python 版本：建议 Python 3.8+
• 前置依赖：
  • 已安装 pip 或 uv（推荐）
  • 已配置 Claude Code 并生成过对话记录（默认位于 ~/.claude/projects/）

💡 国内用户可使用清华或阿里云镜像加速 Python 包安装：

pip install -i https://pypi.tuna.tsinghua.edu.cn/simple claude-code-log

安装步骤

方式一：使用 uvx（无需预先安装，推荐）

uvx claude-code-log@latest

方式二：使用 pip 安装

pip install claude-code-log

方式三：从源码安装

git clone https://github.com/daaain/claude-code-log.git
cd claude-code-log
uv sync
uv run claude-code-log

基本使用

1. 一键生成所有项目日志并打开浏览器

uvx claude-code-log@latest --open-browser

该命令会自动处理 ~/.claude/projects/ 下所有项目，生成索引页和各会话 HTML 文件，并在浏览器中打开主页面。

2. 启动交互式终端界面（TUI）

claude-code-log --tui

在终端中浏览会话列表、查看摘要、快速导出 HTML/Markdown 或恢复会话。支持键盘导航（方向键、Enter、q 退出等）。

3. 处理单个文件或指定目录

# 转换单个 JSONL 文件
claude-code-log transcript.jsonl

# 转换指定目录下的所有会话
claude-code-log /path/to/transcript/directory --open-browser

# 按日期范围过滤（支持自然语言）
claude-code-log ~/.claude/projects/my-project --from-date "yesterday" --to-date "today"

4. 输出结构说明

执行后将在 ~/.claude/projects/ 生成如下结构：

~/.claude/projects/
├── index.html                          # 总索引页（含项目卡片与统计）
├── project-name/
│   ├── combined_transcripts.html       # 项目合并日志
│   └── session-{id}.html               # 单个会话页面

生成的 HTML 支持消息类型过滤、Token 统计、代码高亮、折叠详情及响应式布局，适合回顾、分享或分析对话历史。