claudecode-history-viewer

快速开始

需要 Node.js 18+。本机可选已有 ~/.claude / ~/.cursor / ~/.codex 历史数据。

从 npm 使用（推荐）

npx -y claudecode-history-viewer

npx 首次运行会询问是否安装依赖，加 -y 可跳过确认；装过后再次执行通常不再提示。

或全局安装后执行（无二次确认）：

npm install -g claudecode-history-viewer
claudecode-history-viewer

浏览器访问 http://localhost:3747（端口可自定义，见下方「配置」）

禁用自动打开：NO_OPEN_BROWSER=1 npx -y claudecode-history-viewer

指定端口：

npx -y claudecode-history-viewer --port 3800

从 GitHub 克隆（开发 / 改代码）

git clone https://github.com/wonderomg/claude-history-viewer.git
cd claude-history-viewer
npm install
npm run build && npm start

开发调试（热更新）：在源码目录执行 npm run dev → http://localhost:5173

---

免责声明

独立开源项目，与 Anthropic、Cursor、OpenAI 无官方关系；相关名称为各自商标。仅只读本机历史文件。

---

功能

功能	说明
三来源	侧栏 全部 / Claude Code / Cursor / Codex，搜索随来源过滤
会话列表	按项目筛选、Sub-agent 树形展开
对话渲染	用户 / Markdown / Thinking / Tool Call & Result
搜索	跨会话 + 会话内（高亮、上一处/下一处、回车定位）
用量面板	Token 统计、活动热力图、活动洞察、常用工具/插件/Skill/项目（Claude 与 Codex 为 JSONL 真实 usage；Cursor 为估算）
其他	原始 JSONL、导出 Markdown、浅色/深色/护眼主题、中/英文界面

---

数据路径

来源	路径	内容
Claude Code	~/.claude/sessions/*.json	会话元数据
Claude Code	~/.claude/projects/{slug}/{sessionId}.jsonl	主对话
Claude Code	.../{sessionId}/subagents/*.jsonl	Sub-agent
Cursor	~/.cursor/projects/{slug}/agent-transcripts/{id}/{id}.jsonl	Agent 对话
Cursor	.../subagents/*.jsonl	Sub-agent
Codex	~/.codex/sessions/**/rollout-*.jsonl	Codex CLI rollout 对话

项目 slug（如 -Users-you-code-project）会在界面中还原为可读路径。

Codex 数据目录：默认为 ~/.codex。若 Codex 数据在其他位置，可通过环境变量 CODEX_HOME 指定。

---

配置

首次启动时会自动创建 ~/.claudecode-history-viewer/config.yaml（若不存在）。

claudecode-history-viewer --init-config    # 手动创建配置文件
claudecode-history-viewer --config       # 查看配置路径与生效值
claudecode-history-viewer --help         # 全部 CLI 参数

命令行覆盖（优先级最高）

claudecode-history-viewer --port 3800 --language zh --theme eye
npm start -- --port 3800

参数	说明
--port, -p	监听端口
--host	绑定地址
--language, --lang	界面语言：zh | en
--theme	界面主题：light | dark | eye
--init-config	写入默认 ~/.claudecode-history-viewer/config.yaml
--config	打印当前生效配置
--force	配合 --init-config，覆盖已有文件

配置文件合并顺序（后者覆盖前者）

1. 安装包内 config.yaml
2. ~/.claudecode-history-viewer/config.yaml（用户配置，首次运行自动创建）
3. 当前目录 ./config.yaml

port: 3747
host: 127.0.0.1
language: zh   # 界面语言：zh | en，同「设置 → 语言」
theme: eye     # 界面主题：light | dark | eye（护眼豆沙绿）

每次启动会读取 config.yaml 的 language / theme，直到你在设置或顶栏主题按钮中改过（之后以浏览器记忆为准）。若要恢复为配置默认值，清除本站点的本地存储，或删除 DevTools → Application 中的 claude-history-viewer-locale-user / claude-history-viewer-theme-user。

环境变量

变量	默认	说明
HOST	127.0.0.1	API 监听地址（也可写在 config.yaml）
PORT	3747	API / 生产静态服务端口
VITE_PORT	5173	Vite 开发端口
NO_OPEN_BROWSER	—	1 禁用自动打开浏览器
CODEX_HOME	~/.codex	Codex 数据目录（sessions/ 下的 rollout JSONL）

---

本地 API

GET /api/health · GET /api/config · GET /api/sessions?source= · GET /api/sessions/:id · GET /api/sessions/:id/search?q= · GET /api/sessions/:id/raw · GET /api/sessions/:id/export · GET /api/search?q=&source= · GET /api/usage

---

隐私与安全

• 仅读取 ~/.claude、~/.cursor、~/.codex，不上传云端
• 对话中可能含密钥与内部信息，界面会如实展示
• API 无鉴权，默认仅本机；勿暴露到不可信网络

---

常见问题

问题	处理
无法连接后端	确认已运行 npx -y claudecode-history-viewer 或 npm start，端口 3747 未被占用
列表为空	确认对应目录存在且已有工具产生的历史；Codex 请检查 ~/.codex/sessions/**/rollout-*.jsonl
搜索/高亮不准	会话内搜索按 回车 或等渲染后用

---

局限性

支持 Claude Code、Cursor 与 Codex；Web 界面；无实时文件监听、会话增删改。用量面板中 Cursor 为 transcript 长度估算，Claude Code 与 Codex 优先使用 JSONL 中的 token 字段。

---

许可证

MIT License

---