claude-code-tracker/README.md

Claude Code Project Tracker

A comprehensive development intelligence system that tracks and analyzes your coding activity when using Claude Code. Get insights into your development patterns, track sessions, monitor conversations, and analyze productivity trends.

🚀 Features

🎯 Core Functionality

• Automatic Session Tracking - Real-time monitoring of Claude Code sessions
• Conversation History - Complete searchable archive of your interactions
• Project Analytics - Detailed insights per project with timelines and statistics
• File Upload Import - Easy .claude.json file import with preview functionality
• Hook Integration - 39+ hooks for comprehensive activity tracking

🐳 Deployment & Installation

• Docker Ready - Production-ready containerization with Caddy integration
• One-Click Setup - Automated hook installation with ./setup-hooks
• Multiple Profiles - 7 pre-configured hook profiles for different use cases
• User-Scope Installation - Safe, reversible installation process

📊 Analytics & Insights

• Development Metrics - Track time, sessions, and productivity trends
• Visual Analytics - Charts, graphs, and timeline visualizations
• Project Intelligence - Language detection, file activity, and code metrics
• Conversation Search - Full-text search through your Claude Code history

🔒 Privacy & Security

• Local Data - All data stays on your server, no external dependencies
• HTTPS Support - Secure communication with automatic SSL via Caddy
• User Control - Complete control over data collection and retention

📦 Quick Start

Option 1: Docker Deployment (Recommended)

# 1. Clone and configure
git clone https://git.supported.systems/claude/claude-code-tracker.git claude-tracker
cd claude-tracker
cp .env.example .env
# Edit .env with your domain

# 2. Deploy with Docker
docker-compose up -d

# 3. Install hooks on your development machine
export DOMAIN=your-domain.com
./setup-hooks

# 4. Start using Claude Code!

Option 2: Local Development

# 1. Install dependencies
pip install -r requirements.txt

# 2. Initialize database
python init_db.py

# 3. Start the server
python main.py

# 4. Install hooks
export DOMAIN=localhost:8000
./setup-hooks

🛠️ Installation Scripts

Quick Setup (Most Users)

export DOMAIN=your-domain.com
./setup-hooks

Advanced Installation

# List available hook profiles
./install-hooks.sh --list

# Install specific profile
./install-hooks.sh comprehensive
./install-hooks.sh developer
./install-hooks.sh basic

# Custom domain
./install-hooks.sh -d your-domain.com comprehensive

# Verify installation
./install-hooks.sh --verify

# Remove hooks
./install-hooks.sh --uninstall

📋 Hook Profiles

Profile	Hooks	Best For	Description
basic	5	New users	Essential session and conversation tracking
essential	8	Most users	Core development tracking features
comprehensive	39+	Complete tracking	All available hooks (recommended)
developer	15	Active developers	Professional development focused
power_user	20	Advanced users	Detailed analytics and monitoring
research	25	Researchers	Learning and exploration tracking
team	18	Teams	Collaboration and sharing features

🏗️ Architecture

Backend (FastAPI)

• Python 3.12 with async/await support
• SQLAlchemy 2.0 with async SQLite database
• FastAPI for modern, high-performance API
• Pydantic for data validation and serialization

Frontend (Web Dashboard)

• Bootstrap 5 for responsive UI components
• Jinja2 templating with server-side rendering
• Chart.js for interactive visualizations
• Real-time updates via API polling

Deployment

• Docker with multi-stage builds and uv package manager
• Caddy reverse proxy with automatic SSL
• Health checks and resource monitoring
• Data persistence with volume mounting

📖 Documentation

Complete documentation is available at /dashboard/docs when running the application:

• Getting Started Guide - Setup and first steps
• Data Import Guide - File upload and import process
• Docker Deployment - Production deployment
• Hook Setup Guide - Automated and manual hook installation
• Hook Reference - Complete hook documentation
• API Reference - Interactive API documentation

📁 Project Structure

claude-tracker/
├── app/
│   ├── api/                 # API endpoints
│   │   ├── importer.py      # Data import functionality
│   │   └── hooks.py         # Hook management API
│   ├── dashboard/           # Web interface
│   │   ├── templates/       # HTML templates
│   │   ├── static/          # Static assets and hook configs
│   │   └── routes.py        # Dashboard routes
│   ├── database/            # Database connection
│   ├── models/              # SQLAlchemy models
│   └── __init__.py
├── hooks/                   # Hook configuration files
│   ├── claude-hooks-basic.json
│   ├── claude-hooks-comprehensive.json
│   └── ...
├── install-hooks.sh         # Comprehensive hook installer
├── setup-hooks             # Simple hook installer
├── docker-compose.yml      # Docker deployment config
├── Dockerfile              # Container definition
├── main.py                 # Application entry point
├── init_db.py              # Database initialization
└── README.md

🔧 Configuration

Environment Variables

Variable	Description	Example
DOMAIN	Your tracker domain	claude.example.com
DATABASE_URL	Database connection string	sqlite+aiosqlite:///./data/tracker.db
DEBUG	Enable debug mode	false
PYTHONPATH	Python module path	/app

Hook Configuration

Hooks are installed to ~/.config/claude-code/settings.json and include:

• Session Management - Start, end, pause, resume tracking
• Conversation Tracking - Message exchanges, context updates
• File Operations - Create, modify, delete, read operations
• Tool Calls - Claude Code tool usage and results
• Performance Monitoring - Memory, CPU, execution times
• Code Quality - Linting, testing, compilation events
• Project Intelligence - Language detection, dependencies

🛡️ Security & Privacy

• Local Data Storage - All data stays on your server
• User-Scope Installation - No system-wide changes required
• Automatic Backups - Settings preserved before modifications
• HTTPS Enforcement - Secure communication by default
• Data Validation - Input sanitization and validation
• Error Handling - Graceful failure and recovery

🧪 Development

Running Tests

# Run the test suite
pytest tests/

# Run with coverage
pytest --cov=app tests/

Local Development Setup

# Install development dependencies
pip install -r requirements-dev.txt

# Start with auto-reload
uvicorn main:app --reload --host 0.0.0.0 --port 8000

# Initialize test database
python init_db.py

Database Migrations

# Create new migration
alembic revision --autogenerate -m "Description"

# Apply migrations
alembic upgrade head

📊 API Endpoints

Core Tracking

• POST /api/sessions/start - Start new session
• POST /api/sessions/end - End session
• POST /api/conversations - Log conversation
• POST /api/tool-calls - Track tool usage

Data Management

• POST /api/import/claude-json - Import from file path
• POST /api/import/claude-json/upload - Import via file upload
• GET /api/import/claude-json/preview - Preview import data

Analytics

• GET /api/projects - List projects
• GET /api/projects/{id}/stats - Project statistics
• GET /api/conversations/search - Search conversations

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Run the test suite
6. Submit a pull request

📄 License

This project is licensed under the MIT License. See LICENSE file for details.

🆘 Support

• Documentation: Visit /dashboard/docs in your running instance
• Issues: Report bugs and request features via GitHub Issues
• Discussions: Join community discussions for questions and ideas

🔄 Updates

The project is actively maintained with regular updates for:

• New Claude Code features and hooks
• Performance improvements and optimizations
• Enhanced analytics and visualizations
• Security updates and bug fixes

---

Made with ❤️ for the Claude Code community