{"id":31528410,"url":"https://github.com/kunwar-shah/claudex","last_synced_at":"2026-04-07T21:31:50.208Z","repository":{"id":317820723,"uuid":"1068967326","full_name":"kunwar-shah/claudex","owner":"kunwar-shah","description":"Claudex - A friendly viewer, Browse and explore your Claude conversations.","archived":false,"fork":false,"pushed_at":"2026-02-11T13:23:13.000Z","size":6845,"stargazers_count":43,"open_issues_count":0,"forks_count":5,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-11T17:48:55.723Z","etag":null,"topics":["claude-ai","claude-code","conversation-viewer","fastify","full-text-search","jsonl-parser","markdown-renderer","nodejs","react","sqlite"],"latest_commit_sha":null,"homepage":"https://kunwar-shah.github.io/claudex/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kunwar-shah.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"docs/contributing.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"ko_fi":"kunwarshah","custom":["https://paypal.me/kunwarJhamat"]}},"created_at":"2025-10-03T07:36:39.000Z","updated_at":"2026-02-11T13:23:11.000Z","dependencies_parsed_at":null,"dependency_job_id":"8fdbfe6b-f4a7-4a20-a062-9fce9eef4c49","html_url":"https://github.com/kunwar-shah/claudex","commit_stats":null,"previous_names":["kunwar-shah/claudex"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/kunwar-shah/claudex","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kunwar-shah%2Fclaudex","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kunwar-shah%2Fclaudex/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kunwar-shah%2Fclaudex/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kunwar-shah%2Fclaudex/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kunwar-shah","download_url":"https://codeload.github.com/kunwar-shah/claudex/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kunwar-shah%2Fclaudex/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31530641,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-07T16:28:08.000Z","status":"ssl_error","status_checked_at":"2026-04-07T16:28:06.951Z","response_time":105,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["claude-ai","claude-code","conversation-viewer","fastify","full-text-search","jsonl-parser","markdown-renderer","nodejs","react","sqlite"],"created_at":"2025-10-03T23:40:14.289Z","updated_at":"2026-04-07T21:31:50.198Z","avatar_url":"https://github.com/kunwar-shah.png","language":"JavaScript","funding_links":["https://ko-fi.com/kunwarshah","https://paypal.me/kunwarJhamat","https://github.com/sponsors/kunwar-shah"],"categories":["Tooling 🧰","Data \u0026 Analytics"],"sub_categories":["Usage Monitors"],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"docs/logo-sm.png\" alt=\"Claudex Logo\" width=\"180\"\u003e\n\n  # Claudex\n\n  **Professional conversation viewer and analysis tool for Claude Code**\n\n  \u003e **Category**: Development Tools · Conversation Analysis · Usage Monitoring\n\n  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.\n\n  [![Version](https://img.shields.io/github/v/release/kunwar-shah/claudex)](https://github.com/kunwar-shah/claudex/releases)\n  [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/kunwar-shah/claudex/blob/main/LICENSE)\n  [![Documentation](https://img.shields.io/badge/docs-github--pages-blue)](https://kunwar-shah.github.io/claudex/)\n  [![Discussions](https://img.shields.io/github/discussions/kunwar-shah/claudex)](https://github.com/kunwar-shah/claudex/discussions)\n  [![Mentioned in Awesome Claude Code](https://awesome.re/mentioned-badge.svg)](https://github.com/hesreallyhim/awesome-claude-code)\n\n  **📚 [Documentation](https://kunwar-shah.github.io/claudex/)** | **💬 [Discussions](https://github.com/kunwar-shah/claudex/discussions)** | **🐛 [Issues](https://github.com/kunwar-shah/claudex/issues)**\n\n\u003c/div\u003e\n\n---\n\n## 🆕 What's New\n\n### Version 1.3.0 (February 12, 2026) — MCP Server\n- **🧠 MCP Server**: Model Context Protocol server gives Claude Code persistent memory across sessions\n- **🔧 10 MCP Tools**: Project context, session search, conversation retrieval, structured memory CRUD\n- **💾 Structured Memory System**: Store coding knowledge (conventions, architecture, decisions, error patterns) with priority, confidence, and TTL\n- **📋 3 MCP Prompts**: `/recall`, `/catchup`, `/history` for quick access to past sessions\n- **🎯 Token Budgeting**: Three detail levels (minimal/standard/full) for context management\n- **📖 One-Command Setup**: `claude mcp add --transport stdio claudex -- claudex-mcp`\n\n\u003cdetails\u003e\n\u003csummary\u003ePrevious releases\u003c/summary\u003e\n\n### Version 1.2.0 (November 11, 2025)\n- **🎨 Comprehensive Theming System**: 10 professional themes (default, emerald, green, blue, purple, orange, red, rose, yellow, classic)\n- **🔤 Advanced Typography**: 29 font families with visual preview\n- **📏 Granular Font Sizing**: 5 precise font size options (14px-18px)\n- **💾 Settings Persistence**: All customizations saved to localStorage\n\n### Version 1.1.0 (October 27, 2025)\n- **🎯 Smart Title Extraction**: Meaningful session titles from conversation content\n- **📊 Tremor Analytics Dashboard**: Tailwind-based charts and multi-scale visualizations\n- **🐳 Docker Multi-Platform**: amd64 and arm64 with optimized ~200MB images\n- **⚡ Performance**: 121x faster async search index rebuild\n\n\u003c/details\u003e\n\n[View full changelog](https://kunwar-shah.github.io/claudex/#/changelog) | [Troubleshooting guide](https://kunwar-shah.github.io/claudex/#/troubleshooting)\n\n---\n\n## 📸 Screenshots\n\n### 🎨 NEW in v1.2.0: Theming \u0026 Customization\n\n\u003ctable\u003e\n  \u003ctr\u003e\n    \u003ctd width=\"50%\"\u003e\n      \u003cimg src=\"screenshots/v1.2.0/01-theme-selector.png\" alt=\"10 Professional Themes\" width=\"100%\"\u003e\n      \u003cp align=\"center\"\u003e\u003cstrong\u003e10 Professional Themes\u003c/strong\u003e\u003cbr/\u003eClassic, Emerald, Blue, Purple, Orange, Red, Rose, Yellow, Green, Default\u003c/p\u003e\n    \u003c/td\u003e\n    \u003ctd width=\"50%\"\u003e\n      \u003cimg src=\"screenshots/v1.2.0/02-font-family-preview.png\" alt=\"29 Font Families\" width=\"100%\"\u003e\n      \u003cp align=\"center\"\u003e\u003cstrong\u003e29 Font Families\u003c/strong\u003e\u003cbr/\u003eVisual preview showing actual typefaces\u003c/p\u003e\n    \u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd width=\"50%\"\u003e\n      \u003cimg src=\"screenshots/v1.2.0/03-font-size-border-radius.png\" alt=\"Font Size \u0026 Border Radius\" width=\"100%\"\u003e\n      \u003cp align=\"center\"\u003e\u003cstrong\u003eGranular Font Sizing\u003c/strong\u003e\u003cbr/\u003e5 precise options (14px-18px) + border radius control\u003c/p\u003e\n    \u003c/td\u003e\n    \u003ctd width=\"50%\"\u003e\n      \u003cimg src=\"screenshots/v1.2.0/04-settings-tabs-soon-badges.png\" alt=\"Settings Modal\" width=\"100%\"\u003e\n      \u003cp align=\"center\"\u003e\u003cstrong\u003eSettings Modal\u003c/strong\u003e\u003cbr/\u003eAppearance functional, more settings coming soon\u003c/p\u003e\n    \u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\n### Conversation View\n\u003cimg src=\"screenshots/conversation-view.png\" alt=\"Conversation View\" width=\"800\"\u003e\n\n### Full-Text Search\n\u003cimg src=\"screenshots/search-results.png\" alt=\"Search Results\" width=\"800\"\u003e\n\n## ✨ Features\n\n- **MCP Server**: Give Claude Code persistent memory — conventions, architecture, decisions, and error patterns survive across sessions\n- **Structured Memory**: Store and recall coding knowledge with priority (1-10), confidence, and TTL-based expiration\n- **Auto Project Discovery**: Automatically scans `~/.claude/projects` directory to discover all conversations across multiple projects\n- **Full-Text Search**: Enterprise-grade SQLite FTS5 search engine with advanced filtering by project, session, role, date range, and content highlighting\n- **Universal Template Support**: Intelligent template detection and parsing for all Claude Code versions (V1.x, V2-mixed, V2.0+) with automatic format detection\n- **Smart Content Rendering**: Syntax-highlighted code blocks, markdown rendering, diff visualization, JSON formatting, and tool usage tracking\n- **Session Analytics**: Comprehensive analytics dashboard with message distribution charts, file operation tracking, and conversation statistics using Tremor React\n- **Export Options**: Export conversations to JSON (structured data), HTML (readable format), or plain TXT for archival and sharing\n- **Modern UI**: Responsive React interface with 10 themes, 29 fonts, session favorites, and optimized for developer workflows\n\n---\n\n## 💖 Support This Project\n\nClaudex is free and open source. If it saves you time and improves your workflow, please consider:\n\n- ⭐ **Star the repo** - Help others discover Claudex\n- 🐛 **Report bugs** - Your feedback makes us better\n- 💡 **Share ideas** - Request features in [Discussions](https://github.com/kunwar-shah/claudex/discussions)\n- ☕ **Buy me a coffee** - Support continued development\n\n\u003cdiv align=\"center\"\u003e\n\n  [![Ko-fi](https://img.shields.io/badge/Ko--fi-Buy%20me%20a%20coffee-FF5E5B?logo=ko-fi\u0026style=for-the-badge)](https://ko-fi.com/kunwarshah)\n  [![PayPal](https://img.shields.io/badge/PayPal-Donate-00457C?logo=paypal\u0026style=for-the-badge)](https://paypal.me/kunwarJhamat)\n  \u003c!-- [![GitHub Sponsors](https://img.shields.io/badge/Sponsor-GitHub-ea4aaa?logo=github\u0026style=for-the-badge)](https://github.com/sponsors/kunwar-shah) --\u003e\n\n  **Every contribution helps keep this project alive and growing!** 🚀\n\n\u003c/div\u003e\n\n---\n\n## 🚀 Quick Start\n\n### Prerequisites\n\n- Node.js 18+ and npm\n- Claude Code installed with conversation history in `~/.claude/projects`\n\n### Installation\n\n#### Option 1: npm (Recommended)\n\n```bash\n# Global installation\nnpm install -g @kunwarshah/claudex [https://www.npmjs.com/package/@kunwarshah/claudex]\n\n# Then run anywhere:\nclaudex\n\n# Custom port (if 3400 is in use):\nclaudex --port 3500\n\n# Custom project directory:\nclaudex --project-root ~/my-claude-projects\n\n# Or use without installing (npx):\nnpx @kunwarshah/claudex\n```\n\n**Add MCP Server** (gives Claude Code persistent memory):\n\n```bash\nclaude mcp add --transport stdio claudex -- claudex-mcp\n```\n\nSee the [MCP Server Guide](https://kunwar-shah.github.io/claudex/#/mcp) for details.\n\n**CLI Options**:\n- `--help, -h`: Show help message\n- `--version, -v`: Show version\n- `--port, -p \u003cport\u003e`: Custom server port (default: 3400)\n- `--project-root \u003cpath\u003e`: Custom Claude projects directory\n\n**Environment Variables**:\n- `PORT`: Server port (default: 3400)\n- `PROJECT_ROOT`: Claude projects directory (default: ~/.claude/projects)\n\n#### Option 2: From Source\n\n1. **Clone the repository**:\n```bash\ngit clone https://github.com/kunwar-shah/claudex.git\ncd claudex\n```\n\n2. **Run system check** (optional but recommended):\n```bash\nnpm run check\n```\nThis validates your environment and catches common setup issues.\n\n3. **Install dependencies** (or use auto-fix):\n```bash\n# Option 1: Manual installation\nnpm install\ncd server \u0026\u0026 npm install \u0026\u0026 cd ..\ncd client \u0026\u0026 npm install \u0026\u0026 cd ..\n\n# Option 2: Auto-fix (installs deps + creates .env)\nnpm run check:fix\n```\n\n4. **Configure environment** (if not using auto-fix):\n```bash\ncd server\ncp .env.example .env\n# Edit .env if needed (default: PROJECT_ROOT=~/.claude/projects)\ncd ..\n```\n\n5. **Start the application**:\n```bash\n# Automatically runs system check, then starts servers\nnpm run dev\n```\n\n6. **Open your browser**: http://localhost:3000\n\nThe backend API runs on `http://localhost:3400`\n\n### System Checker\n\nClaudex includes a comprehensive system checker that validates your environment:\n\n```bash\n# Quick check\nnpm run check\n\n# Detailed output\nnpm run check:verbose\n\n# Auto-fix common issues\nnpm run check:fix\n\n# JSON output (for CI/CD)\nnpm run check:json\n```\n\n**What it checks:**\n- ✅ Node.js \u0026 npm versions\n- ✅ PROJECT_ROOT path \u0026 permissions\n- ✅ Port availability (3000, 3400)\n- ✅ Dependencies installation\n- ✅ Claude Code data (projects, sessions)\n- ✅ JSONL file validity\n- ✅ Database permissions\n- ✅ Search index status\n\n### Global CLI Installation (Optional)\n\nInstall globally to use `claudex` command anywhere:\n\n```bash\n./install.sh\n\n# Then run from anywhere:\nclaudex\n```\n\n## 🔧 Configuration\n\n### Server Configuration (`.env`)\n\n```env\n# Path to Claude Code projects directory\n# Supports ~ expansion (e.g., ~/.claude/projects)\nPROJECT_ROOT=~/.claude/projects\n\n# Server port\nPORT=3400\n\n# Environment\nNODE_ENV=development\n```\n\n### Default Ports\n\n- **Frontend**: http://localhost:3000 (Vite dev server)\n- **Backend**: http://localhost:3400 (Fastify API)\n- **Frontend build**: Uses port 3400 (served by backend in production)\n\n## 📂 Project Structure\n\n```\nclaudex/\n├── server/                    # Backend (Node.js + Fastify)\n│   ├── src/\n│   │   ├── parsers/          # Template detection \u0026 message parsing\n│   │   │   ├── templateDetector.js    # V1/V2/V3 template detection\n│   │   │   └── messageParser.js       # Universal message parser\n│   │   ├── services/         # Core business logic\n│   │   │   ├── fileScanner.js        # Project/session discovery\n│   │   │   ├── sessionParser.js      # Full session parsing\n│   │   │   ├── searchDatabase.js     # SQLite FTS5 search\n│   │   │   ├── searchIndexer.js      # Search index builder\n│   │   │   └── memoryService.js      # Structured memory CRUD\n│   │   ├── mcp/              # MCP server (Claude Code integration)\n│   │   │   ├── index.js              # MCP entry point + stdio transport\n│   │   │   ├── tools.js              # 10 MCP tool handlers\n│   │   │   ├── resources.js          # MCP resources\n│   │   │   └── prompts.js            # 3 MCP prompts\n│   │   ├── routes/           # API endpoints\n│   │   │   ├── projects.js           # Project/session routes\n│   │   │   ├── search.js             # Search routes\n│   │   │   └── export.js             # Export routes\n│   │   ├── utils/            # Helper utilities\n│   │   │   └── pathHelper.js         # Path expansion (~/ support)\n│   │   └── server.js         # Main server\n│   ├── data/                 # SQLite database (auto-created)\n│   ├── .env.example          # Environment template\n│   └── package.json\n├── client/                   # Frontend (React + Vite)\n│   ├── src/\n│   │   ├── components/       # React components\n│   │   │   ├── ProjectSelector.jsx\n│   │   │   ├── SessionList.jsx\n│   │   │   ├── ConversationThread.jsx\n│   │   │   ├── MessageBubble.jsx\n│   │   │   ├── ClaudeMessageRenderer.jsx\n│   │   │   └── SearchPage.jsx\n│   │   ├── services/         # API client\n│   │   │   └── api.js\n│   │   └── App.jsx           # Main app\n│   └── package.json\n├── bin/                      # CLI entry point\n├── test-search.sh           # Search API testing script\n├── install.sh               # Global CLI installer\n├── SETUP.md                 # Detailed setup guide\n├── README.md                # This file\n└── package.json             # Root package (CLI + concurrently)\n```\n\n## 🎯 Supported Claude Code Formats\n\nThe viewer automatically detects and parses all Claude Code conversation formats:\n\n### V3 Template (Universal - Recommended)\n- **Claude Code v2.0+**: New format with `role` field directly\n- **Claude Code v1.x**: Original format with `type` field\n- **Edge cases**: Mixed formats and migration states\n- **New message types**: `file-history-snapshot` support\n- **Role mapping**: All system messages → assistant (binary user/assistant classification)\n\n### Legacy Templates (Auto-detected)\n- **V2-Mixed**: Transition format between V1 and V2\n- **V1**: Original Claude Code format\n\nThe template detector uses a waterfall detection strategy, automatically selecting the best parser for your conversation files.\n\n## 🔍 Search System\n\n### Building the Search Index\n\nThe search index needs to be built before searching:\n\n```bash\n# Option 1: Via API\ncurl -X POST http://localhost:3400/api/search/index/build\n\n# Option 2: Via test script\n./test-search.sh\n\n# Option 3: Via UI (Search page → \"Rebuild Index\" button)\n```\n\n### When to Rebuild Index\n\nRebuild the search index when:\n- First time setup\n- After template changes\n- When new conversations are added\n- If search results seem outdated\n\n### Search API Examples\n\n```bash\n# Basic search\ncurl -X POST http://localhost:3400/api/search \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"q\": \"migration\", \"limit\": 10}'\n\n# Search with filters\ncurl -X POST http://localhost:3400/api/search \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"q\": \"database\",\n    \"projectId\": \"my-project\",\n    \"role\": \"user\",\n    \"limit\": 20,\n    \"offset\": 0\n  }'\n\n# Check index status\ncurl http://localhost:3400/api/search/index/status\n```\n\n## 📡 API Endpoints\n\n### Projects \u0026 Sessions\n| Endpoint | Method | Description |\n|----------|--------|-------------|\n| `/api/projects` | GET | List all projects |\n| `/api/projects/:id/sessions` | GET | Get sessions for project |\n| `/api/projects/:id/sessions/:sessionId` | GET | Get full session with messages |\n\n### Search\n| Endpoint | Method | Description |\n|----------|--------|-------------|\n| `/api/search` | POST | Search conversations (FTS5) |\n| `/api/search/index/build` | POST | Build/rebuild search index |\n| `/api/search/index/status` | GET | Get index statistics |\n| `/api/search/index/clear` | POST | Clear search index |\n\n### Export\n| Endpoint | Method | Description |\n|----------|--------|-------------|\n| `/api/export/session/:projectId/:sessionId?format=json` | GET | Export as JSON |\n| `/api/export/session/:projectId/:sessionId?format=html` | GET | Export as HTML |\n| `/api/export/session/:projectId/:sessionId?format=txt` | GET | Export as TXT |\n\n### Health\n| Endpoint | Method | Description |\n|----------|--------|-------------|\n| `/api/health` | GET | Health check + system info |\n\n## 🛠️ Development\n\n### Development Mode\n\n```bash\n# Run both frontend + backend with hot reload\nnpm run dev\n\n# Or run separately:\n# Terminal 1 - Backend (auto-restarts on changes)\ncd server \u0026\u0026 npm run dev\n\n# Terminal 2 - Frontend (hot module replacement)\ncd client \u0026\u0026 npm run dev\n```\n\n### Testing the Search System\n\n```bash\n# Run comprehensive search tests\n./test-search.sh\n```\n\nThis script will:\n1. Check server health\n2. Get index status\n3. Build/rebuild index\n4. Run test searches with various filters\n5. Display results\n\n### Adding New Templates\n\n1. **Update Template Detector** (`server/src/parsers/templateDetector.js`):\n```javascript\n'my-template': {\n  name: 'My Template Name',\n  detect: (samples) =\u003e {\n    return samples.some(s =\u003e s.myUniqueField !== undefined);\n  },\n  parser: 'my-template'\n}\n```\n\n2. **Add Parser Method** (`server/src/parsers/messageParser.js`):\n```javascript\nparseMyTemplate(rawMessage) {\n  return {\n    id: rawMessage.id || this.generateId(),\n    role: rawMessage.myRole === 'user' ? 'user' : 'assistant',\n    content: rawMessage.myContent || '',\n    timestamp: rawMessage.myTimestamp,\n    // ... other fields\n  };\n}\n```\n\n3. **Rebuild Search Index**: The new template will be automatically detected and used.\n\n## 📝 Scripts Reference\n\n### Claudex Directory\n- `npm run dev` - Run frontend + backend concurrently (with pre-check)\n- `npm start` - Run frontend + backend (production mode)\n- `npm run check` - Run system health check\n- `npm run check:verbose` - Run detailed system check\n- `npm run check:fix` - Auto-fix common setup issues\n- `npm run check:json` - JSON output for CI/CD\n- `./install.sh` - Install as global CLI command\n- `./test-search.sh` - Test search API endpoints\n\n### Server Directory\n- `npm run dev` - Run with nodemon (auto-restart)\n- `npm start` - Run in production mode\n\n### Client Directory\n- `npm run dev` - Vite dev server (http://localhost:3000)\n- `npm run build` - Build for production\n- `npm run preview` - Preview production build\n\n## 🐛 Troubleshooting\n\n### Quick Diagnosis\n\nRun the system checker first to identify issues:\n```bash\nnpm run check:verbose\n```\n\nThis will check all common problems and provide actionable suggestions.\n\n### Common Issues\n\n#### \"No messages found\" Despite Messages Existing\n**Fixed in v1.1.1** - If you see intermittent empty sessions or duplicate key warnings:\n```bash\n# Update to latest version\ncd claude-viewer\ngit pull origin main\nnpm install \u0026\u0026 cd server \u0026\u0026 npm install \u0026\u0026 cd ../client \u0026\u0026 npm install \u0026\u0026 cd ..\nnpm run dev\n```\nSee [detailed troubleshooting guide](https://kunwar-shah.github.io/claudex/#/troubleshooting) for more information.\n\n#### No Projects Found\n```bash\n# Check what the system sees\nnpm run check\n\n# Verify path\ncat server/.env | grep PROJECT_ROOT\n```\n- Verify `PROJECT_ROOT` in `.env` points to `~/.claude/projects`\n- Check that Claude Code has created conversation files\n- Run `npm run check:fix` to auto-create missing directories\n\n#### Search Not Working\n```bash\n# Quick fix via UI\n# Visit http://localhost:3000/search → Click \"Rebuild Index\"\n\n# Or via command line\ncurl -X POST http://localhost:3400/api/search/index/build\n```\n\n#### Port Conflicts\n```bash\n# System checker will detect port conflicts\nnpm run check\n\n# Auto-detected ports in use show PID\n# Kill process: kill \u003cPID\u003e\n# Or change PORT in server/.env\n```\n\n#### Permission Errors\n```bash\n# Check permissions\nnpm run check:verbose\n\n# Fix permissions\nchmod +r ~/.claude/projects\nchmod +w claude-viewer/server/data\n```\n\n#### Dependencies Issues\n```bash\n# Auto-install all dependencies\nnpm run check:fix\n```\n\n## 🚢 Production Deployment\n\n### Using Docker (Recommended)\n\nClaudex includes production-ready Docker configuration with multi-stage builds for optimal image size.\n\n#### Quick Start with Docker\n\n```bash\n# Build and start with docker-compose\ndocker-compose up -d\n\n# View logs\ndocker-compose logs -f\n\n# Stop\ndocker-compose down\n```\n\nAccess at: http://localhost:3400\n\n#### Docker Configuration\n\nThe default `docker-compose.yml` mounts your Claude projects directory as read-only:\n\n```yaml\nvolumes:\n  # Adjust path to match your system\n  - ~/.claude/projects:/root/.claude/projects:ro\n```\n\n**Common path configurations:**\n\n```bash\n# Linux/macOS\n~/.claude/projects:/root/.claude/projects:ro\n\n# Windows (WSL2)\n/mnt/c/Users/YourName/.claude/projects:/root/.claude/projects:ro\n\n# Custom path\n/path/to/your/projects:/root/.claude/projects:ro\n```\n\n#### Docker Commands\n\n```bash\n# Build image manually\ndocker build -t claudex:latest .\n\n# Run container manually\ndocker run -d \\\n  -p 3400:3400 \\\n  -v ~/.claude/projects:/root/.claude/projects:ro \\\n  -v claudex-data:/app/data \\\n  --name claudex-web \\\n  claudex:latest\n\n# Check health\ndocker ps  # Check STATUS column for \"healthy\"\n\n# View logs\ndocker logs claudex-web -f\n\n# Stop and remove\ndocker stop claudex-web \u0026\u0026 docker rm claudex-web\n```\n\n#### Docker Features\n\n- **Multi-stage build**: Optimized image size (~200MB)\n- **Non-root user**: Runs as nodejs user for security\n- **Health checks**: Automatic health monitoring\n- **Persistent volumes**: Stores search index and logs\n- **Read-only mounts**: Claude projects mounted read-only for safety\n- **Log rotation**: JSON logs with 10MB max size, 3 file rotation\n\n#### Docker Environment Variables\n\n```bash\n# Override in docker-compose.yml or docker run\n-e PORT=3400                           # Server port\n-e HOST=0.0.0.0                        # Bind address\n-e NODE_ENV=production                 # Environment\n-e PROJECT_ROOT=/root/.claude/projects # Claude projects path\n```\n\n### Manual Production Build\n\nFor non-Docker deployments:\n\n```bash\n# 1. Install dependencies\nnpm run install-deps\n\n# 2. Build client\nnpm run build\n\n# 3. Start server (serves built client)\ncd server \u0026\u0026 NODE_ENV=production npm start\n```\n\nAccess at: http://localhost:3400\n\n## 📋 Roadmap\n\n- [x] SQLite FTS5 full-text search\n- [x] Universal template support (V1/V2/V3)\n- [x] Export to JSON/HTML/TXT\n- [x] Docker deployment (v1.1.0)\n- [x] Conversation analytics dashboard (v1.1.0)\n- [x] Theming system — 10 themes, 29 fonts (v1.2.0)\n- [x] Session favorites/bookmarking (v1.2.4)\n- [x] MCP server for Claude Code (v1.3.0)\n- [x] Structured memory system (v1.3.0)\n- [ ] Token cost calculator\n- [ ] WebSocket live updates\n- [ ] Plugin system for custom parsers\n\n---\n\n## 📄 License\n\nMIT License - see LICENSE file for details.\n\n## 🤝 Contributing\n\n1. Fork the repository\n2. Create a feature branch: `git checkout -b feature/amazing-feature`\n3. Commit changes: `git commit -m 'Add amazing feature'`\n4. Push to branch: `git push origin feature/amazing-feature`\n5. Open a Pull Request\n\n## 📚 Additional Documentation\n\n- [SETUP.md](SETUP.md) - Detailed setup and configuration guide\n- [INSTALL.md](INSTALL.md) - Legacy installation instructions\n\n## 💡 Tips\n\n- Use the search page to find conversations across all projects\n- Export conversations to share with team members\n- Rebuild search index after adding new conversations\n- Check `/api/health` endpoint to verify system status\n- Use `npm run dev` for the best development experience with hot reload\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkunwar-shah%2Fclaudex","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkunwar-shah%2Fclaudex","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkunwar-shah%2Fclaudex/lists"}