Skip to content
Back to search

claudex

MCP server with persistent memory + FTS5 search for Claude Code conversation history. Index your ~/.claude/projects/, expose 10 MCP tools, browse via web UI. MIT-licensed.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/kunwar-shah--claudex/badge.svg)](/listings/kunwar-shah--claudex)

HTML

<a href="/listings/kunwar-shah--claudex"><img src="/api/listings/kunwar-shah--claudex/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Prerequisites

- Node.js 18+ and npm - Claude Code installed with conversation history in `~/.claude/projects`

Installation

Option 1: npm (Recommended)

# 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

**Add MCP Server** (gives Claude Code persistent memory):

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

See the [MCP Server Guide](https://kunwar-shah.github.io/claudex/#/mcp) for details.

**CLI Options**: - `--help, -h`: Show help message - `--version, -v`: Show version - `--port, -p <port>`: Custom server port (default: 3400) - `--project-root <path>`: Custom Claude projects directory

**Environment Variables**: - `PORT`: Server port (default: 3400) - `PROJECT_ROOT`: Claude projects directory (default: ~/.claude/projects)

Option 2: From Source

1. **Clone the repository**:

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

2. **Run system check** (optional but recommended):

npm run check

This validates your environment and catches common setup issues.

3. **Install dependencies** (or use auto-fix):

# 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. **Configure environment** (if not using auto-fix):

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

5. **Start the application**:

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

6. **Open your browser**: http://localhost:3000

The backend API runs on `http://localhost:3400`

System Checker

Claudex includes a comprehensive system checker that validates your environment:

# 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

**What it checks:** - ✅ Node.js & npm versions - ✅ PROJECT_ROOT path & permissions - ✅ Port availability (3000, 3400) - ✅ Dependencies installation - ✅ Claude Code data (projects, sessions) - ✅ JSONL file validity - ✅ Database permissions - ✅ Search index status

Global CLI Installation (Optional)

Install globally to use `claudex` command anywhere:

./install.sh

# Then run from anywhere:
claudex

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 713 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <div align="center">
  2. <img src="docs/logo-sm.png" alt="Claudex Logo" width="180">
  3. # Claudex
  4. **Professional conversation viewer and analysis tool for Claude Code**
  5. > **Category**: Development Tools · Conversation Analysis · Usage Monitoring
  6. Claudex is a full-stack web application designed for developers, QA engineers, and researchers who need to inspect, search, and analyze Claude Code conversation histories. Built with React and Fastify, it provides enterprise-grade full-text search using SQLite FTS5, universal template support for all Claude Code versions, and comprehensive analytics dashboards.
  7. [![Version](https://img.shields.io/github/v/release/kunwar-shah/claudex)](https://github.com/kunwar-shah/claudex/releases)
  8. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/kunwar-shah/claudex/blob/main/LICENSE)
  9. [![Documentation](https://img.shields.io/badge/docs-github--pages-blue)](https://kunwar-shah.github.io/claudex/)
  10. [![Discussions](https://img.shields.io/github/discussions/kunwar-shah/claudex)](https://github.com/kunwar-shah/claudex/discussions)
  11. [![Mentioned in Awesome Claude Code](https://awesome.re/mentioned-badge.svg)](https://github.com/hesreallyhim/awesome-claude-code)
  12. **📚 [Documentation](https://kunwar-shah.github.io/claudex/)** | **💬 [Discussions](https://github.com/kunwar-shah/claudex/discussions)** | **🐛 [Issues](https://github.com/kunwar-shah/claudex/issues)**
  13. ![Claudex — browse, search, and give Claude Code persistent memory. SQLite FTS5 full-text search across all sessions, MCP server with 10 tools, universal V1/V2/V3 template support.](screenshots/hero.gif)
  14. </div>
  15. ---
  16. ## 🆕 What's New
  17. ### Version 1.3.0 (February 12, 2026) — MCP Server
  18. - **🧠 MCP Server**: Model Context Protocol server gives Claude Code persistent memory across sessions
  19. - **🔧 10 MCP Tools**: Project context, session search, conversation retrieval, structured memory CRUD
  20. - **💾 Structured Memory System**: Store coding knowledge (conventions, architecture, decisions, error patterns) with priority, confidence, and TTL
  21. - **📋 3 MCP Prompts**: `/recall`, `/catchup`, `/history` for quick access to past sessions
  22. - **🎯 Token Budgeting**: Three detail levels (minimal/standard/full) for context management
  23. - **📖 One-Command Setup**: `claude mcp add --transport stdio claudex -- claudex-mcp`
  24. <details>
  25. <summary>Previous releases</summary>
  26. ### Version 1.2.0 (November 11, 2025)
  27. - **🎨 Comprehensive Theming System**: 10 professional themes (default, emerald, green, blue, purple, orange, red, rose, yellow, classic)
  28. - **🔤 Advanced Typography**: 29 font families with visual preview
  29. - **📏 Granular Font Sizing**: 5 precise font size options (14px-18px)
  30. - **💾 Settings Persistence**: All customizations saved to localStorage
  31. ### Version 1.1.0 (October 27, 2025)
  32. - **🎯 Smart Title Extraction**: Meaningful session titles from conversation content
  33. - **📊 Tremor Analytics Dashboard**: Tailwind-based charts and multi-scale visualizations
  34. - **🐳 Docker Multi-Platform**: amd64 and arm64 with optimized ~200MB images
  35. - **⚡ Performance**: 121x faster async search index rebuild
  36. </details>
  37. [View full changelog](https://kunwar-shah.github.io/claudex/#/changelog) | [Troubleshooting guide](https://kunwar-shah.github.io/claudex/#/troubleshooting)
  38. ---
  39. ## 📸 Screenshots
  40. ### 🎨 NEW in v1.2.0: Theming & Customization
  41. <table>
  42. <tr>
  43. <td width="50%">
  44. <img src="screenshots/v1.2.0/01-theme-selector.png" alt="10 Professional Themes" width="100%">
  45. <p align="center"><strong>10 Professional Themes</strong><br/>Classic, Emerald, Blue, Purple, Orange, Red, Rose, Yellow, Green, Default</p>
  46. </td>
  47. <td width="50%">
  48. <img src="screenshots/v1.2.0/02-font-family-preview.png" alt="29 Font Families" width="100%">
  49. <p align="center"><strong>29 Font Families</strong><br/>Visual preview showing actual typefaces</p>
  50. </td>
  51. </tr>
  52. <tr>
  53. <td width="50%">
  54. <img src="screenshots/v1.2.0/03-font-size-border-radius.png" alt="Font Size & Border Radius" width="100%">
  55. <p align="center"><strong>Granular Font Sizing</strong><br/>5 precise options (14px-18px) + border radius control</p>
  56. </td>
  57. <td width="50%">
  58. <img src="screenshots/v1.2.0/04-settings-tabs-soon-badges.png" alt="Settings Modal" width="100%">
  59. <p align="center"><strong>Settings Modal</strong><br/>Appearance functional, more settings coming soon</p>
  60. </td>
  61. </tr>
  62. </table>
  63. ### Conversation View
  64. <img src="screenshots/conversation-view.png" alt="Conversation View" width="800">
  65. ### Full-Text Search
  66. <img src="screenshots/search-results.png" alt="Search Results" width="800">
  67. ## ✨ Features
  68. - **MCP Server**: Give Claude Code persistent memory — conventions, architecture, decisions, and error patterns survive across sessions
  69. - **Structured Memory**: Store and recall coding knowledge with priority (1-10), confidence, and TTL-based expiration
  70. - **Auto Project Discovery**: Automatically scans `~/.claude/projects` directory to discover all conversations across multiple projects
  71. - **Full-Text Search**: Enterprise-grade SQLite FTS5 search engine with advanced filtering by project, session, role, date range, and content highlighting
  72. - **Universal Template Support**: Intelligent template detection and parsing for all Claude Code versions (V1.x, V2-mixed, V2.0+) with automatic format detection
  73. - **Smart Content Rendering**: Syntax-highlighted code blocks, markdown rendering, diff visualization, JSON formatting, and tool usage tracking
  74. - **Session Analytics**: Comprehensive analytics dashboard with message distribution charts, file operation tracking, and conversation statistics using Tremor React
  75. - **Export Options**: Export conversations to JSON (structured data), HTML (readable format), or plain TXT for archival and sharing
  76. - **Modern UI**: Responsive React interface with 10 themes, 29 fonts, session favorites, and optimized for developer workflows
  77. ---
  78. ## 💖 Support This Project
  79. Claudex is free and open source. If it saves you time and improves your workflow, please consider:
  80. - ⭐ **Star the repo** - Help others discover Claudex
  81. - 🐛 **Report bugs** - Your feedback makes us better
  82. - 💡 **Share ideas** - Request features in [Discussions](https://github.com/kunwar-shah/claudex/discussions)
  83. - ☕ **Buy me a coffee** - Support continued development
  84. <div align="center">
  85. [![Ko-fi](https://img.shields.io/badge/Ko--fi-Buy%20me%20a%20coffee-FF5E5B?logo=ko-fi&style=for-the-badge)](https://ko-fi.com/kunwarshah)
  86. [![PayPal](https://img.shields.io/badge/PayPal-Donate-00457C?logo=paypal&style=for-the-badge)](https://paypal.me/kunwarJhamat)
  87. <!-- [![GitHub Sponsors](https://img.shields.io/badge/Sponsor-GitHub-ea4aaa?logo=github&style=for-the-badge)](https://github.com/sponsors/kunwar-shah) -->
  88. **Every contribution helps keep this project alive and growing!** 🚀
  89. </div>
  90. ---
  91. ## 🚀 Quick Start
  92. ### Prerequisites
  93. - Node.js 18+ and npm
  94. - Claude Code installed with conversation history in `~/.claude/projects`
  95. ### Installation
  96. #### Option 1: npm (Recommended)
  97. ```bash
  98. # Global installation
  99. npm install -g @kunwarshah/claudex [https://www.npmjs.com/package/@kunwarshah/claudex]
  100. # Then run anywhere:
  101. claudex
  102. # Custom port (if 3400 is in use):
  103. claudex --port 3500
  104. # Custom project directory:
  105. claudex --project-root ~/my-claude-projects
  106. # Or use without installing (npx):
  107. npx @kunwarshah/claudex
  108. ```
  109. **Add MCP Server** (gives Claude Code persistent memory):
  110. ```bash
  111. claude mcp add --transport stdio claudex -- claudex-mcp
  112. ```
  113. See the [MCP Server Guide](https://kunwar-shah.github.io/claudex/#/mcp) for details.
  114. **CLI Options**:
  115. - `--help, -h`: Show help message
  116. - `--version, -v`: Show version
  117. - `--port, -p <port>`: Custom server port (default: 3400)
  118. - `--project-root <path>`: Custom Claude projects directory
  119. **Environment Variables**:
  120. - `PORT`: Server port (default: 3400)
  121. - `PROJECT_ROOT`: Claude projects directory (default: ~/.claude/projects)
  122. #### Option 2: From Source
  123. 1. **Clone the repository**:
  124. ```bash
  125. git clone https://github.com/kunwar-shah/claudex.git
  126. cd claudex
  127. ```
  128. 2. **Run system check** (optional but recommended):
  129. ```bash
  130. npm run check
  131. ```
  132. This validates your environment and catches common setup issues.
  133. 3. **Install dependencies** (or use auto-fix):
  134. ```bash
  135. # Option 1: Manual installation
  136. npm install
  137. cd server && npm install && cd ..
  138. cd client && npm install && cd ..
  139. # Option 2: Auto-fix (installs deps + creates .env)
  140. npm run check:fix
  141. ```
  142. 4. **Configure environment** (if not using auto-fix):
  143. ```bash
  144. cd server
  145. cp .env.example .env
  146. # Edit .env if needed (default: PROJECT_ROOT=~/.claude/projects)
  147. cd ..
  148. ```
  149. 5. **Start the application**:
  150. ```bash
  151. # Automatically runs system check, then starts servers
  152. npm run dev
  153. ```
  154. 6. **Open your browser**: http://localhost:3000
  155. The backend API runs on `http://localhost:3400`
  156. ### System Checker
  157. Claudex includes a comprehensive system checker that validates your environment:
  158. ```bash
  159. # Quick check
  160. npm run check
  161. # Detailed output
  162. npm run check:verbose
  163. # Auto-fix common issues
  164. npm run check:fix
  165. # JSON output (for CI/CD)
  166. npm run check:json
  167. ```
  168. **What it checks:**
  169. - ✅ Node.js & npm versions
  170. - ✅ PROJECT_ROOT path & permissions
  171. - ✅ Port availability (3000, 3400)
  172. - ✅ Dependencies installation
  173. - ✅ Claude Code data (projects, sessions)
  174. - ✅ JSONL file validity
  175. - ✅ Database permissions
  176. - ✅ Search index status
  177. ### Global CLI Installation (Optional)
  178. Install globally to use `claudex` command anywhere:
  179. ```bash
  180. ./install.sh
  181. # Then run from anywhere:
  182. claudex
  183. ```
  184. ## 🔧 Configuration
  185. ### Server Configuration (`.env`)
  186. ```env
  187. # Path to Claude Code projects directory
  188. # Supports ~ expansion (e.g., ~/.claude/projects)
  189. PROJECT_ROOT=~/.claude/projects
  190. # Server port
  191. PORT=3400
  192. # Environment
  193. NODE_ENV=development
  194. ```
  195. ### Default Ports
  196. - **Frontend**: http://localhost:3000 (Vite dev server)
  197. - **Backend**: http://localhost:3400 (Fastify API)
  198. - **Frontend build**: Uses port 3400 (served by backend in production)
  199. ## 📂 Project Structure
  200. ```
  201. claudex/
  202. ├── server/ # Backend (Node.js + Fastify)
  203. │ ├── src/
  204. │ │ ├── parsers/ # Template detection & message parsing
  205. │ │ │ ├── templateDetector.js # V1/V2/V3 template detection
  206. │ │ │ └── messageParser.js # Universal message parser
  207. │ │ ├── services/ # Core business logic
  208. │ │ │ ├── fileScanner.js # Project/session discovery
  209. │ │ │ ├── sessionParser.js # Full session parsing
  210. │ │ │ ├── searchDatabase.js # SQLite FTS5 search
  211. │ │ │ ├── searchIndexer.js # Search index builder
  212. │ │ │ └── memoryService.js # Structured memory CRUD
  213. │ │ ├── mcp/ # MCP server (Claude Code integration)
  214. │ │ │ ├── index.js # MCP entry point + stdio transport
  215. │ │ │ ├── tools.js # 10 MCP tool handlers
  216. │ │ │ ├── resources.js # MCP resources
  217. │ │ │ └── prompts.js # 3 MCP prompts
  218. │ │ ├── routes/ # API endpoints
  219. │ │ │ ├── projects.js # Project/session routes
  220. │ │ │ ├── search.js # Search routes
  221. │ │ │ └── export.js # Export routes
  222. │ │ ├── utils/ # Helper utilities
  223. │ │ │ └── pathHelper.js # Path expansion (~/ support)
  224. │ │ └── server.js # Main server
  225. │ ├── data/ # SQLite database (auto-created)
  226. │ ├── .env.example # Environment template
  227. │ └── package.json
  228. ├── client/ # Frontend (React + Vite)
  229. │ ├── src/
  230. │ │ ├── components/ # React components
  231. │ │ │ ├── ProjectSelector.jsx
  232. │ │ │ ├── SessionList.jsx
  233. │ │ │ ├── ConversationThread.jsx
  234. │ │ │ ├── MessageBubble.jsx
  235. │ │ │ ├── ClaudeMessageRenderer.jsx
  236. │ │ │ └── SearchPage.jsx
  237. │ │ ├── services/ # API client
  238. │ │ │ └── api.js
  239. │ │ └── App.jsx # Main app
  240. │ └── package.json
  241. ├── bin/ # CLI entry point
  242. ├── test-search.sh # Search API testing script
  243. ├── install.sh # Global CLI installer
  244. ├── SETUP.md # Detailed setup guide
  245. ├── README.md # This file
  246. └── package.json # Root package (CLI + concurrently)
  247. ```
  248. ## 🎯 Supported Claude Code Formats
  249. The viewer automatically detects and parses all Claude Code conversation formats:
  250. ### V3 Template (Universal - Recommended)
  251. - **Claude Code v2.0+**: New format with `role` field directly
  252. - **Claude Code v1.x**: Original format with `type` field
  253. - **Edge cases**: Mixed formats and migration states
  254. - **New message types**: `file-history-snapshot` support
  255. - **Role mapping**: All system messages → assistant (binary user/assistant classification)
  256. ### Legacy Templates (Auto-detected)
  257. - **V2-Mixed**: Transition format between V1 and V2
  258. - **V1**: Original Claude Code format
  259. The template detector uses a waterfall detection strategy, automatically selecting the best parser for your conversation files.
  260. ## 🔍 Search System
  261. ### Building the Search Index
  262. The search index needs to be built before searching:
  263. ```bash
  264. # Option 1: Via API
  265. curl -X POST http://localhost:3400/api/search/index/build
  266. # Option 2: Via test script
  267. ./test-search.sh
  268. # Option 3: Via UI (Search page → "Rebuild Index" button)
  269. ```
  270. ### When to Rebuild Index
  271. Rebuild the search index when:
  272. - First time setup
  273. - After template changes
  274. - When new conversations are added
  275. - If search results seem outdated
  276. ### Search API Examples
  277. ```bash
  278. # Basic search
  279. curl -X POST http://localhost:3400/api/search \
  280. -H "Content-Type: application/json" \
  281. -d '{"q": "migration", "limit": 10}'
  282. # Search with filters
  283. curl -X POST http://localhost:3400/api/search \
  284. -H "Content-Type: application/json" \
  285. -d '{
  286. "q": "database",
  287. "projectId": "my-project",
  288. "role": "user",
  289. "limit": 20,
  290. "offset": 0
  291. }'
  292. # Check index status
  293. curl http://localhost:3400/api/search/index/status
  294. ```
  295. ## 📡 API Endpoints
  296. ### Projects & Sessions
  297. | Endpoint | Method | Description |
  298. |----------|--------|-------------|
  299. | `/api/projects` | GET | List all projects |
  300. | `/api/projects/:id/sessions` | GET | Get sessions for project |
  301. | `/api/projects/:id/sessions/:sessionId` | GET | Get full session with messages |
  302. ### Search
  303. | Endpoint | Method | Description |
  304. |----------|--------|-------------|
  305. | `/api/search` | POST | Search conversations (FTS5) |
  306. | `/api/search/index/build` | POST | Build/rebuild search index |
  307. | `/api/search/index/status` | GET | Get index statistics |
  308. | `/api/search/index/clear` | POST | Clear search index |
  309. ### Export
  310. | Endpoint | Method | Description |
  311. |----------|--------|-------------|
  312. | `/api/export/session/:projectId/:sessionId?format=json` | GET | Export as JSON |
  313. | `/api/export/session/:projectId/:sessionId?format=html` | GET | Export as HTML |
  314. | `/api/export/session/:projectId/:sessionId?format=txt` | GET | Export as TXT |
  315. ### Health
  316. | Endpoint | Method | Description |
  317. |----------|--------|-------------|
  318. | `/api/health` | GET | Health check + system info |
  319. ## 🛠️ Development
  320. ### Development Mode
  321. ```bash
  322. # Run both frontend + backend with hot reload
  323. npm run dev
  324. # Or run separately:
  325. # Terminal 1 - Backend (auto-restarts on changes)
  326. cd server && npm run dev
  327. # Terminal 2 - Frontend (hot module replacement)
  328. cd client && npm run dev
  329. ```
  330. ### Testing the Search System
  331. ```bash
  332. # Run comprehensive search tests
  333. ./test-search.sh
  334. ```
  335. This script will:
  336. 1. Check server health
  337. 2. Get index status
  338. 3. Build/rebuild index
  339. 4. Run test searches with various filters
  340. 5. Display results
  341. ### Adding New Templates
  342. 1. **Update Template Detector** (`server/src/parsers/templateDetector.js`):
  343. ```javascript
  344. 'my-template': {
  345. name: 'My Template Name',
  346. detect: (samples) => {
  347. return samples.some(s => s.myUniqueField !== undefined);
  348. },
  349. parser: 'my-template'
  350. }
  351. ```
  352. 2. **Add Parser Method** (`server/src/parsers/messageParser.js`):
  353. ```javascript
  354. parseMyTemplate(rawMessage) {
  355. return {
  356. id: rawMessage.id || this.generateId(),
  357. role: rawMessage.myRole === 'user' ? 'user' : 'assistant',
  358. content: rawMessage.myContent || '',
  359. timestamp: rawMessage.myTimestamp,
  360. // ... other fields
  361. };
  362. }
  363. ```
  364. 3. **Rebuild Search Index**: The new template will be automatically detected and used.
  365. ## 📝 Scripts Reference
  366. ### Claudex Directory
  367. - `npm run dev` - Run frontend + backend concurrently (with pre-check)
  368. - `npm start` - Run frontend + backend (production mode)
  369. - `npm run check` - Run system health check
  370. - `npm run check:verbose` - Run detailed system check
  371. - `npm run check:fix` - Auto-fix common setup issues
  372. - `npm run check:json` - JSON output for CI/CD
  373. - `./install.sh` - Install as global CLI command
  374. - `./test-search.sh` - Test search API endpoints
  375. ### Server Directory
  376. - `npm run dev` - Run with nodemon (auto-restart)
  377. - `npm start` - Run in production mode
  378. ### Client Directory
  379. - `npm run dev` - Vite dev server (http://localhost:3000)
  380. - `npm run build` - Build for production
  381. - `npm run preview` - Preview production build
  382. ## 🐛 Troubleshooting
  383. ### Quick Diagnosis
  384. Run the system checker first to identify issues:
  385. ```bash
  386. npm run check:verbose
  387. ```
  388. This will check all common problems and provide actionable suggestions.
  389. ### Common Issues
  390. #### "No messages found" Despite Messages Existing
  391. **Fixed in v1.1.1** - If you see intermittent empty sessions or duplicate key warnings:
  392. ```bash
  393. # Update to latest version
  394. cd claude-viewer
  395. git pull origin main
  396. npm install && cd server && npm install && cd ../client && npm install && cd ..
  397. npm run dev
  398. ```
  399. See [detailed troubleshooting guide](https://kunwar-shah.github.io/claudex/#/troubleshooting) for more information.
  400. #### No Projects Found
  401. ```bash
  402. # Check what the system sees
  403. npm run check
  404. # Verify path
  405. cat server/.env | grep PROJECT_ROOT
  406. ```
  407. - Verify `PROJECT_ROOT` in `.env` points to `~/.claude/projects`
  408. - Check that Claude Code has created conversation files
  409. - Run `npm run check:fix` to auto-create missing directories
  410. #### Search Not Working
  411. ```bash
  412. # Quick fix via UI
  413. # Visit http://localhost:3000/search → Click "Rebuild Index"
  414. # Or via command line
  415. curl -X POST http://localhost:3400/api/search/index/build
  416. ```
  417. #### Port Conflicts
  418. ```bash
  419. # System checker will detect port conflicts
  420. npm run check
  421. # Auto-detected ports in use show PID
  422. # Kill process: kill <PID>
  423. # Or change PORT in server/.env
  424. ```
  425. #### Permission Errors
  426. ```bash
  427. # Check permissions
  428. npm run check:verbose
  429. # Fix permissions
  430. chmod +r ~/.claude/projects
  431. chmod +w claude-viewer/server/data
  432. ```
  433. #### Dependencies Issues
  434. ```bash
  435. # Auto-install all dependencies
  436. npm run check:fix
  437. ```
  438. ## 🚢 Production Deployment
  439. ### Using Docker (Recommended)
  440. Claudex includes production-ready Docker configuration with multi-stage builds for optimal image size.
  441. #### Quick Start with Docker
  442. ```bash
  443. # Build and start with docker-compose
  444. docker-compose up -d
  445. # View logs
  446. docker-compose logs -f
  447. # Stop
  448. docker-compose down
  449. ```
  450. Access at: http://localhost:3400
  451. #### Docker Configuration
  452. The default `docker-compose.yml` mounts your Claude projects directory as read-only:
  453. ```yaml
  454. volumes:
  455. # Adjust path to match your system
  456. - ~/.claude/projects:/root/.claude/projects:ro
  457. ```
  458. **Common path configurations:**
  459. ```bash
  460. # Linux/macOS
  461. ~/.claude/projects:/root/.claude/projects:ro
  462. # Windows (WSL2)
  463. /mnt/c/Users/YourName/.claude/projects:/root/.claude/projects:ro
  464. # Custom path
  465. /path/to/your/projects:/root/.claude/projects:ro
  466. ```
  467. #### Docker Commands
  468. ```bash
  469. # Build image manually
  470. docker build -t claudex:latest .
  471. # Run container manually
  472. docker run -d \
  473. -p 3400:3400 \
  474. -v ~/.claude/projects:/root/.claude/projects:ro \
  475. -v claudex-data:/app/data \
  476. --name claudex-web \
  477. claudex:latest
  478. # Check health
  479. docker ps # Check STATUS column for "healthy"
  480. # View logs
  481. docker logs claudex-web -f
  482. # Stop and remove
  483. docker stop claudex-web && docker rm claudex-web
  484. ```
  485. #### Docker Features
  486. - **Multi-stage build**: Optimized image size (~200MB)
  487. - **Non-root user**: Runs as nodejs user for security
  488. - **Health checks**: Automatic health monitoring
  489. - **Persistent volumes**: Stores search index and logs
  490. - **Read-only mounts**: Claude projects mounted read-only for safety
  491. - **Log rotation**: JSON logs with 10MB max size, 3 file rotation
  492. #### Docker Environment Variables
  493. ```bash
  494. # Override in docker-compose.yml or docker run
  495. -e PORT=3400 # Server port
  496. -e HOST=0.0.0.0 # Bind address
  497. -e NODE_ENV=production # Environment
  498. -e PROJECT_ROOT=/root/.claude/projects # Claude projects path
  499. ```
  500. ### Manual Production Build
  501. For non-Docker deployments:
  502. ```bash
  503. # 1. Install dependencies
  504. npm run install-deps
  505. # 2. Build client
  506. npm run build
  507. # 3. Start server (serves built client)
  508. cd server && NODE_ENV=production npm start
  509. ```
  510. Access at: http://localhost:3400
  511. ## 📋 Roadmap
  512. - [x] SQLite FTS5 full-text search
  513. - [x] Universal template support (V1/V2/V3)
  514. - [x] Export to JSON/HTML/TXT
  515. - [x] Docker deployment (v1.1.0)
  516. - [x] Conversation analytics dashboard (v1.1.0)
  517. - [x] Theming system — 10 themes, 29 fonts (v1.2.0)
  518. - [x] Session favorites/bookmarking (v1.2.4)
  519. - [x] MCP server for Claude Code (v1.3.0)
  520. - [x] Structured memory system (v1.3.0)
  521. - [ ] Token cost calculator
  522. - [ ] WebSocket live updates
  523. - [ ] Plugin system for custom parsers
  524. ---
  525. ## 📄 License
  526. MIT License - see LICENSE file for details.
  527. ## 🤝 Contributing
  528. 1. Fork the repository
  529. 2. Create a feature branch: `git checkout -b feature/amazing-feature`
  530. 3. Commit changes: `git commit -m 'Add amazing feature'`
  531. 4. Push to branch: `git push origin feature/amazing-feature`
  532. 5. Open a Pull Request
  533. ## 📚 Additional Documentation
  534. - [SETUP.md](SETUP.md) - Detailed setup and configuration guide
  535. - [INSTALL.md](INSTALL.md) - Legacy installation instructions
  536. ## 💡 Tips
  537. - Use the search page to find conversations across all projects
  538. - Export conversations to share with team members
  539. - Rebuild search index after adding new conversations
  540. - Check `/api/health` endpoint to verify system status
  541. - Use `npm run dev` for the best development experience with hot reload

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.