claudex

---

🆕 最新动态

版本 1.3.0（2026 年 2 月 12 日）— MCP 服务

• 🧠 MCP 服务：Model Context Protocol 服务为 Claude Code 提供跨会话的持久记忆
• 🔧 10 个 MCP 工具：项目上下文、会话搜索、对话检索、结构化记忆的 CRUD 操作
• 💾 结构化记忆系统：存储编程知识（约定、架构、决策、错误模式），并设置优先级、置信度和 TTL
• 📋 3 个 MCP 提示词：/recall、/catchup、/history，快速访问过往会话
• 🎯 Token 预算管理：提供三个详细程度（minimal/standard/full），用于上下文管理
• 📖 一条命令即可完成设置：claude mcp add --transport stdio claudex -- claudex-mcp

此前发布的版本

版本 1.2.0（2025 年 11 月 11 日）

• 🎨 全面的主题系统：10 种专业主题（default、emerald、green、blue、purple、orange、red、rose、yellow、classic）
• 🔤 高级字体排版：29 种字体系列，可视化预览
• 📏 灵活的字体大小设置：5 种精确字号选项（14px-18px）
• 💾 设置持久化：所有自定义设置均保存至 localStorage

版本 1.1.0（2025 年 10 月 27 日）

• 🎯 智能标题提取：根据对话内容生成有意义的会话标题
• 📊 Tremor 数据分析仪表板：基于 Tailwind 的图表和多尺度可视化
• 🐳 Docker 多平台支持：amd64 和 arm64，优化后的镜像约为 200MB
• ⚡ 性能提升：异步搜索索引重建速度提升 121 倍

查看完整更新日志 | 故障排除指南

---

📸 截图

🎨 v1.2.0 新增：主题与自定义

10 款专业主题 经典、翡翠、蓝色、紫色、橙色、红色、玫瑰色、黄色、绿色、默认	29 种字体 直观预览实际字体样式
精细字号设置 5 种精确选项（14px-18px）+ 边框圆角控制	设置模态框 外观设置已可用，更多设置即将推出

对话视图

全文搜索

✨ 功能

• MCP 服务：为 Claude Code 提供持久记忆——约定、架构、决策和错误模式可跨会话保留
• 结构化记忆：存储和回忆编码知识，并设置优先级（1-10）、置信度和基于 TTL 的过期时间
• 自动发现项目：自动扫描 ~/.claude/projects 目录，发现多个项目中的所有对话
• 全文搜索：企业级 SQLite FTS5 搜索引擎，支持按项目、会话、角色、日期范围进行高级筛选，并突出显示内容
• 通用模板支持：智能检测并解析所有 Claude Code 版本（V1.x、V2-mixed、V2.0+）的模板，自动检测格式
• 智能内容渲染：语法高亮代码块、Markdown 渲染、差异可视化、JSON 格式化和工具使用跟踪
• 会话分析：功能全面的分析仪表板，使用 Tremor React 展示消息分布图表、文件操作跟踪和对话统计信息
• 导出选项：将对话导出为 JSON（结构化数据）、HTML（易读格式）或纯文本 TXT，以便存档和分享
• 现代界面：响应式 React 界面，提供 10 种主题、29 种字体和会话收藏功能，并针对开发者工作流进行优化

---

💖 支持此项目

Claudex 免费且开源。如果它为你节省了时间并改善了工作流，请考虑：

• ⭐ 为仓库点星——帮助更多人发现 Claudex
• 🐛 报告错误——你的反馈能帮助我们做得更好
• 💡 分享想法——在 Discussions 中提出功能需求
• ☕ 请我喝杯咖啡——支持持续开发

---

🚀 快速开始

前提条件

• Node.js 18+ 和 npm
• 已安装 Claude Code，且 ~/.claude/projects 中有对话历史记录

安装

选项 1：npm（推荐）

