# 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.

- **Type:** MCP server
- **Install:** `agentstack add mcp-kunwar-shah-claudex`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [kunwar-shah](https://agentstack.voostack.com/s/kunwar-shah)
- **Installs:** 0
- **Category:** [Databases](https://agentstack.voostack.com/c/databases)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [kunwar-shah](https://github.com/kunwar-shah)
- **Source:** https://github.com/kunwar-shah/claudex
- **Website:** https://kunwar-shah.github.io/claudex/

## Install

```sh
agentstack add mcp-kunwar-shah-claudex
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Claudex

  **Professional conversation viewer and analysis tool for Claude Code**

  > **Category**: Development Tools · Conversation Analysis · Usage Monitoring

  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.

  [](https://github.com/kunwar-shah/claudex/releases)
  [](https://github.com/kunwar-shah/claudex/blob/main/LICENSE)
  [](https://kunwar-shah.github.io/claudex/)
  [](https://github.com/kunwar-shah/claudex/discussions)
  [](https://github.com/hesreallyhim/awesome-claude-code)

  **📚 [Documentation](https://kunwar-shah.github.io/claudex/)** | **💬 [Discussions](https://github.com/kunwar-shah/claudex/discussions)** | **🐛 [Issues](https://github.com/kunwar-shah/claudex/issues)**

  

---

## 🆕 What's New

### Version 1.3.0 (February 12, 2026) — MCP Server
- **🧠 MCP Server**: Model Context Protocol server gives Claude Code persistent memory across sessions
- **🔧 10 MCP Tools**: Project context, session search, conversation retrieval, structured memory CRUD
- **💾 Structured Memory System**: Store coding knowledge (conventions, architecture, decisions, error patterns) with priority, confidence, and TTL
- **📋 3 MCP Prompts**: `/recall`, `/catchup`, `/history` for quick access to past sessions
- **🎯 Token Budgeting**: Three detail levels (minimal/standard/full) for context management
- **📖 One-Command Setup**: `claude mcp add --transport stdio claudex -- claudex-mcp`

Previous releases

### Version 1.2.0 (November 11, 2025)
- **🎨 Comprehensive Theming System**: 10 professional themes (default, emerald, green, blue, purple, orange, red, rose, yellow, classic)
- **🔤 Advanced Typography**: 29 font families with visual preview
- **📏 Granular Font Sizing**: 5 precise font size options (14px-18px)
- **💾 Settings Persistence**: All customizations saved to localStorage

### Version 1.1.0 (October 27, 2025)
- **🎯 Smart Title Extraction**: Meaningful session titles from conversation content
- **📊 Tremor Analytics Dashboard**: Tailwind-based charts and multi-scale visualizations
- **🐳 Docker Multi-Platform**: amd64 and arm64 with optimized ~200MB images
- **⚡ Performance**: 121x faster async search index rebuild

[View full changelog](https://kunwar-shah.github.io/claudex/#/changelog) | [Troubleshooting guide](https://kunwar-shah.github.io/claudex/#/troubleshooting)

---

## 📸 Screenshots

### 🎨 NEW in v1.2.0: Theming & Customization

  
    
      
      10 Professional ThemesClassic, Emerald, Blue, Purple, Orange, Red, Rose, Yellow, Green, Default
    
    
      
      29 Font FamiliesVisual preview showing actual typefaces
    
  
  
    
      
      Granular Font Sizing5 precise options (14px-18px) + border radius control
    
    
      
      Settings ModalAppearance functional, more settings coming soon
    
  

### Conversation View

### Full-Text Search

## ✨ Features

- **MCP Server**: Give Claude Code persistent memory — conventions, architecture, decisions, and error patterns survive across sessions
- **Structured Memory**: Store and recall coding knowledge with priority (1-10), confidence, and TTL-based expiration
- **Auto Project Discovery**: Automatically scans `~/.claude/projects` directory to discover all conversations across multiple projects
- **Full-Text Search**: Enterprise-grade SQLite FTS5 search engine with advanced filtering by project, session, role, date range, and content highlighting
- **Universal Template Support**: Intelligent template detection and parsing for all Claude Code versions (V1.x, V2-mixed, V2.0+) with automatic format detection
- **Smart Content Rendering**: Syntax-highlighted code blocks, markdown rendering, diff visualization, JSON formatting, and tool usage tracking
- **Session Analytics**: Comprehensive analytics dashboard with message distribution charts, file operation tracking, and conversation statistics using Tremor React
- **Export Options**: Export conversations to JSON (structured data), HTML (readable format), or plain TXT for archival and sharing
- **Modern UI**: Responsive React interface with 10 themes, 29 fonts, session favorites, and optimized for developer workflows

---

## 💖 Support This Project

Claudex is free and open source. If it saves you time and improves your workflow, please consider:

- ⭐ **Star the repo** - Help others discover Claudex
- 🐛 **Report bugs** - Your feedback makes us better
- 💡 **Share ideas** - Request features in [Discussions](https://github.com/kunwar-shah/claudex/discussions)
- ☕ **Buy me a coffee** - Support continued development

  [](https://ko-fi.com/kunwarshah)
  [](https://paypal.me/kunwarJhamat)
  

  **Every contribution helps keep this project alive and growing!** 🚀

---

## 🚀 Quick Start

### Prerequisites

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

### Installation

#### Option 1: npm (Recommended)

```bash
# 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):

```bash
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 `: Custom server port (default: 3400)
- `--project-root `: 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**:
```bash
git clone https://github.com/kunwar-shah/claudex.git
cd claudex
```

2. **Run system check** (optional but recommended):
```bash
npm run check
```
This validates your environment and catches common setup issues.

3. **Install dependencies** (or use auto-fix):
```bash
# 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):
```bash
cd server
cp .env.example .env
# Edit .env if needed (default: PROJECT_ROOT=~/.claude/projects)
cd ..
```

5. **Start the application**:
```bash
# 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:

```bash
# 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:

```bash
./install.sh

# Then run from anywhere:
claudex
```

## 🔧 Configuration

### Server Configuration (`.env`)

```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
```

### Default Ports

- **Frontend**: http://localhost:3000 (Vite dev server)
- **Backend**: http://localhost:3400 (Fastify API)
- **Frontend build**: Uses port 3400 (served by backend in production)

## 📂 Project Structure

```
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)
```

## 🎯 Supported Claude Code Formats

The viewer automatically detects and parses all Claude Code conversation formats:

### V3 Template (Universal - Recommended)
- **Claude Code v2.0+**: New format with `role` field directly
- **Claude Code v1.x**: Original format with `type` field
- **Edge cases**: Mixed formats and migration states
- **New message types**: `file-history-snapshot` support
- **Role mapping**: All system messages → assistant (binary user/assistant classification)

### Legacy Templates (Auto-detected)
- **V2-Mixed**: Transition format between V1 and V2
- **V1**: Original Claude Code format

The template detector uses a waterfall detection strategy, automatically selecting the best parser for your conversation files.

## 🔍 Search System

### Building the Search Index

The search index needs to be built before searching:

```bash
# 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)
```

### When to Rebuild Index

Rebuild the search index when:
- First time setup
- After template changes
- When new conversations are added
- If search results seem outdated

### Search API Examples

```bash
# 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 Endpoints

### Projects & Sessions
| Endpoint | Method | Description |
|----------|--------|-------------|
| `/api/projects` | GET | List all projects |
| `/api/projects/:id/sessions` | GET | Get sessions for project |
| `/api/projects/:id/sessions/:sessionId` | GET | Get full session with messages |

### Search
| Endpoint | Method | Description |
|----------|--------|-------------|
| `/api/search` | POST | Search conversations (FTS5) |
| `/api/search/index/build` | POST | Build/rebuild search index |
| `/api/search/index/status` | GET | Get index statistics |
| `/api/search/index/clear` | POST | Clear search index |

### Export
| Endpoint | Method | Description |
|----------|--------|-------------|
| `/api/export/session/:projectId/:sessionId?format=json` | GET | Export as JSON |
| `/api/export/session/:projectId/:sessionId?format=html` | GET | Export as HTML |
| `/api/export/session/:projectId/:sessionId?format=txt` | GET | Export as TXT |

### Health
| Endpoint | Method | Description |
|----------|--------|-------------|
| `/api/health` | GET | Health check + system info |

## 🛠️ Development

### Development Mode

```bash
# 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
```

### Testing the Search System

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

This script will:
1. Check server health
2. Get index status
3. Build/rebuild index
4. Run test searches with various filters
5. Display results

### Adding New Templates

1. **Update Template Detector** (`server/src/parsers/templateDetector.js`):
```javascript
'my-template': {
  name: 'My Template Name',
  detect: (samples) => {
    return samples.some(s => s.myUniqueField !== undefined);
  },
  parser: 'my-template'
}
```

2. **Add Parser Method** (`server/src/parsers/messageParser.js`):
```javascript
parseMyTemplate(rawMessage) {
  return {
    id: rawMessage.id || this.generateId(),
    role: rawMessage.myRole === 'user' ? 'user' : 'assistant',
    content: rawMessage.myContent || '',
    timestamp: rawMessage.myTimestamp,
    // ... other fields
  };
}
```

3. **Rebuild Search Index**: The new template will be automatically detected and used.

## 📝 Scripts Reference

### Claudex Directory
- `npm run dev` - Run frontend + backend concurrently (with pre-check)
- `npm start` - Run frontend + backend (production mode)
- `npm run check` - Run system health check
- `npm run check:verbose` - Run detailed system check
- `npm run check:fix` - Auto-fix common setup issues
- `npm run check:json` - JSON output for CI/CD
- `./install.sh` - Install as global CLI command
- `./test-search.sh` - Test search API endpoints

### Server Directory
- `npm run dev` - Run with nodemon (auto-restart)
- `npm start` - Run in production mode

### Client Directory
- `npm run dev` - Vite dev server (http://localhost:3000)
- `npm run build` - Build for production
- `npm run preview` - Preview production build

## 🐛 Troubleshooting

### Quick Diagnosis

Run the system checker first to identify issues:
```bash
npm run check:verbose
```

This will check all common problems and provide actionable suggestions.

### Common Issues

#### "No messages found" Despite Messages Existing
**Fixed in v1.1.1** - If you see intermittent empty sessions or duplicate key warnings:
```bash
# 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
```
See [detailed troubleshooting guide](https://kunwar-shah.github.io/claudex/#/troubleshooting) for more information.

#### No Projects Found
```bash
# Check what the system sees
npm run check

# Verify path
cat server/.env | grep PROJECT_ROOT
```
- Verify `PROJECT_ROOT` in `.env` points to

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [kunwar-shah](https://github.com/kunwar-shah)
- **Source:** [kunwar-shah/claudex](https://github.com/kunwar-shah/claudex)
- **License:** MIT
- **Homepage:** https://kunwar-shah.github.io/claudex/

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-kunwar-shah-claudex
- Seller: https://agentstack.voostack.com/s/kunwar-shah
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.