claudecode-history-viewer 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 wonderomg
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.en-US.md

@@ -0,0 +1,125 @@
+<div align="center">
+
+# claude-history-viewer
+
+**A lightweight, local web viewer for Claude Code and Cursor conversation history.**
+
+Browse, search, and export sessions from `~/.claude` and `~/.cursor` — **100% offline**, no cloud, no telemetry.
+
+[![Stars](https://img.shields.io/github/stars/wonderomg/claude-history-viewer?style=flat&color=yellow)](https://github.com/wonderomg/claude-history-viewer/stargazers)
+![Node](https://img.shields.io/badge/Node.js-18%2B-339933?logo=node.js&logoColor=white)
+![License](https://img.shields.io/badge/License-MIT-blue.svg)
+
+**Languages**: [中文 (简体)](README.md) | [English](README.en-US.md)
+
+</div>
+
+<p align="center">
+  <img width="80%" alt="History" src="https://raw.githubusercontent.com/wonderomg/claude-history-viewer/master/claude-history-viewer.png" />
+</p>
+
+## Quick Start
+
+Requires **Node.js 18+**. Optional: existing `~/.claude` / `~/.cursor` history on your machine.
+
+```bash
+git clone https://github.com/wonderomg/claude-history-viewer.git
+cd claude-history-viewer
+npm install
+npm run build && npm start
+```
+
+Open **http://localhost:3747**
+
+Auto-open on start; disable: `NO_OPEN_BROWSER=1 npm start`.
+
+For development (hot reload): `npm run dev` → http://localhost:5173
+
+---
+
+## Disclaimer
+
+Independent open-source project, **not affiliated with Anthropic or Cursor**. Trademark names belong to their owners. Read-only access to local history files only.
+
+---
+
+## Features
+
+| Feature | Description |
+|---------|-------------|
+| Dual source | Sidebar **All / Claude Code / Cursor**; search follows source |
+| Sessions | Filter by project, expandable sub-agents |
+| Chat UI | User / Markdown / Thinking / tool calls & results |
+| Search | Global + in-session (highlight, prev/next, Enter to jump) |
+| Extras | Raw JSONL, Markdown export, light/dark theme, EN/中文 UI |
+
+---
+
+## Data paths
+
+| Source | Path | Content |
+|--------|------|---------|
+| Claude Code | `~/.claude/sessions/*.json` | Session metadata |
+| Claude Code | `~/.claude/projects/{slug}/{sessionId}.jsonl` | Main conversation |
+| Claude Code | `.../{sessionId}/subagents/*.jsonl` | Sub-agent |
+| Cursor | `~/.cursor/projects/{slug}/agent-transcripts/{id}/{id}.jsonl` | Agent transcript |
+| Cursor | `.../subagents/*.jsonl` | Sub-agent |
+
+Project slugs like `-Users-you-code-project` are decoded to readable paths in the UI.
+
+---
+
+## Configuration
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `HOST` | `127.0.0.1` | API bind address |
+| `PORT` | `3747` | API / production static server |
+| `VITE_PORT` | `5173` | Vite dev port |
+| `NO_OPEN_BROWSER` | — | `1` to skip opening browser |
+
+---
+
+## Local API
+
+`GET /api/health` · `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=`
+
+---
+
+## Privacy & security
+
+- Reads `~/.claude` and `~/.cursor` only; nothing uploaded
+- Chats may contain secrets; the viewer shows them as-is
+- No auth; bound to localhost by default — do not expose to untrusted networks
+
+---
+
+## FAQ
+
+| Issue | Fix |
+|-------|-----|
+| Cannot connect to backend | Run `npm run build && npm start`; ensure port `3747` is free |
+| Empty session list | Ensure history dirs exist and tools have written data |
+| Search/highlight off | Press **Enter** in in-session search, or use ◀ ▶ after render |
+
+---
+
+## Limitations
+
+Claude Code and Cursor only; web UI; no token analytics, live file watch, or session edit/delete.
+
+---
+
+## License
+
+[MIT License](LICENSE)
+
+---
+
+<div align="center">
+
+If this project helps you, please give it a star!
+
+[![Star History Chart](https://api.star-history.com/svg?repos=wonderomg/claude-history-viewer&type=Date)](https://star-history.com/#wonderomg/claude-history-viewer&Date)
+
+</div>

package/README.md

@@ -0,0 +1,125 @@
+<div align="center">
+
+# claude-history-viewer
+
+**轻量级本地 Web 查看器，用于浏览 Claude Code 与 Cursor 会话历史。**
+
+从 `~/.claude` 与 `~/.cursor` 读取对话记录，支持浏览、搜索与导出 — **完全离线**，无云端、无遥测。
+
+[![Stars](https://img.shields.io/github/stars/wonderomg/claude-history-viewer?style=flat&color=yellow)](https://github.com/wonderomg/claude-history-viewer/stargazers)
+![Node](https://img.shields.io/badge/Node.js-18%2B-339933?logo=node.js&logoColor=white)
+![License](https://img.shields.io/badge/License-MIT-blue.svg)
+
+**语言**: [中文 (简体)](README.md) | [English](README.en-US.md)
+
+</div>
+
+<p align="center">
+  <img width="80%" alt="History" src="https://raw.githubusercontent.com/wonderomg/claude-history-viewer/master/claude-history-viewer.png" />
+</p>
+
+## 快速开始
+
+需要 **Node.js 18+**。本机可选已有 `~/.claude` / `~/.cursor` 历史数据。
+
+```bash
+git clone https://github.com/wonderomg/claude-history-viewer.git
+cd claude-history-viewer
+npm install
+npm run build && npm start
+```
+
+浏览器访问 **http://localhost:3747**
+
+启动后会尝试自动打开；禁用：`NO_OPEN_BROWSER=1 npm start`。
+
+开发调试（热更新）：`npm run dev` → http://localhost:5173
+
+---
+
+## 免责声明
+
+独立开源项目，与 **Anthropic**、**Cursor** 无官方关系；相关名称为各自商标。仅只读本机历史文件。
+
+---
+
+## 功能
+
+| 功能 | 说明 |
+|------|------|
+| 双来源 | 侧栏 **全部 / Claude Code / Cursor**，搜索随来源过滤 |
+| 会话列表 | 按项目筛选、Sub-agent 树形展开 |
+| 对话渲染 | 用户 / Markdown / Thinking / Tool Call & Result |
+| 搜索 | 跨会话 + 会话内（高亮、`上一处/下一处`、回车定位） |
+| 其他 | 原始 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 |
+
+项目 slug（如 `-Users-you-code-project`）会在界面中还原为可读路径。
+
+---
+
+## 配置
+
+| 变量 | 默认 | 说明 |
+|------|------|------|
+| `HOST` | `127.0.0.1` | API 监听地址 |
+| `PORT` | `3747` | API / 生产静态服务端口 |
+| `VITE_PORT` | `5173` | Vite 开发端口 |
+| `NO_OPEN_BROWSER` | — | `1` 禁用自动打开浏览器 |
+
+---
+
+## 本地 API
+
+`GET /api/health` · `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=`
+
+---
+
+## 隐私与安全
+
+- 仅读取 `~/.claude`、`~/.cursor`，不上传云端
+- 对话中可能含密钥与内部信息，界面会如实展示
+- API 无鉴权，默认仅本机；勿暴露到不可信网络
+
+---
+
+## 常见问题
+
+| 问题 | 处理 |
+|------|------|
+| 无法连接后端 | 确认已执行 `npm run build && npm start`，端口 `3747` 未被占用 |
+| 列表为空 | 确认对应目录存在且已有工具产生的历史 |
+| 搜索/高亮不准 | 会话内搜索按 **回车** 或等渲染后用 ◀ ▶ |
+
+---
+
+## 局限性
+
+仅支持 Claude Code 与 Cursor；Web 界面；无 Token 统计、实时监听、会话增删改。
+
+---
+
+## 许可证
+
+[MIT License](LICENSE)
+
+---
+
+<div align="center">
+
+如果这个项目对您有帮助，请给它一个星标！
+
+[![Star History Chart](https://api.star-history.com/svg?repos=wonderomg/claude-history-viewer&type=Date)](https://star-history.com/#wonderomg/claude-history-viewer&Date)
+
+</div>

package/SECURITY.md

@@ -0,0 +1,23 @@
+# Security Policy
+
+## Supported Versions
+
+Security fixes are provided for the latest release on the default branch.
+
+## Reporting a Vulnerability
+
+Please **do not** open a public GitHub issue for security vulnerabilities.
+
+Report security issues via [GitHub Security Advisories](https://github.com/wonderomg/claude-history-viewer/security/advisories/new) or by opening a private report through the repository maintainer.
+
+Include:
+
+- A description of the issue and potential impact
+- Steps to reproduce
+- Your environment (OS, Node.js version)
+
+We aim to acknowledge reports within a reasonable timeframe.
+
+## Scope Notes
+
+This application reads local conversation files under `~/.claude` and `~/.cursor`. It is intended for **local use only**. Do not expose the API port to untrusted networks without authentication and a reverse proxy.

package/index.html

@@ -0,0 +1,27 @@
+<!DOCTYPE html>
+<html lang="zh-CN" class="dark">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>claude-history-viewer</title>
+    <script>
+      (function () {
+        var theme = localStorage.getItem('claude-history-viewer-theme');
+        if (theme === 'light' || theme === 'dark') {
+          document.documentElement.classList.remove('dark', 'light');
+          document.documentElement.classList.add(theme);
+          document.documentElement.dataset.theme = theme;
+        }
+        var locale = localStorage.getItem('claude-history-viewer-locale');
+        if (locale === 'zh' || locale === 'en') {
+          document.documentElement.lang = locale === 'zh' ? 'zh-CN' : 'en';
+          document.documentElement.dataset.locale = locale;
+        }
+      })();
+    </script>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="/src/main.js"></script>
+  </body>
+</html>

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "claudecode-history-viewer",
+  "version": "1.0.0",
+  "description": "Local web viewer for Claude Code and Cursor conversation history",
+  "license": "MIT",
+  "author": "wonderomg",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/wonderomg/claude-history-viewer.git"
+  },
+  "bugs": {
+    "url": "https://github.com/wonderomg/claude-history-viewer/issues"
+  },
+  "homepage": "https://github.com/wonderomg/claude-history-viewer#readme",
+  "keywords": [
+    "claude",
+    "cursor",
+    "conversation-history",
+    "jsonl",
+    "local",
+    "viewer"
+  ],
+  "type": "module",
+  "scripts": {
+    "dev": "concurrently -n server,web -c blue,green \"node server/index.js\" \"vite\"",
+    "build": "vite build",
+    "preview": "vite preview",
+    "start": "NODE_ENV=production node server/index.js"
+  },
+  "dependencies": {
+    "express": "^4.21.2",
+    "highlight.js": "^11.11.1",
+    "markdown-it": "^14.1.0",
+    "vue": "^3.5.13"
+  },
+  "devDependencies": {
+    "@vitejs/plugin-vue": "^5.2.1",
+    "autoprefixer": "^10.4.20",
+    "concurrently": "^9.1.2",
+    "postcss": "^8.4.49",
+    "tailwindcss": "^3.4.17",
+    "vite": "^6.0.7"
+  }
+}

package/postcss.config.js

@@ -0,0 +1,6 @@
+export default {
+  plugins: {
+    tailwindcss: {},
+    autoprefixer: {},
+  },
+}

package/server/export.js

@@ -0,0 +1,73 @@
+/**
+ * 将解析后的消息列表导出为 Markdown
+ */
+
+export function messagesToMarkdown(session, meta, messages) {
+  const lines = []
+  const title = meta?.title || session?.title || 'Claude Code Session'
+  lines.push(`# ${title}`)
+  lines.push('')
+  lines.push(`- **Session ID**: \`${session?.id || ''}\``)
+  if (session?.parentSessionId) {
+    lines.push(`- **类型**: Sub-agent（父会话 \`${session.parentSessionId}\`）`)
+  }
+  if (session?.agentType) lines.push(`- **Agent 类型**: ${session.agentType}`)
+  if (session?.agentDescription) lines.push(`- **描述**: ${session.agentDescription}`)
+  lines.push(`- **项目**: \`${session?.projectPath || ''}\``)
+  lines.push(`- **工作目录**: \`${session?.cwd || ''}\``)
+  if (session?.updatedAt) {
+    lines.push(`- **更新时间**: ${new Date(session.updatedAt).toLocaleString('zh-CN')}`)
+  }
+  lines.push('')
+  lines.push('---')
+  lines.push('')
+
+  for (const msg of messages) {
+    if (msg.role === 'user') {
+      lines.push('## User')
+      lines.push('')
+      lines.push(msg.text || '')
+      lines.push('')
+    } else if (msg.role === 'assistant') {
+      lines.push('## Assistant')
+      if (msg.model) lines.push(`*model: ${msg.model}*`)
+      lines.push('')
+      if (msg.thinking) {
+        lines.push('<details>')
+        lines.push('<summary>Thinking</summary>')
+        lines.push('')
+        lines.push(msg.thinking)
+        lines.push('')
+        lines.push('</details>')
+        lines.push('')
+      }
+      if (msg.toolUses?.length) {
+        for (const t of msg.toolUses) {
+          lines.push(`### Tool: \`${t.name}\``)
+          lines.push('')
+          lines.push('```json')
+          lines.push(JSON.stringify(t.input, null, 2))
+          lines.push('```')
+          lines.push('')
+        }
+      }
+      if (msg.text) {
+        lines.push(msg.text)
+        lines.push('')
+      }
+    } else if (msg.role === 'tool_result') {
+      const label = msg.isError ? 'Tool Error' : 'Tool Result'
+      lines.push(`## ${label}`)
+      lines.push('')
+      lines.push('```')
+      lines.push(msg.content || '')
+      lines.push('```')
+      lines.push('')
+    } else if (msg.role === 'system' && msg.subtype === 'turn_duration') {
+      lines.push(`*— 本轮耗时 ${Math.round((msg.durationMs || 0) / 1000)}s —*`)
+      lines.push('')
+    }
+  }
+
+  return lines.join('\n')
+}

package/server/index.js

@@ -0,0 +1,190 @@
+import express from 'express'
+import path from 'path'
+import { fileURLToPath } from 'url'
+import {
+  scanAllSessions,
+  findSessionById,
+  readRawTranscript,
+  getClaudeDir,
+  decodeProjectSlug,
+} from './scanner.js'
+import { getCursorDir } from './scanner-cursor.js'
+import { parseTranscript, searchInTranscript } from './parser.js'
+import { parseCursorTranscript, searchInCursorTranscript } from './parser-cursor.js'
+import { messagesToMarkdown } from './export.js'
+import { openBrowser } from './open-browser.js'
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+const PORT = process.env.PORT || 3747
+const HOST = process.env.HOST || '127.0.0.1'
+const isProd = process.env.NODE_ENV === 'production'
+
+const app = express()
+app.use(express.json())
+
+function parseSessionFile(session) {
+  if (session.source === 'cursor') {
+    return parseCursorTranscript(session.filePath)
+  }
+  return parseTranscript(session.filePath)
+}
+
+function searchSessionFile(session, query) {
+  if (session.source === 'cursor') {
+    return searchInCursorTranscript(session.filePath, query)
+  }
+  return searchInTranscript(session.filePath, query)
+}
+
+app.get('/api/health', (_req, res) => {
+  res.json({ ok: true, claudeDir: getClaudeDir(), cursorDir: getCursorDir() })
+})
+
+app.get('/api/sessions', (req, res) => {
+  try {
+    const source = req.query.source || 'all'
+    const sessions = scanAllSessions({ source })
+    const projects = [...new Set(sessions.map((s) => s.projectSlug))].map((slug) => ({
+      slug,
+      path: sessions.find((s) => s.projectSlug === slug)?.projectPath || slug,
+      count: sessions.filter((s) => s.projectSlug === slug).length,
+    }))
+    res.json({
+      sessions,
+      projects,
+      claudeDir: getClaudeDir(),
+      cursorDir: getCursorDir(),
+    })
+  } catch (err) {
+    console.error(err)
+    res.status(500).json({ error: err.message })
+  }
+})
+
+app.get('/api/sessions/:id', (req, res) => {
+  try {
+    const session = findSessionById(req.params.id)
+    if (!session) {
+      return res.status(404).json({ error: 'Session not found' })
+    }
+    const parsed = parseSessionFile(session)
+    const subagents =
+      session.kind === 'main'
+        ? scanAllSessions({ source: session.source }).filter(
+            (s) => s.kind === 'subagent' && s.parentSessionId === session.id
+          )
+        : []
+    res.json({
+      session,
+      meta: parsed.meta,
+      messages: parsed.messages,
+      subagents,
+    })
+  } catch (err) {
+    console.error(err)
+    res.status(500).json({ error: err.message })
+  }
+})
+
+app.get('/api/sessions/:id/raw', (req, res) => {
+  try {
+    const session = findSessionById(req.params.id)
+    if (!session) {
+      return res.status(404).json({ error: 'Session not found' })
+    }
+    const raw = readRawTranscript(session.filePath)
+    res.json({ session: { id: session.id, filePath: session.filePath }, ...raw })
+  } catch (err) {
+    console.error(err)
+    res.status(500).json({ error: err.message })
+  }
+})
+
+app.get('/api/sessions/:id/export', (req, res) => {
+  try {
+    const session = findSessionById(req.params.id)
+    if (!session) {
+      return res.status(404).json({ error: 'Session not found' })
+    }
+    const parsed = parseSessionFile(session)
+    const md = messagesToMarkdown(session, parsed.meta, parsed.messages)
+    const filename = `${session.title.replace(/[^\w\u4e00-\u9fa5-]+/g, '_').slice(0, 40)}.md`
+    res.setHeader('Content-Type', 'text/markdown; charset=utf-8')
+    res.setHeader('Content-Disposition', `attachment; filename="${encodeURIComponent(filename)}"`)
+    res.send(md)
+  } catch (err) {
+    console.error(err)
+    res.status(500).json({ error: err.message })
+  }
+})
+
+app.get('/api/sessions/:id/search', (req, res) => {
+  try {
+    const q = req.query.q || ''
+    const session = findSessionById(req.params.id)
+    if (!session) {
+      return res.status(404).json({ error: 'Session not found' })
+    }
+    const result = searchSessionFile(session, q)
+    res.json({ query: q, hits: result.hits, matches: result.matches, total: result.total })
+  } catch (err) {
+    console.error(err)
+    res.status(500).json({ error: err.message })
+  }
+})
+
+app.get('/api/search', (req, res) => {
+  try {
+    const q = (req.query.q || '').trim()
+    if (!q) return res.json({ query: q, results: [] })
+
+    const source = req.query.source || 'all'
+    const sessions = scanAllSessions({ source })
+    const results = []
+
+    for (const session of sessions) {
+      const result = searchSessionFile(session, q)
+      if (result.total > 0) {
+        results.push({
+          sessionId: session.id,
+          title: session.title,
+          projectPath: session.projectPath,
+          source: session.source,
+          kind: session.kind,
+          parentSessionId: session.parentSessionId,
+          hits: result.hits,
+          total: result.total,
+        })
+      }
+    }
+
+    res.json({ query: q, results })
+  } catch (err) {
+    console.error(err)
+    res.status(500).json({ error: err.message })
+  }
+})
+
+if (isProd) {
+  const dist = path.join(__dirname, '..', 'dist')
+  app.use(express.static(dist))
+  app.get('*', (_req, res) => {
+    res.sendFile(path.join(dist, 'index.html'))
+  })
+}
+
+const DEV_WEB_PORT = process.env.VITE_PORT || 5173
+
+app.listen(PORT, HOST, () => {
+  const apiUrl = `http://${HOST === '0.0.0.0' ? 'localhost' : HOST}:${PORT}`
+  const browseUrl = isProd ? apiUrl : `http://localhost:${DEV_WEB_PORT}`
+
+  console.log(`Claude History Viewer API → ${apiUrl}`)
+  console.log(`Reading from ${getClaudeDir()}`)
+  if (!isProd) {
+    console.log(`Dev frontend  → ${browseUrl} (proxy /api → :${PORT})`)
+  }
+
+  const delay = isProd ? 300 : 800
+  setTimeout(() => openBrowser(browseUrl), delay)
+})

package/server/open-browser.js

@@ -0,0 +1,37 @@
+import { spawn } from 'child_process'
+
+/**
+ * 启动后自动打开浏览器（macOS / Windows / Linux）
+ * 设置环境变量 NO_OPEN_BROWSER=1 可禁用
+ */
+export function openBrowser(url) {
+  if (process.env.NO_OPEN_BROWSER === '1' || process.env.NO_OPEN_BROWSER === 'true') {
+    return
+  }
+
+  let command
+  let args
+
+  if (process.platform === 'darwin') {
+    command = 'open'
+    args = [url]
+  } else if (process.platform === 'win32') {
+    command = 'cmd'
+    args = ['/c', 'start', '', url]
+  } else {
+    command = 'xdg-open'
+    args = [url]
+  }
+
+  try {
+    const child = spawn(command, args, {
+      detached: true,
+      stdio: 'ignore',
+      windowsHide: true,
+    })
+    child.unref()
+  } catch (err) {
+    console.warn(`[open-browser] 无法自动打开浏览器: ${err.message}`)
+    console.warn(`[open-browser] 请手动访问: ${url}`)
+  }
+}