# Global installation
npm install -g @kunwarshah/claudex [https://www.npmjs.com/package/@kunwarshah/claudex]

# Then run anywhere:
claudex

# Custom port (if 3400 is in use):
claudex --port 3500

# Custom project directory:
claudex --project-root ~/my-claude-projects

# Or use without installing (npx):
npx @kunwarshah/claudex

添加 MCP 服务（为 Claude Code 提供持久记忆）：

claude mcp add --transport stdio claudex -- claudex-mcp

详情请参阅 MCP 服务指南。

CLI 选项：

• --help, -h：显示帮助信息
• --version, -v：显示版本
• --port, -p <port>：自定义服务端口（默认：3400）
• --project-root <path>：自定义 Claude 项目目录

环境变量：

• PORT：服务端口（默认：3400）
• PROJECT_ROOT：Claude 项目目录（默认：~/.claude/projects）

选项 2：从源码构建

1. 克隆仓库：

git clone https://github.com/kunwar-shah/claudex.git
cd claudex

2. 运行系统检查（可选，但推荐）：

npm run check

此操作会验证你的环境并排查常见的设置问题。

3. 安装依赖项（或使用自动修复）：

# Option 1: Manual installation
npm install
cd server && npm install && cd ..
cd client && npm install && cd ..

# Option 2: Auto-fix (installs deps + creates .env)
npm run check:fix

4. 配置环境（如果不使用自动修复）：

cd server
cp .env.example .env
# Edit .env if needed (default: PROJECT_ROOT=~/.claude/projects)
cd ..

5. 启动应用程序：

# Automatically runs system check, then starts servers
npm run dev

6. 打开浏览器：http://localhost:3000

后端 API 运行在 http://localhost:3400

系统检查器

Claudex 内置了全面的系统检查器，用于验证你的环境：

# Quick check
npm run check

# Detailed output
npm run check:verbose

# Auto-fix common issues
npm run check:fix

# JSON output (for CI/CD)
npm run check:json

检查内容：

• ✅ Node.js 和 npm 版本
• ✅ PROJECT_ROOT 路径和权限
• ✅ 端口可用性（3000、3400）
• ✅ 依赖项安装情况
• ✅ Claude Code 数据（项目、会话）
• ✅ JSONL 文件有效性
• ✅ 数据库权限
• ✅ 搜索索引状态

全局 CLI 安装（可选）

全局安装后，可在任何位置使用 claudex 命令：

./install.sh

# Then run from anywhere:
claudex

🔧 配置

服务配置（.env）

# Path to Claude Code projects directory
# Supports ~ expansion (e.g., ~/.claude/projects)
PROJECT_ROOT=~/.claude/projects

# Server port
PORT=3400

# Environment
NODE_ENV=development

默认端口

• 前端：http://localhost:3000（Vite 开发服务）
• 后端：http://localhost:3400（Fastify API）
• 前端构建：使用端口 3400（生产环境中由后端提供服务）

📂 项目结构

claudex/
├── server/                    # Backend (Node.js + Fastify)
│   ├── src/
│   │   ├── parsers/          # Template detection & message parsing
│   │   │   ├── templateDetector.js    # V1/V2/V3 template detection
│   │   │   └── messageParser.js       # Universal message parser
│   │   ├── services/         # Core business logic
│   │   │   ├── fileScanner.js        # Project/session discovery
│   │   │   ├── sessionParser.js      # Full session parsing
│   │   │   ├── searchDatabase.js     # SQLite FTS5 search
│   │   │   ├── searchIndexer.js      # Search index builder
│   │   │   └── memoryService.js      # Structured memory CRUD
│   │   ├── mcp/              # MCP server (Claude Code integration)
│   │   │   ├── index.js              # MCP entry point + stdio transport
│   │   │   ├── tools.js              # 10 MCP tool handlers
│   │   │   ├── resources.js          # MCP resources
│   │   │   └── prompts.js            # 3 MCP prompts
│   │   ├── routes/           # API endpoints
│   │   │   ├── projects.js           # Project/session routes
│   │   │   ├── search.js             # Search routes
│   │   │   └── export.js             # Export routes
│   │   ├── utils/            # Helper utilities
│   │   │   └── pathHelper.js         # Path expansion (~/ support)
│   │   └── server.js         # Main server
│   ├── data/                 # SQLite database (auto-created)
│   ├── .env.example          # Environment template
│   └── package.json
├── client/                   # Frontend (React + Vite)
│   ├── src/
│   │   ├── components/       # React components
│   │   │   ├── ProjectSelector.jsx
│   │   │   ├── SessionList.jsx
│   │   │   ├── ConversationThread.jsx
│   │   │   ├── MessageBubble.jsx
│   │   │   ├── ClaudeMessageRenderer.jsx
│   │   │   └── SearchPage.jsx
│   │   ├── services/         # API client
│   │   │   └── api.js
│   │   └── App.jsx           # Main app
│   └── package.json
├── bin/                      # CLI entry point
├── test-search.sh           # Search API testing script
├── install.sh               # Global CLI installer
├── SETUP.md                 # Detailed setup guide
├── README.md                # This file
└── package.json             # Root package (CLI + concurrently)

🎯 支持的 Claude Code 格式

查看器会自动检测并解析所有 Claude Code 对话格式：

V3 模板（通用 — 推荐）

• Claude Code v2.0+：新格式，直接包含 role 字段
• Claude Code v1.x：原始格式，包含 type 字段
• 边缘情况：混合格式和迁移状态
• 新消息类型：支持 file-history-snapshot
• 角色映射：所有系统消息 → assistant（二元 user/assistant 分类）

旧版模板（自动检测）

• V2-Mixed：V1 和 V2 之间的过渡格式
• V1：原始 Claude Code 格式

模板检测器采用逐级检测策略，自动为你的对话文件选择最佳解析器。

🔍 搜索系统

构建搜索索引

搜索前需要先构建搜索索引：

# Option 1: Via API
curl -X POST http://localhost:3400/api/search/index/build

# Option 2: Via test script
./test-search.sh

# Option 3: Via UI (Search page → "Rebuild Index" button)

何时重建索引

在以下情况下重建搜索索引：

• 首次设置时
• 模板变更后
• 添加新对话时
• 搜索结果似乎过时时

搜索 API 示例

# Basic search
curl -X POST http://localhost:3400/api/search \
  -H "Content-Type: application/json" \
  -d '{"q": "migration", "limit": 10}'

# Search with filters
curl -X POST http://localhost:3400/api/search \
  -H "Content-Type: application/json" \
  -d '{
    "q": "database",
    "projectId": "my-project",
    "role": "user",
    "limit": 20,
    "offset": 0
  }'

