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)

```bash
# 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

```bash
# 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)
```bash
export DOMAIN=your-domain.com
./setup-hooks
```

### Advanced Installation
```bash
# 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](./app/dashboard/templates/docs/getting-started.html)** - Setup and first steps
- **[Data Import Guide](./app/dashboard/templates/docs/data-import.html)** - File upload and import process
- **[Docker Deployment](./app/dashboard/templates/docs/docker-deployment.html)** - Production deployment
- **[Hook Setup Guide](./app/dashboard/templates/docs/hook-setup.html)** - Automated and manual hook installation
- **[Hook Reference](./app/dashboard/templates/docs/hook-reference.html)** - Complete hook documentation
- **[API Reference](./docs)** - 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
```bash
# Run the test suite
pytest tests/

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

### Local Development Setup
```bash
# 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
```bash
# 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**