claude-viewer: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code when working with this repository.

GitHub Account

Before any GitHub operations (push, PR, etc.), switch to the correct account:

gh auth switch -u maxturazzini

Project Overview

Claude Viewer is an admin tool that visualizes Claude Code conversation history from all users on a machine. It uses a dual-source data approach:

1. Primary: ~/.claude/history.jsonl - Quick conversation list
2. Enrichment: ~/.claude/projects/{project}/{session-uuid}.jsonl - Full conversation details

Key Features:

• Full conversations (user prompts AND Claude responses)
• Token usage analytics (input/output/cache)
• Model tracking (sonnet-4-5, opus, haiku)
• Tool usage analytics (WebSearch, Bash, Edit, etc.)
• MCP Server for Claude Desktop/Code integration

Tech Stack

• Backend: Node.js + Express.js (v4.18.2)
• MCP Server: Model Context Protocol with stdio transport
• Frontend: Vanilla JavaScript, HTML5, CSS3
• Data: JSONL files from Claude Code history
• Platform: Cross-platform (macOS, Linux, Windows)

Development Commands

# Install dependencies
npm install

# Start web server
npm start

# Run MCP server
npm run mcp

# Default port: 2204 (configurable via CLAUDE_VIEWER_PORT env)

MCP Server

Tools Available

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 (~/Library/Application Support/Claude/claude_desktop_config.json):

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