# Check index status
curl http://localhost:3400/api/search/index/status

📡 API 端点

项目与会话

端点	方法	描述
/api/projects	GET	列出所有项目
/api/projects/:id/sessions	GET	获取项目的会话
/api/projects/:id/sessions/:sessionId	GET	获取包含消息的完整会话

搜索

端点	方法	描述
/api/search	POST	搜索对话（FTS5）
/api/search/index/build	POST	构建/重建搜索索引
/api/search/index/status	GET	获取索引统计信息
/api/search/index/clear	POST	清空搜索索引

导出

端点	方法	描述
/api/export/session/:projectId/:sessionId?format=json	GET	导出为 JSON
/api/export/session/:projectId/:sessionId?format=html	GET	导出为 HTML
/api/export/session/:projectId/:sessionId?format=txt	GET	导出为 TXT

健康状态

端点	方法	描述
/api/health	GET	健康检查 + 系统信息

🛠️ 开发

开发模式

# Run both frontend + backend with hot reload
npm run dev

# Or run separately:
# Terminal 1 - Backend (auto-restarts on changes)
cd server && npm run dev

# Terminal 2 - Frontend (hot module replacement)
cd client && npm run dev

测试搜索系统

# Run comprehensive search tests
./test-search.sh

此脚本将：

1. 检查服务健康状况
2. 获取索引状态
3. 构建／重建索引
4. 使用各种筛选条件运行测试搜索
5. 显示结果

添加新模板

1. 更新模板检测器（server/src/parsers/templateDetector.js）：

'my-template': {
  name: 'My Template Name',
  detect: (samples) => {
    return samples.some(s => s.myUniqueField !== undefined);
  },
  parser: 'my-template'
}

2. 添加解析器方法（server/src/parsers/messageParser.js）：

parseMyTemplate(rawMessage) {
  return {
    id: rawMessage.id || this.generateId(),
    role: rawMessage.myRole === 'user' ? 'user' : 'assistant',
    content: rawMessage.myContent || '',
    timestamp: rawMessage.myTimestamp,
    // ... other fields
  };
}

3. 重建搜索索引：系统会自动检测并使用新模板。

📝 脚本参考

Claudex 目录

• npm run dev - 并发运行前端和后端（含预检查）
• npm start - 运行前端和后端（生产模式）
• npm run check - 运行系统健康检查
• npm run check:verbose - 运行详细系统检查
• npm run check:fix - 自动修复常见配置问题
• npm run check:json - 输出 JSON，供 CI/CD 使用
• ./install.sh - 安装为全局 CLI 命令
• ./test-search.sh - 测试搜索 API 端点

Server 目录

• npm run dev - 使用 nodemon 运行（自动重启）
• npm start - 以生产模式运行

Client 目录

• npm run dev - Vite 开发服务器（http://localhost:3000）
• npm run build - 构建生产版本
• npm run preview - 预览生产构建

🐛 故障排除

快速诊断

先运行系统检查器，查找问题：

npm run check:verbose

此操作会检查所有常见问题，并提供可执行的建议。

常见问题

明明存在消息，却显示“未找到消息”

已在 v1.1.1 中修复——如果你遇到间歇性空会话或重复键警告：

