# 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:
```bash
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
```bash
# 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`):
```json
{
"mcpServers": {
"claude-viewer": {
"command": "node",
"args": ["/path/to/claude-viewer/mcp-server.js"]
}
}
}
```
**Claude Code** (recommended via CLI):
```bash
# Global (all projects)
claude mcp add claude-viewer -s user -- node "/path/to/claude-viewer/mcp-server.js"
# Per project
claude mcp add claude-viewer -s project -- node "/path/to/claude-viewer/mcp-server.js"
```
## Project Structure
```
claude-viewer/
├── server.js # Express backend (~114 lines)
├── mcp-server.js # MCP server (~350 lines)
├── lib/
│ └── data-access.js # Shared data functions (~700 lines)
├── public/
│ ├── index.html # Main UI
│ ├── app.js # Client logic
│ └── styles.css # Styling
├── start-claude-viewer.sh # Launcher script
└── package.json
```
## REST API Endpoints
- `GET /api/users` - List users with Claude history
- `GET /api/conversations` - All conversations with enriched metadata
- `GET /api/stats` - Aggregated statistics
- `GET /api/conversation/:sessionId/:username` - Full conversation transcript
## 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`
## Important: Session Retention
Claude Code auto-deletes sessions after 30 days by default. To preserve history:
```json
// ~/.claude/settings.json
{
"cleanupPeriodDays": 365
}
```
## Common Issues
| Issue | Solution |
|-------|----------|
| "Cannot find module 'express'" | Run `npm install` |
| No data displayed | Verify `~/.claude/history.jsonl` exists |
| Port 2204 in use | Set `CLAUDE_VIEWER_PORT=3000 npm start` |
| Browser shows old UI | Hard refresh: `Cmd+Shift+R` |
## Version
- **Version:** 0.1.0
- **Author:** Max Turazzini
- **License:** MIT
