claude-history-viewer

轻量级本地 Web 查看器，用于浏览 Claude Code、Cursor 与 Codex 会话历史。

从 ~/.claude、~/.cursor 与 ~/.codex 读取对话记录，支持浏览、搜索与导出 — 完全离线，无云端、无遥测。

语言: English | 中文 (简体)

快速开始

需要 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

如果这个项目对您有帮助，请给它一个星标！