我开源了一个Claude Code历史可视化工具：本地Prompt一键浏览、搜索、导出

文章目录

1、前言
2、快速上手
- [2.1 方式一：直接下载安装包（最快）](#2.1 方式一：直接下载安装包（最快）)
- [2.2 方式二：源码运行（任意平台 / 想改代码）](#2.2 方式二：源码运行（任意平台 / 想改代码）)
- [2.3 配置数据源（可选）](#2.3 配置数据源（可选）)
[3、背景：Claude Code 的历史数据藏在哪](#3、背景：Claude Code 的历史数据藏在哪)
- [3.1 三处数据源](#3.1 三处数据源)
- [3.2 数据在，但没有入口](#3.2 数据在，但没有入口)
4、功能详解
- [4.1 以文件夹为维度浏览 Prompt](#4.1 以文件夹为维度浏览 Prompt)
- [4.2 全局 / 文件夹内模糊搜索](#4.2 全局 / 文件夹内模糊搜索)
- [4.3 统计概览](#4.3 统计概览)
- [4.4 对话详情](#4.4 对话详情)
- [4.5 按日期范围导出 Prompt（v0.2.0 新增）](#4.5 按日期范围导出 Prompt（v0.2.0 新增）)
5、技术实现
- [5.1 整体架构：为什么是 Tauri](#5.1 整体架构：为什么是 Tauri)
- [5.2 数据解析与合并去重](#5.2 数据解析与合并去重)
- [5.3 索引与磁盘缓存](#5.3 索引与磁盘缓存)
- [5.4 搜索的实现](#5.4 搜索的实现)
- [5.5 导出：一个好索引带来的红利](#5.5 导出：一个好索引带来的红利)
- [5.6 技术选型小结](#5.6 技术选型小结)
6、总结

🍃作者介绍：AI 应用负责人/AI产品架构师，阿里云专家博主。专注 LLM 应用开发、Agent 系统设计、具身智能与工业 AI 落地。日常在大模型训练、Coding Agent 工具链、AI 产品商业化等方向持续输出实战内容。

🦅个人主页：@逐梦苍穹

🐼GitHub主页：https://github.com/XZL-CODE

✈ 您的一键三连，是我创作的最大动力🌹

1、前言

用 Claude Code 久了，你大概率会遇到这么一个尴尬时刻：

某天你想找回几周前的一段 Prompt------可能是当时让它重构某个模块的需求描述，可能是某个排查思路------但翻遍终端历史也找不到。它明明发生过，却像没存档一样消失了。

实际上它并没有消失 。Claude Code 把你敲过的每一条 Prompt、每一次完整对话，都老老实实写进了本地的 ~/.claude/ 目录。问题只是：这些数据是一堆 JSONL 文件，散落在上百个以"编码路径"命名的目录里，肉眼根本没法浏览，更别说检索。

而且这还不只是"找回某一条"的问题。有时候你想要的是一整段------把最近两周发给 Claude Code 的所有 Prompt 整理出来，做个复盘、写进周报，或者干脆喂回给大模型，让它帮你总结"这段时间我到底在折腾什么"。可原始 JSONL 既导不出、也没法按时间筛。

所以我写了一个小工具------CC History Viewer ：扫描本地 ~/.claude/，把你在 Claude Code 里交互过的所有 Prompt 按文件夹聚合起来，支持模糊搜索、统计概览，能展开查看完整对话，还能按日期范围把 Prompt 一键导出成 Markdown。纯本地、只读、不联网。

它已经在 GitHub 开源（MIT 协议）：

🔗 仓库地址：https://github.com/XZL-CODE/cc-history-viewer

这篇文章会带你先把它跑起来，再讲清楚它解决什么问题、有哪些功能，以及------重点------它是怎么实现的。

2、快速上手

按"先用起来，再深入理解"的顺序，我们先让它在你机器上跑起来。有两种方式，挑顺手的。

2.1 方式一：直接下载安装包（最快）

如果你用的是 Apple Silicon（M 系列）Mac ，不想折腾环境，直接去 Releases 页下载打包好的 .dmg：

📦 下载地址：https://github.com/XZL-CODE/cc-history-viewer/releases/latest

打开 dmg、把 App 拖进「应用程序」即可。

⚠️ 应用没有 Apple 开发者签名，首次打开可能被 Gatekeeper 拦下（提示"无法验证开发者"）。两种绕过方式任选其一：右键点 App →「打开」，或在终端执行 xattr -cr "/Applications/CC History Viewer.app"。这是个人开源工具的常态，介意的话就走下面的源码方式。

2.2 方式二：源码运行（任意平台 / 想改代码）

它是一个 Tauri 桌面应用，从源码跑需要：

Node.js ≥ 18、pnpm ≥ 8------前端构建
Rust 工具链 ------Tauri 的后端是 Rust 写的（没装的话，仓库里附了一份《Rust 工具链安装指南》，跟着 rustup 装一遍即可）

bash 复制代码

git clone https://github.com/XZL-CODE/cc-history-viewer.git
cd cc-history-viewer
pnpm install
pnpm tauri dev

第一次 pnpm tauri dev 会把 Rust 依赖整个编译一遍，耗时几分钟，属于正常现象；编译完成后会自动弹出应用窗口。之后再启动就是秒级的增量编译了。

2.3 配置数据源（可选）

应用默认读取 ~/.claude。如果你的 Claude Code 数据在别的位置，把仓库里的 settings.example.json 复制成 settings.json，填入 claudeDataDir 即可；全部留空就是默认路径。改完在应用里点一下刷新按钮就生效，不用重新编译。

跑起来之后，你应该能立刻看到自己积累的全部 Prompt 历史。我自己这台机器上是 5900 多条 Prompt、横跨 330 多个项目目录、1000 多个会话、近 7.7 万条消息，时间从 2025 年 9 月底一路到现在------这些数据以前是完全"看不见"的。

3、背景：Claude Code 的历史数据藏在哪

要理解这个工具，得先知道 Claude Code 在本地到底存了什么。

3.1 三处数据源

Claude Code 的历史数据分散在 ~/.claude/ 下的三个地方：

history.jsonl------你在输入框里敲下的每一条 Prompt，一行一条 JSON，带时间戳和当时的工作目录；
projects/<编码路径>/*.jsonl------每个会话一个文件，记录完整对话流：用户消息、AI 回复、工具调用、git 分支等；
sessions/*.json------会话元数据：进程、启动时间、Claude Code 版本、状态。

3.2 数据在，但没有入口

这套设计对 Claude Code 自己运行没问题，但对"人想回看历史"非常不友好：

projects/ 下的目录名，是把真实路径里的 / 替换成 - 编码出来的，中文路径还会被编码成一长串看不懂的 -，你根本认不出哪个目录对应哪个项目；
几百上千个 JSONL 文件、几百 MB 体量，没有任何检索手段；
history.jsonl 是一本流水账，既没按项目聚合，也没有搜索，更没法按时间段导出。

一句话：数据是你的，但你用不上。CC History Viewer 要做的，就是给这堆数据补一个"浏览器"和一个"导出口"。

4、功能详解

整个应用就三块：顶部常驻搜索栏、左侧文件夹导航、右侧主内容区。

4.1 以文件夹为维度浏览 Prompt

"你在某个项目里都让 Claude Code 干过什么"------这是最自然的回看视角。所以应用以**文件夹（项目）**为一级导航：左侧列出所有交互过的目录，点进去就是该目录下逐条排列的 Prompt，每条带相对时间、来源标签、字数、关联会话。

4.2 全局 / 文件夹内模糊搜索

搜索是这个工具的核心交互，搜索栏常驻顶部，两种范围一键切换：

全局搜索：在所有文件夹的 Prompt 里找；
当前文件夹：进入某个项目后，只在这个项目范围内找。

匹配策略是子串匹配 + 不区分大小写 + 空格分词（多个关键词之间是 AND 关系），命中的关键词在结果里高亮。

4.3 统计概览

首页是一块统计面板：Prompt 总数、文件夹数、会话数、每日活跃度曲线、24 小时分布、最活跃项目 Top 榜、用过的 Claude Code 版本......算是给自己的使用习惯做一次体检。

4.4 对话详情

Prompt 列表里每条都能跳转到它所属的完整会话，以聊天气泡的形式展示用户消息和 AI 回复；工具调用、思考过程默认折叠，需要时再展开。

4.5 按日期范围导出 Prompt（v0.2.0 新增）

这是最新加的一块，也是开头说的那个"找回一整段"的痛点解法。

侧边栏新增一个「导出 Prompt」页：选一个日期范围（内置 近 7 天 / 近 30 天 / 本月 / 全部 预设），把这段时间里你发给 Claude Code 的每一条 Prompt ，导出成一份完整的 Markdown 文件 ，一键存到 ~/Downloads。

几个能调的选项：

组织方式：按文件夹分组（默认）/ 按天 / 纯时间线，三选一；
文件夹范围：导全部，或只导某一个项目；
斜杠命令 ：/clear、/model 这类命令默认不算"真正的 Prompt"，可选包含；
实时预览：动手导出前，先告诉你这个范围将导出多少条、跨几个文件夹、几天。

导出来的 Markdown 大致长这样（按文件夹分组、正文完整保留）：

markdown 复制代码

# Claude Code Prompt 导出

> 时间范围：2026-05-16 ~ 2026-05-18 · 共 42 条 · 3 个文件夹

## 📁 cc-history-viewer
`~/GithubProjects/cc-history-viewer` · 30 条

**2026-05-16 09:14**

帮我把解析逻辑抽出来，单独放一个 parser.rs

拿到这份文件，你可以直接当周报素材、丢进笔记软件归档，或者整段喂给大模型让它替你总结复盘------原始 JSONL 干不了的事，现在一个按钮搞定。

5、技术实现

这部分是重点------讲讲它到底是拿什么、怎么搭出来的。

5.1 整体架构：为什么是 Tauri

它是一个 Tauri v2 应用：

前端：Vite + React 18 + TypeScript + Tailwind CSS v4，负责界面；
后端：Rust，负责文件 I/O、JSONL 解析、建索引、搜索；
两者通过 Tauri 的 IPC 通信------前端 invoke 一个命令，Rust 侧执行后把结果传回。

为什么不用 Electron？因为这是个本地小工具，对体积和启动速度敏感------Tauri 打包产物只有几 MB（Electron 动辄上百 MB），且复用系统自带的 WebView。更关键的是：要读取并解析几百 MB 的 JSONL，Rust 的性能与内存表现远好于 Node，还天然没有额外运行时依赖。

5.2 数据解析与合并去重

这是后端最有意思的部分。

第一个问题：Prompt 从哪来。 我做的是双数据源合并 ------history.jsonl 里是你输入框敲的 Prompt，projects/*.jsonl 里也有用户消息，两者大量重叠。后端把两边都解析出来，按"项目 + 文本 + 时间窗口"聚类去重，合并成一条，并标注它的来源（仅历史 / 仅对话 / 两者都有）。同时过滤掉工具结果、命令回显、系统提示这些噪音。

第二个问题：中文路径还原。 前面说过 projects/ 的目录名是编码过的，中文会变成一堆 -，没法可靠反解。我的解法是绕开它 ------每个对话 JSONL 的每一行里都带了一个 cwd 字段，记录着当时真实的工作目录绝对路径。直接取 cwd，编码还原这个难题就根本不存在了。

第三个问题：几百 MB 怎么扛。 我本地的 projects/ 有 400MB+、上千个文件。后端用 Rust 的 rayon 把文件解析并行化，几秒就能扫完一遍。

5.3 索引与磁盘缓存

每次启动都全量扫几百 MB 显然不行。所以后端在首次扫描后，会把解析结果建成一个索引，缓存到应用数据目录。下次启动时先比对所有源文件的修改时间（mtime）指纹：没变化就直接秒读缓存，变化了才重建。缓存是覆盖式写入的单个文件，不会越积越大。

5.4 搜索的实现

搜索放在 Rust 侧做，不依赖前端。查询词按空格分词，每个词在 Prompt 文本里做大小写不敏感的子串匹配，全部命中（AND）才算匹配；匹配的同时记录下每个命中片段的字符区间，一起返回给前端做高亮渲染。数据量不大时这套朴素算法足够快，而且行为完全可预测。

5.5 导出：一个好索引带来的红利

4.5 的导出功能，后端几乎没写一行新的解析代码------这件事我觉得值得单独说一句。

因为建索引那一步，已经把每条 Prompt 连同它的时间戳、所属项目、来源、是否斜杠命令全都算好、放进了内存。所以"按日期范围导出"本质上只是在这份现成的索引上做三件事：按时间范围过滤 → 排序 → 拼成 Markdown 字符串，纯内存操作，连磁盘都不用再读。日期边界用本地时区把"起始日 00:00 ~ 结束日 23:59:59.999"换算成毫秒，和统计图表用的是同一套口径。

一个设计得当的中间层（这里就是那份索引），能让后面新加的功能近乎免费------这是我做这个小项目最有体感的一点。

5.6 技术选型小结

关注点	选择	理由
桌面框架	Tauri v2	体积小、启动快、原生 Rust 后端
前端	React + TypeScript + Tailwind	生态成熟、类型安全
后端	Rust	解析大量 JSONL 快、无额外运行时依赖
数据处理	rayon 并行 + mtime 缓存	首次秒级扫描，后续秒开
导出	复用索引做过滤/排序/拼接	不重复解析，新功能近乎零成本

整个项目坚持两条原则：只读（绝不修改 ~/.claude 下任何文件）与纯本地（不联网、不上传任何对话内容）。

6、总结

CC History Viewer 解决的是一个具体而真实的小痛点：让 Claude Code 散落在本地的交互历史重新变得可浏览、可检索、可导出。技术上它是一个 Tauri v2 应用------Rust 负责把三处数据源解析、合并去重、建索引，React 负责把它呈现成一个清爽的桌面界面；而最新的按日期范围导出，又复用这份索引把 Prompt 整段落成 Markdown。

它已经在 GitHub 开源，MIT 协议，欢迎试用、提 Issue、发 PR：

🔗 https://github.com/XZL-CODE/cc-history-viewer

如果你也是 Claude Code 的重度用户，不妨把它跑起来，看看自己这段时间到底跟 AI 聊了些什么------那大概会是一份挺有意思的"使用回忆录"。

|--------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------|
| 🚀 持续探索 AI 与前沿技术 分享大模型应用、软件开发实战与行业洞察。欢迎关注 【龙哥AI】，加入 7000+ 技术同行的交流圈！ 🌟 探索技术边界，让开发更有效率 | |