Analytics Dashboard - Claude Code Templates

The Analytics Dashboard provides comprehensive real-time analytics for your Claude Code usage, including conversation tracking, token usage statistics, agent analysis, and performance monitoring.

Launch Dashboard

Start the analytics dashboard server:

claudedev analytics

Output:

🚀 Analytics dashboard started at http://localhost:3333
🌐 Opening browser to Claude Code Analytics...

The dashboard automatically opens in your default browser at http://localhost:3333.

Options

Verbose Mode

Enable detailed logging:

claudedev analytics --verbose

Open Specific View

Open directly to the agents view:

claudedev analytics --agents

Open to the 2025 Year in Review:

claudedev analytics --2025

Remote Access via Cloudflare Tunnel

For secure remote access to your analytics dashboard:

claudedev analytics --tunnel

Requirements:

cloudflared must be installed
macOS: brew install cloudflared
Windows: winget install --id Cloudflare.cloudflared
Linux: apt-get install cloudflared

Output:

🚀 Analytics dashboard started at http://localhost:3333
☁️  Setting up Cloudflare Tunnel...
☁️  Cloudflare Tunnel ready: https://abc-def-ghi.trycloudflare.com

Cloudflare Tunnel creates a secure, private connection. Only you have access to the generated URL. The connection is end-to-end encrypted and automatically closes when you stop the server.

Features

Conversation Analytics

Real-time tracking of all Claude Code conversations
State detection: Active, Idle, Recently active, Inactive
Process monitoring: Detects running Claude Code processes
File watching: Automatically refreshes when conversations change

Token Usage

Detailed token statistics:

Input tokens: User prompts and context
Output tokens: Claude responses
Cache creation tokens: Prompt caching overhead
Cache read tokens: Tokens read from cache
Total usage: Aggregate token consumption

Agent Usage Analysis

Track subagent invocations:

Agent types and frequency
Task tool usage patterns
Agent performance metrics
Date range filtering

Session Data

Claude Max plan usage tracking:

5-hour session windows
Current session progress
Session timer and countdown
Monthly and weekly session counts

Performance Monitoring

Memory usage tracking
Request statistics
Cache hit rates
Error monitoring
System health status

API Endpoints

The dashboard exposes several REST API endpoints:

Get All Data

curl http://localhost:3333/api/data

Returns conversations, summary, and detailed token usage.

Paginated Conversations

curl "http://localhost:3333/api/conversations?page=0&limit=10"

Conversation States

curl http://localhost:3333/api/conversation-state

Returns current state for all conversations.

Agent Analytics

curl "http://localhost:3333/api/agents?startDate=2025-01-01&endDate=2025-12-31"

Session Data

curl http://localhost:3333/api/session/data

Returns Max plan session tracking with timer data.

System Health

curl http://localhost:3333/api/system/health

Refresh Data

curl http://localhost:3333/api/refresh

Forces a full data reload.

Clear Cache

curl -X POST http://localhost:3333/api/clear-cache

Clears the conversation cache.

WebSocket Support

Real-time updates via WebSocket:

const ws = new WebSocket('ws://localhost:3333');

ws.on('message', (data) => {
  const event = JSON.parse(data);
  if (event.type === 'new_message') {
    console.log('New message:', event.data);
  }
});

Event Types:

new_message: New conversation message
data_refresh: Data reloaded
state_change: Conversation state changed

Data Sources

The dashboard reads from:

~/.claude/: Conversation JSONL files
~/Library/Application Support/Claude/: Claude Desktop data (macOS)
~/.claude/statsig/: Usage statistics

Performance Considerations

Memory Management

The dashboard implements several optimizations:

Conversation limiting: Keeps only 150 most recent conversations in memory
Data caching: Parsed conversations cached to reduce disk I/O
Garbage collection: Manual GC hints when available

File Watching

Automatic refresh when:

New conversation files created
Existing conversations modified
Settings files updated

Debounced to prevent excessive reloads (2-second delay).

Architecture

Core Components

StateCalculator (analytics/core/StateCalculator.js):lines/analytics.js:31

Determines conversation states
Quick state calculation for active processes
Idle time detection

ProcessDetector (analytics/core/ProcessDetector.js):lines/analytics.js:32

