Claude Viewer

Multi-User Conversation History Viewer for Claude Code

---

🎯 Overview

Claude Viewer is an admin tool web application for visualizing Claude Code conversation history from all Windows/macOS users on a single machine. It provides rich analytics, full conversation details, token usage tracking, and model/tool insights.

MCP Server integration allows Claude Desktop and Claude Code to query conversation data directly!

Demo

https://github.com/user-attachments/assets/1426b08d-6086-439f-9f4b-d95d7cfdac1e

---

✨ Key Features

v0.1 Features

• ✅ MCP Server Integration - Query conversation data directly from Claude Desktop/Code
• ✅ 5 MCP Tools - get_claude_users, get_conversations, get_stats, get_conversation_details, open_dashboard
• ✅ Open Dashboard via MCP - Start server and open browser with a single command
• ✅ Shared Library - Refactored codebase with lib/data-access.js for reuse
• ✅ Configurable Port - Default 2204, configurable via CLAUDE_VIEWER_PORT env
• ✅ Full Conversation Viewer - View complete user/assistant message threads in modal
• ✅ Token Usage Analytics - Track input/output/cache tokens per conversation
• ✅ Model Tracking - See which Claude models are used (Sonnet 4.5, Opus, Haiku)
• ✅ Tool Analytics - Top 10 most-used tools (WebSearch, Bash, Edit, etc.)
• ✅ Enhanced Dashboard - 8 statistical cards
• ✅ Enriched Data Table - 9 columns with messages, tokens, model, tools
• ✅ Dual-Source Architecture - Combines history.jsonl + projects/*.jsonl for rich metadata

Core Features

• 📊 Real-time statistics dashboard
• 🔍 Advanced search and filtering (user, project, date range, text)
• 📈 Daily activity chart (last 30 days)
• ☁️ Keyword cloud (top 20 keywords)
• 📥 CSV export with enriched data
• 🖥️ Multi-user support (scans all system users)
• 🔐 XSS protection with HTML escaping

---

🚀 Quick Start

Installation

# Clone or download this repository
cd claude-viewer

# Install dependencies
npm install

# Start the server
npm start

# Open in browser
open http://localhost:2204

---

⚡ Quick Start Integration Options

Choose your preferred method to launch Claude Viewer with a single command:

1️⃣ Automated Launcher Script (Recommended)

A convenient bash script that starts the server and opens your browser automatically.

Location: start-claude-viewer.sh

What it does:

• Starts the Node.js server in the background
• Waits for server initialization (3 seconds)
• Automatically opens your default browser at http://localhost:2204
• Displays helpful status messages during startup

Usage:

./start-claude-viewer.sh

To stop the server:

# Press Ctrl+C in the terminal, or:
pkill -f 'node.*server.js'

Setup (first time only):

chmod +x start-claude-viewer.sh

---

2️⃣ Global Shell Alias

For terminal power users, create a global alias to launch from anywhere.

Add to your ~/.zshrc (or ~/.bashrc):

alias claude-viewer='~/path/to/claude-viewer/start-claude-viewer.sh'

Replace ~/path/to/claude-viewer/ with your actual project path, for example:

alias claude-viewer='~/Library/Mobile\ Documents/com~apple~CloudDocs/Sviluppo\ AI/MaxTurazzini/claude-viewer/start-claude-viewer.sh'

Usage from anywhere:

claude-viewer

Apply changes:

source ~/.zshrc

---

📋 Summary of Launch Methods

Method	Command	Requires
Direct Script	./start-claude-viewer.sh	None (project directory)
Shell Alias	claude-viewer	.zshrc configuration
Manual	npm start	None

All launch methods provide the same seamless experience: One command → Server starts → Browser opens → View conversations

Tip: The script runs the server in the background, allowing you to continue using your terminal. To view server logs, check server.log or monitor the console output.

---

🔌 MCP Server Integration (v0.1)

Claude Viewer includes an MCP (Model Context Protocol) server that exposes conversation data directly to Claude Desktop and Claude Code.

Running the MCP Server

# Run MCP server (stdio transport)
npm run mcp

# Or directly
node mcp-server.js

Available MCP Tools

Tool	Description	Parameters
get_claude_users	List users with Claude history	-
get_conversations	Get conversations with filters	username?, search?, project?, dateFrom?, dateTo?, limit?, offset?
get_stats	Aggregated usage statistics	-
get_conversation_details	Full transcript of a session	sessionId, username
open_dashboard	Start server and open browser	port? (default: 2204)

Configuration

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "claude-viewer": {
      "command": "node",
      "args": ["/path/to/claude-viewer/mcp-server.js"]
    }
  }
}

Claude Code

Option 1: Via CLI (recommended)

# Global (available in all projects)
claude mcp add claude-viewer -s user -- node "/path/to/claude-viewer/mcp-server.js"

# Per project (current project only)
claude mcp add claude-viewer -s project -- node "/path/to/claude-viewer/mcp-server.js"

Option 2: Configuration file

• Global (~/.claude.json):

{
  "mcpServers": {
    "claude-viewer": {
      "command": "node",
      "args": ["/path/to/claude-viewer/mcp-server.js"]
    }
  }
}

• Per project (.mcp.json in project root):

{
  "mcpServers": {
    "claude-viewer": {
      "command": "node",
      "args": ["/path/to/claude-viewer/mcp-server.js"]
    }
  }
}

Verify configuration:

# List configured MCP servers
claude mcp list

# Remove server
claude mcp remove claude-viewer -s user

Example Requests to Claude

Once configured, you can ask Claude to query your conversation history. Here are some practical examples:

Dashboard & Overview

• "Open the Claude Viewer dashboard"
• "Show me my Claude usage statistics"
• "How many conversations do I have in total?"

User Analysis

• "Which users have Claude conversation history on this machine?"
• "Who is the most active Claude user?"
• "Compare token usage between users"

Conversation Search

• "Show me conversations about MCP from the last week"
• "Find all conversations related to React development"
• "Search for conversations where I discussed database optimization"
• "List conversations from the project /Users/max/myapp"

Token & Cost Analysis

• "What's my total token usage this month?"
• "Which conversations consumed the most tokens?"
• "Show daily token usage for the past 30 days"
• "Calculate my estimated API costs based on token usage"

Model & Tool Insights

• "Which Claude model do I use most frequently?"
• "What tools are most commonly used in my conversations?"
• "Show conversations where I used WebSearch"
• "List all conversations that used the Bash tool"

Conversation Details

• "Get the full transcript of session abc123..."
• "Show me the last conversation I had about authentication"
• "What did Claude suggest for the caching implementation?"

---

📊 Dashboard & Features

8-Card Statistics Dashboard

1. Total Conversations - Count of all conversations
2. Active Users - Number of unique users
3. Most Active User - User with most conversations
4. Most Used Project - Top project by conversation count
5. Total Tokens - Sum of all input/output/cache tokens
6. Total Messages - Count of all user + assistant messages
7. Top Model - Most-used Claude model (e.g., "sonnet-4-5")
8. Top Tool - Most-used tool (e.g., "WebSearch")

9-Column Conversation Table

• Timestamp
• User
• Project
• Prompt (user's first message)
• Msgs - Number of messages in conversation
• Tokens - Formatted token usage (e.g., "12,345")
• Model - Model used (e.g., "sonnet-4-5")
• Tools - Tool count with hover tooltip for names
• Actions (Details button)

Additional Features

• Conversation Modal - Click "💬 Dettagli" to view full user/assistant thread
• Daily Activity Chart - Canvas-based visualization of last 30 days
• Keyword Cloud - Frequency-based sizing (4+ character words only)
• Advanced Filters - Text search, user, project, date range
• CSV Export - Download filtered data with 8 columns

---

🏗️ Architecture

Tech Stack

• Backend: Node.js + Express.js (v4.18.2)
• Frontend: Vanilla JavaScript, HTML5, CSS3 (no frameworks)
• Data Format: JSONL (JSON Lines) from Claude Code history
• Platform: Cross-platform (Windows/macOS/Linux)

Dual-Source Data Architecture

Claude Viewer now combines data from two sources for enriched insights:

Source 1: Quick Conversation List

Path: ~/.claude/history.jsonl (Windows: C:\Users\{USERNAME}\.claude\history.jsonl)

Contains:

• User prompts (display text)
• Timestamps
• Project paths
• Basic metadata

Purpose: Fast scanning for conversation list

Source 2: Full Session Transcripts

Path: ~/.claude/projects/{project}/{session-uuid}.jsonl

Contains:

• Complete message threads (user + assistant)
• Token usage (input/output/cache_creation/cache_read)
• Model information (e.g., "claude-sonnet-4-5-20250929")
• Tool usage (WebSearch, Bash, Edit, Read, etc.)
• Thinking blocks and tool_use content

Purpose: Rich metadata extraction

Data Flow

1. Scan ~/.claude/history.jsonl (all users)
   ↓
2. Parse conversation list with basic metadata
   ↓
3. Match conversations to projects/*.jsonl by timestamp (±5 min tolerance)
   ↓
4. Extract metadata: tokens, model, tools, message count
   ↓
5. Enrich conversation objects with full data
   ↓
6. Serve via REST API endpoints
   ↓
7. Frontend renders dashboard, table, and modal

REST API Endpoints

• GET /api/users - List of users with Claude history
• GET /api/conversations - All conversations with enriched metadata
  • Includes: messageCount, totalTokens, model, toolsUsed[], hasDetails
  • Sorted by timestamp descending (most recent first)
• GET /api/stats - Aggregated statistics
  • Original: totalConversations, totalUsers, userStats, projectStats, dailyStats, topKeywords
  • New: totalTokens, totalMessages, tokensByUser, modelStats, toolStats, dailyTokenStats
• GET /api/conversation/:sessionId/:username - Full conversation transcript
  • Returns complete thread with all messages
  • Used by modal for detailed view

---

🛠️ Configuration

Change Port (Optional)

Default port is 2204. You can change it via environment variable:

# Set custom port
CLAUDE_VIEWER_PORT=3000 npm start

# Or export it
export CLAUDE_VIEWER_PORT=3000
npm start

Data Locations

macOS/Linux:

• History: ~/.claude/history.jsonl
• Sessions: ~/.claude/projects/{project}/{session-uuid}.jsonl

Windows:

• History: C:\Users\{USERNAME}\.claude\history.jsonl
• Sessions: C:\Users\{USERNAME}\.claude\projects\{project}\{session-uuid}.jsonl

---

⚠️ Troubleshooting

No Data Displayed

Symptoms: Empty conversation list, 0 total conversations

Solutions:

1. Verify Claude history files exist:

   # macOS/Linux
   ls ~/.claude/history.jsonl
   
   # Windows
   dir C:\Users\*\.claude\history.jsonl
   

2. Check permissions (may require admin on enterprise PCs):

   # macOS/Linux
   sudo npm start
   
   # Windows (run terminal as Administrator)
   npm start
   

3. Check server logs for errors:

   tail -f server.log
   

---

Dashboard Shows "0" for Tokens/Messages

Cause: ~/.claude/projects directory not accessible or empty

Solutions:

1. Verify session files exist:

   # macOS/Linux
   find ~/.claude/projects -name "*.jsonl"
   
   # Windows
   dir C:\Users\%USERNAME%\.claude\projects /s /b | findstr .jsonl
   

2. Check server console for "Error enriching conversation" messages

3. Graceful Degradation: App still works, showing 0 values but conversation list remains visible

---

Table Missing New Columns (Msgs, Tokens, Model, Tools)

Cause: Browser cached old app.js

Solutions:

1. Hard refresh: Ctrl+Shift+R (Windows/Linux) or Cmd+Shift+R (macOS)
2. Clear browser cache for localhost:2204
3. Try incognito/private browsing mode

---

Port 2204 Already in Use

Symptoms: Error: listen EADDRINUSE: address already in use :::2204

Solutions:

1. Option 1: Kill existing process

   # macOS/Linux
   lsof -ti:2204 | xargs kill
   
   # Windows
   netstat -ano | findstr :2204
   taskkill /F /PID [PID from above]
   

2. Option 2: Use different port via environment variable

   CLAUDE_VIEWER_PORT=3000 npm start
   

---

"Cannot find module 'express'" Error

Cause: Dependencies not installed

Solution:

npm install

---

Modal Shows "Session not found"

Cause: Session file deleted, moved, or corrupted

Solutions:

1. Session may have been cleaned up by Claude Code
2. Conversation still visible in list but full transcript unavailable
3. Check if projects/ directory exists and contains .jsonl files

---

Permission Errors on Enterprise PCs

Cause: Corporate policies restrict access to user directories

Solutions:

1. Run terminal/command prompt as Administrator
2. Contact IT to grant read access to C:\Users\*\.claude\ directories
3. Alternative: Copy history files to accessible location and modify paths in server.js

---

Slow Loading (>10 seconds)

Cause: Too many conversations to enrich (>500)

Performance Notes:

• Enrichment reads projects/*.jsonl for each conversation (~100-700KB per file)
• Typical load time: 2-5 seconds for 200-500 conversations
• Memory usage: ~50-100MB for typical workload

Optimization Opportunities:

• Add in-memory cache for session metadata
• Implement lazy loading (only load on modal open)
• Consider SQLite database for >1000 conversations

---

🧑‍💻 Development

Project Structure

claude-viewer/
├── server.js                 # Express backend (~114 lines, uses lib/)
├── mcp-server.js            # MCP server (~280 lines)
├── lib/
│   └── data-access.js       # Shared data functions (~700 lines)
├── public/
│   ├── index.html           # Main UI (165 lines)
│   ├── app.js               # Client logic (525 lines)
│   └── styles.css           # Styling (380 lines)
├── start-claude-viewer.sh   # Launcher script
├── package.json             # Dependencies
├── CLAUDE.md               # Project documentation
└── README.md               # This file

Key Backend Functions

File: server.js

1. getClaudeUsers() - Scans for users with .claude directories
2. parseHistoryFile(filePath, username) - Parses history.jsonl
3. getUserSessions(username) - Finds all session UUID files
4. parseSessionTranscript(filePath) - Parses full session JSONL
5. extractSessionMetadata(messages) - Extracts tokens, model, tools, message count
6. mapConversationsToSessions(conversations, users) - Matches history to sessions
7. buildConversationThread(messages) - Builds threaded conversation view

Key Frontend Functions

File: public/app.js

1. updateDashboard(stats) - Populates 8-card dashboard
2. renderConversations() - Renders 9-column table with enriched data
3. exportToCSV() - Exports 8 columns
4. showConversationDetails(sessionId, username) - Opens modal with full transcript
5. renderConversationThread(thread, container) - Renders user/assistant messages
6. renderAssistantContent(content) - Handles text/thinking/tool_use blocks

---

📈 Version History

v0.1.0 (2025-12-08) - Initial Public Release

Major Features:

• ✅ MCP Server - Exposes conversation data via Model Context Protocol
• ✅ 5 MCP Tools - get_claude_users, get_conversations, get_stats, get_conversation_details, open_dashboard
• ✅ Open Dashboard Tool - Start server and open browser directly from Claude
• ✅ Shared Library - Refactored code into lib/data-access.js for reuse
• ✅ ES Modules - Migrated from CommonJS to ES modules
• ✅ Configurable Port - Default 2204, set via CLAUDE_VIEWER_PORT env

Architecture Changes:

• server.js: Reduced from ~920 to ~114 lines (uses lib/)
• lib/data-access.js: New shared module (~700 lines)
• mcp-server.js: New MCP server entry point (~350 lines)
• package.json: Added "type": "module", MCP SDK dependencies

Dependencies Added:

• @modelcontextprotocol/sdk: ^1.12.0
• zod: ^3.25.0

---

🧪 Test Checklist

After installation or upgrade, verify:

• [ ] Dashboard displays 8 cards
• [ ] "Total Tokens" and "Total Messages" cards show numbers > 0
• [ ] "Top Model" card shows model name (e.g., "sonnet-4-5")
• [ ] "Top Tool" card shows tool name (e.g., "WebSearch")
• [ ] Conversation table has 9 columns
• [ ] "Msgs" column shows message count
• [ ] "Tokens" column shows formatted numbers (with commas)
• [ ] "Model" column shows abbreviated model names
• [ ] "Tools" column shows "X tools" with hover tooltip
• [ ] "💬 Dettagli" button opens modal with full conversation
• [ ] Modal displays user and assistant messages correctly
• [ ] CSV export includes 8 columns
• [ ] Search and filters work correctly
• [ ] Daily activity chart renders
• [ ] Keyword cloud displays

---

📝 Technical Notes

Performance Characteristics

• No database: All data loaded from files on each API request
• No backend pagination: All conversations loaded into memory at once
• Frontend filtering: O(n) filtering on every filter change
• Keyword extraction: Simple regex word matching (\b\w{4,}\b)

Security

• ✅ XSS protection with escapeHtml() function
• ✅ Session ID validation in backend
• ✅ No SQL injection risk (no database)
• ⚠️ File system access required (ensure proper permissions)

Browser Compatibility

• Chrome/Edge 90+
• Firefox 88+
• Safari 14+
• Requires ES6+ support

---

⚙️ Claude Code Configuration

Session Retention

Claude Code automatically deletes conversation sessions older than 30 days by default. To preserve history for Claude Viewer, configure the retention period in ~/.claude/settings.json:

{
  "cleanupPeriodDays": 365
}

Common values:

• 30 - Default (1 month)
• 90 - 3 months
• 365 - 1 year
• 730 - 2 years
• 999999 - Virtually unlimited

File locations:

OS	Path
macOS/Linux	~/.claude/settings.json
Windows	C:\Users\{USERNAME}\.claude\settings.json

Important: Longer retention means more historical data available in Claude Viewer!

---

🤝 Contributing

For issues or feature requests:

1. Check CLAUDE.md for architectural details
2. Review server.log for runtime errors
3. Open an issue on GitHub

---

📄 License

MIT License

Copyright (c) 2025 Max Turazzini

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.

---

Built with: Node.js, Express.js, Vanilla JavaScript Powered by: Claude Code conversation history data Author: Max Turazzini Version: 0.1.0 Last Updated: 2025-12-08