# Update to latest version
cd claude-viewer
git pull origin main
npm install && cd server && npm install && cd ../client && npm install && cd ..
npm run dev

如需了解更多信息，请参阅详细故障排除指南。

未找到项目

# Check what the system sees
npm run check

# Verify path
cat server/.env | grep PROJECT_ROOT

• 确认 .env 中的 PROJECT_ROOT 指向 ~/.claude/projects
• 检查 Claude Code 是否已创建对话文件
• 运行 npm run check:fix 自动创建缺失目录

搜索无法正常工作

# Quick fix via UI
# Visit http://localhost:3000/search → Click "Rebuild Index"

# Or via command line
curl -X POST http://localhost:3400/api/search/index/build

端口冲突

# System checker will detect port conflicts
npm run check

# Auto-detected ports in use show PID
# Kill process: kill <PID>
# Or change PORT in server/.env

权限错误

# Check permissions
npm run check:verbose

# Fix permissions
chmod +r ~/.claude/projects
chmod +w claude-viewer/server/data

依赖问题

# Auto-install all dependencies
npm run check:fix

🚢 生产部署

使用 Docker（推荐）

Claudex 提供可用于生产环境的 Docker 配置，并采用多阶段构建以优化镜像大小。

Docker 快速入门

# Build and start with docker-compose
docker-compose up -d

# View logs
docker-compose logs -f

# Stop
docker-compose down

访问地址：http://localhost:3400

Docker 配置

默认的 docker-compose.yml 会以只读方式挂载你的 Claude 项目目录：

volumes:
  # Adjust path to match your system
  - ~/.claude/projects:/root/.claude/projects:ro

常见路径配置：

# Linux/macOS
~/.claude/projects:/root/.claude/projects:ro

# Windows (WSL2)
/mnt/c/Users/YourName/.claude/projects:/root/.claude/projects:ro

# Custom path
/path/to/your/projects:/root/.claude/projects:ro

Docker 命令

# Build image manually
docker build -t claudex:latest .

# Run container manually
docker run -d \
  -p 3400:3400 \
  -v ~/.claude/projects:/root/.claude/projects:ro \
  -v claudex-data:/app/data \
  --name claudex-web \
  claudex:latest

# Check health
docker ps  # Check STATUS column for "healthy"

# View logs
docker logs claudex-web -f

# Stop and remove
docker stop claudex-web && docker rm claudex-web

Docker 功能

• 多阶段构建：优化镜像大小（约 200 MB）
• 非 root 用户：以 nodejs 用户运行，确保安全
• 健康检查：自动监控健康状况
• 持久化卷：存储搜索索引和日志
• 只读挂载：以只读方式挂载 Claude 项目，确保安全
• 日志轮转：JSON 日志，最大 10 MB，轮转 3 个文件

Docker 环境变量

# Override in docker-compose.yml or docker run
-e PORT=3400                           # Server port
-e HOST=0.0.0.0                        # Bind address
-e NODE_ENV=production                 # Environment
-e PROJECT_ROOT=/root/.claude/projects # Claude projects path

手动生产构建

适用于非 Docker 部署：

# 1. Install dependencies
npm run install-deps

# 2. Build client
npm run build

# 3. Start server (serves built client)
cd server && NODE_ENV=production npm start

访问地址：http://localhost:3400

📋 路线图

• SQLite FTS5 全文搜索
• 通用模板支持（V1/V2/V3）
• 导出为 JSON/HTML/TXT
• Docker 部署（v1.1.0）
• 对话分析仪表板（v1.1.0）
• 主题系统——10 种主题、29 种字体（v1.2.0）
• 会话收藏／书签功能（v1.2.4）
• 面向 Claude Code 的 MCP 服务（v1.3.0）
• 结构化记忆系统（v1.3.0）
• Token 成本计算器
• WebSocket 实时更新
• 自定义解析器插件系统

---

📄 许可证

MIT 许可证——详情请参阅 LICENSE 文件。

🤝 参与贡献

1. Fork 此仓库
2. 创建功能分支：git checkout -b feature/amazing-feature
3. 提交更改：git commit -m 'Add amazing feature'
4. 推送到分支：git push origin feature/amazing-feature
5. 发起 Pull Request

📚 补充文档

• SETUP.md - 详细的设置和配置指南
• INSTALL.md - 旧版安装说明

💡 提示

• 使用搜索页面查找所有项目中的对话
• 导出对话以便与团队成员分享
• 添加新对话后重建搜索索引
• 检查 /api/health 端点以确认系统状态
• 使用 npm run dev 获得最佳开发体验，并启用热重载