Detects running Claude Code processes
Enriches conversations with process info
Finds orphan processes

ConversationAnalyzer (analytics/core/ConversationAnalyzer.js):lines/analytics.js:98

Loads and parses conversation files
Extracts project information
Calculates token usage

SessionAnalyzer (analytics/core/SessionAnalyzer.js):lines/analytics.js:34

Tracks Max plan sessions
Calculates 5-hour windows
Provides session timer data

AgentAnalyzer (analytics/core/AgentAnalyzer.js):lines/analytics.js:35

Analyzes agent usage patterns
Tracks subagent invocations
Generates usage summaries

YearInReview2025 (analytics/core/YearInReview2025.js):lines/analytics.js:36

Generates annual statistics
Activity heatmaps
Top projects and patterns

Data Flow

Initialization:lines/analytics.js:86
- Check Claude directories exist
- Load initial conversation data
- Setup file watchers
- Start Express server
Data Loading:lines/analytics.js:105
- Parse conversation JSONL files
- Calculate token usage
- Extract model information
- Generate status squares
Real-time Updates:lines/analytics.js:592
- File watcher detects changes
- Debounced data refresh
- WebSocket broadcast to clients
Fast State Updates:lines/analytics.js:999
- Only updates conversation states
- Doesn’t reload entire dataset
- Used for frequent polling

Example: Monitoring Token Usage

# Start dashboard
claudedev analytics

# In another terminal, query token usage
curl http://localhost:3333/api/data | jq '.detailedTokenUsage'

Output:

{
  "total": 1234567,
  "inputTokens": 456789,
  "outputTokens": 654321,
  "cacheCreationTokens": 12345,
  "cacheReadTokens": 111112,
  "messagesWithUsage": 150,
  "totalMessages": 200
}

Troubleshooting

Dashboard Won’t Start

Error: Claude Code directory not found Run Claude Code at least once to create ~/.claude/ directory.

No Conversations Showing

Check conversation files exist:

ls ~/.claude/projects/*/conversation.jsonl

Port Already in Use

The dashboard uses port 3333. If occupied:

lsof -i :3333
kill -9 <PID>

WebSocket Connection Failed

Verify WebSocket server initialized:

claudedev analytics --verbose

Look for: 🌐 WebSocket server initialized

Advanced Usage

Custom Port

Edit analytics.js:line/analytics.js:30

this.port = 3333; // Change to desired port

Disable File Watching

Comment out file watcher setup in initialize():line/analytics.js:102

Extend with Custom Analytics

Add custom endpoint:

this.app.get('/api/custom', (req, res) => {
  const customData = calculateCustomMetrics(this.data);
  res.json(customData);
});

​Launch Dashboard

​Options

​Verbose Mode

​Open Specific View

​Remote Access via Cloudflare Tunnel

​Features

​Conversation Analytics

​Token Usage

​Agent Usage Analysis

​Session Data

​Performance Monitoring

​API Endpoints

​Get All Data

​Paginated Conversations

​Conversation States

​Agent Analytics

​Session Data

​System Health

​Refresh Data

​Clear Cache

​WebSocket Support

​Data Sources

​Performance Considerations

​Memory Management

​File Watching

​Architecture

​Core Components

​Data Flow

​Example: Monitoring Token Usage

​Troubleshooting

​Dashboard Won’t Start

​No Conversations Showing

​Port Already in Use

​WebSocket Connection Failed

​Advanced Usage

​Custom Port

​Disable File Watching

​Extend with Custom Analytics

​See Also

Launch Dashboard

Options

Verbose Mode

Open Specific View

Remote Access via Cloudflare Tunnel

Features

Conversation Analytics

Token Usage

Agent Usage Analysis

Session Data

Performance Monitoring

API Endpoints

Get All Data

Paginated Conversations

Conversation States

Agent Analytics

Session Data

System Health

Refresh Data

Clear Cache

WebSocket Support

Data Sources

Performance Considerations

Memory Management

File Watching

Architecture

Core Components

Data Flow

Example: Monitoring Token Usage

Troubleshooting

Dashboard Won’t Start

No Conversations Showing

Port Already in Use

WebSocket Connection Failed

Advanced Usage

Custom Port

Disable File Watching

Extend with Custom Analytics

See Also