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

Total Conversations - Count of all conversations
Active Users - Number of unique users
Most Active User - User with most conversations
Most Used Project - Top project by conversation count
Total Tokens - Sum of all input/output/cache tokens
Total Messages - Count of all user + assistant messages
Top Model - Most-used Claude model (e.g., "sonnet-4-5")
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:

Verify Claude history files exist:

# macOS/Linux
ls ~/.claude/history.jsonl

# Windows
dir C:\Users\*\.claude\history.jsonl

Check permissions (may require admin on enterprise PCs):

# macOS/Linux
sudo npm start

# Windows (run terminal as Administrator)
npm start

Check server logs for errors:
```
tail -f server.log
```

Dashboard Shows "0" for Tokens/Messages

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

Solutions:

Verify session files exist:

# macOS/Linux
find ~/.claude/projects -name "*.jsonl"

# Windows
dir C:\Users\%USERNAME%\.claude\projects /s /b | findstr .jsonl

Check server console for "Error enriching conversation" messages
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:

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

Port 2204 Already in Use

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

Solutions:

Option 1: Kill existing process

# macOS/Linux
lsof -ti:2204 | xargs kill

# Windows
netstat -ano | findstr :2204
taskkill /F /PID [PID from above]

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

Cause: Session file deleted, moved, or corrupted

Solutions:

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

Permission Errors on Enterprise PCs

Cause: Corporate policies restrict access to user directories

Solutions:

Run terminal/command prompt as Administrator
Contact IT to grant read access to C:\Users\*\.claude\ directories
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

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

Key Frontend Functions

File: public/app.js

updateDashboard(stats) - Populates 8-card dashboard
renderConversations() - Renders 9-column table with enriched data
exportToCSV() - Exports 8 columns
showConversationDetails(sessionId, username) - Opens modal with full transcript
renderConversationThread(thread, container) - Renders user/assistant messages
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:

📝 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:

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

📄 License

MIT License

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

Claude Viewer

Multi-User Conversation History Viewer for Claude Code

🎯 Overview

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

Total Conversations - Count of all conversations
Active Users - Number of unique users
Most Active User - User with most conversations
Most Used Project - Top project by conversation count
Total Tokens - Sum of all input/output/cache tokens
Total Messages - Count of all user + assistant messages
Top Model - Most-used Claude model (e.g., "sonnet-4-5")
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:

Verify Claude history files exist:

# macOS/Linux
ls ~/.claude/history.jsonl

# Windows
dir C:\Users\*\.claude\history.jsonl

Check permissions (may require admin on enterprise PCs):

# macOS/Linux
sudo npm start

# Windows (run terminal as Administrator)
npm start

Check server logs for errors:
```
tail -f server.log
```

Dashboard Shows "0" for Tokens/Messages

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

Solutions:

Verify session files exist:

# macOS/Linux
find ~/.claude/projects -name "*.jsonl"

# Windows
dir C:\Users\%USERNAME%\.claude\projects /s /b | findstr .jsonl

Check server console for "Error enriching conversation" messages
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:

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

Port 2204 Already in Use

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

Solutions:

Option 1: Kill existing process

# macOS/Linux
lsof -ti:2204 | xargs kill

# Windows
netstat -ano | findstr :2204
taskkill /F /PID [PID from above]

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

Cause: Session file deleted, moved, or corrupted

Solutions:

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

Permission Errors on Enterprise PCs

Cause: Corporate policies restrict access to user directories

Solutions:

Run terminal/command prompt as Administrator
Contact IT to grant read access to C:\Users\*\.claude\ directories
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

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

Key Frontend Functions

File: public/app.js

updateDashboard(stats) - Populates 8-card dashboard
renderConversations() - Renders 9-column table with enriched data
exportToCSV() - Exports 8 columns
showConversationDetails(sessionId, username) - Opens modal with full transcript
renderConversationThread(thread, container) - Renders user/assistant messages
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:

📝 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:

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

📄 License

MIT License

The above copyright notice and this permission notice shall be included in all copies or substantial portions of 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

Claude Viewer

Claude Viewer

🎯 Overview

Demo

✨ Key Features

v0.1 Features

Core Features

🚀 Quick Start

Installation

⚡ Quick Start Integration Options

1️⃣ Automated Launcher Script (Recommended)

2️⃣ Global Shell Alias

📋 Summary of Launch Methods

🔌 MCP Server Integration (v0.1)

Running the MCP Server

Available MCP Tools

Configuration

Claude Desktop

Claude Code

Example Requests to Claude

Dashboard & Overview

User Analysis

Conversation Search

Token & Cost Analysis

Model & Tool Insights

Conversation Details

📊 Dashboard & Features

8-Card Statistics Dashboard

9-Column Conversation Table

Additional Features

🏗️ Architecture

Tech Stack

Dual-Source Data Architecture

Source 1: Quick Conversation List

Source 2: Full Session Transcripts

Data Flow

REST API Endpoints

🛠️ Configuration

Change Port (Optional)

Data Locations

⚠️ Troubleshooting

No Data Displayed

Dashboard Shows "0" for Tokens/Messages

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

Port 2204 Already in Use

"Cannot find module 'express'" Error

Modal Shows "Session not found"

Permission Errors on Enterprise PCs

Slow Loading (>10 seconds)

🧑‍💻 Development

Project Structure

Key Backend Functions

Key Frontend Functions

📈 Version History

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

🧪 Test Checklist

📝 Technical Notes

Performance Characteristics

Security

Browser Compatibility

⚙️ Claude Code Configuration

Session Retention

🤝 Contributing

📄 License

Claude Viewer

🎯 Overview

Demo

✨ Key Features

v0.1 Features

Core Features

🚀 Quick Start

Installation

⚡ Quick Start Integration Options

1️⃣ Automated Launcher Script (Recommended)

2️⃣ Global Shell Alias

📋 Summary of Launch Methods

🔌 MCP Server Integration (v0.1)

Running the MCP Server

Available MCP Tools

Configuration