claude-code-tracker/README.md

# 🚀 Claude Code Project Tracker

<div align="center">

![Claude Code Tracker Hero](https://img.shields.io/badge/Claude%20Code-Project%20Tracker-blue?style=for-the-badge&logo=anthropic&logoColor=white)

**🎯 The Ultimate Development Intelligence System for Claude Code Users**

*Transform your coding journey into data-driven insights with real-time tracking, comprehensive analytics, and seamless automation*

[![Docker Ready](https://img.shields.io/badge/Docker-Ready-2496ED?style=flat-square&logo=docker&logoColor=white)](./docker-compose.yml)
[![FastAPI](https://img.shields.io/badge/FastAPI-Python%203.12-009688?style=flat-square&logo=fastapi&logoColor=white)](https://fastapi.tiangolo.com/)
[![Caddy Integration](https://img.shields.io/badge/Caddy-SSL%20Ready-1F88C0?style=flat-square&logo=caddy&logoColor=white)](https://caddyserver.com/)
[![File Upload](https://img.shields.io/badge/File%20Upload-Drag%20%26%20Drop-4CAF50?style=flat-square&logo=files&logoColor=white)](#-data-import--file-upload)
[![39+ Hooks](https://img.shields.io/badge/Hooks-39%2B%20Types-FF6B6B?style=flat-square&logo=webhook&logoColor=white)](#-hook-profiles--automation)

</div>

---

## ✨ What Makes This Project AWESOME?

### 🎭 **It's Like Having a Personal Data Scientist for Your Code**
Stop wondering *"What did I work on last week?"* or *"How productive was I this month?"*. Claude Code Tracker automatically captures everything, analyzes your patterns, and presents beautiful insights about your development journey.

### 🔥 **Zero-Friction Setup That Just Works**
```bash
# Literally 4 commands and you're tracking everything!
git clone https://git.supported.systems/claude/claude-code-tracker.git
cd claude-code-tracker
docker-compose up -d
./setup-hooks
```
**That's it!** 🎉 Your tracker is live, hooks are installed, and data is flowing.

### 🧠 **Smart Enough to Surprise You**
- **File Upload with AI Preview** - Drag your `.claude.json`, get instant insights
- **39+ Hook Types** - More comprehensive than any other Claude Code tracker
- **7 User Profiles** - From beginners to teams, we've got your use case covered
- **Language Detection** - Automatically figures out what you're coding in
- **Timeline Visualization** - See your coding journey unfold over time

---

## 🌟 **Features That Will Blow Your Mind**

<table>
<tr>
<td width="50%">

### 🎯 **Real-Time Intelligence**
- **Live Session Tracking** - Watch your productivity in real-time
- **Conversation History** - Never lose a brilliant Claude exchange again
- **Project Analytics** - Deep insights per project with visual timelines
- **Smart File Monitoring** - Know exactly what files you're touching

</td>
<td width="50%">

### 🚀 **Next-Level Automation**
- **One-Click Hook Install** - `./setup-hooks` and you're done
- **7 Pre-Built Profiles** - Choose your adventure (basic → comprehensive)
- **Auto-Domain Config** - Works with any domain instantly
- **Self-Healing Setup** - Backups, verification, rollbacks included

</td>
</tr>
<tr>
<td width="50%">

### 📊 **Beautiful Visualizations**
- **Interactive Dashboards** - Bootstrap 5 + Chart.js magic
- **Project Timelines** - See your development story unfold
- **Productivity Heatmaps** - Identify your peak coding hours
- **Conversation Search** - Full-text search through all interactions

</td>
<td width="50%">

### 🔒 **Privacy-First Design**
- **100% Local** - Your data never leaves your server
- **Docker Containerized** - Secure, isolated, professional
- **HTTPS Ready** - Automatic SSL with Caddy integration
- **User-Scope Only** - No system changes, completely reversible

</td>
</tr>
</table>

---

## 🚀 **Get Started in 60 Seconds**

### 🐳 **Docker Deployment** (Recommended for Everyone)

<div align="center">

*The fastest way to get a production-ready tracker with SSL, monitoring, and all the bells and whistles*

</div>

```bash
# 🎬 Step 1: Get the goods
git clone https://git.supported.systems/claude/claude-code-tracker.git claude-tracker
cd claude-tracker

# 🔧 Step 2: Configure your domain  
cp .env.example .env
echo "DOMAIN=your-awesome-domain.com" >> .env

# 🚀 Step 3: Launch the beast
docker-compose up -d

# 🎯 Step 4: Install hooks (on your dev machine)
export DOMAIN=your-awesome-domain.com
./setup-hooks

# 🎉 Step 5: Start coding and watch the magic happen!
```

<div align="center">

**🎊 Boom! You now have a professional-grade development intelligence system!**

Visit `https://your-awesome-domain.com/dashboard` and prepare to be amazed 🤩

</div>

### 💻 **Local Development** (For the Tinkerers)

```bash
# Clone and setup
git clone https://git.supported.systems/claude/claude-code-tracker.git claude-tracker
cd claude-tracker

# Python magic
pip install -r requirements.txt
python init_db.py
python main.py

# Hook installation
export DOMAIN=localhost:8000
./setup-hooks

# Visit http://localhost:8000/dashboard
```

---

## 🎭 **Hook Profiles: Choose Your Adventure**

<div align="center">

*Not all developers are the same. We've got 7 carefully crafted profiles to match your workflow*

</div>

<table>
<tr>
<th width="15%">Profile</th>
<th width="10%">Hooks</th>
<th width="20%">Perfect For</th>
<th width="55%">What You Get</th>
</tr>
<tr>
<td><strong>🌱 basic</strong></td>
<td align="center">5</td>
<td>New Users</td>
<td>Essential session and conversation tracking. Clean, simple, effective.</td>
</tr>
<tr>
<td><strong>⚡ essential</strong></td>
<td align="center">8</td>
<td>Most Developers</td>
<td>Core development tracking with file monitoring and tool usage.</td>
</tr>
<tr>
<td><strong>🎯 comprehensive</strong></td>
<td align="center">39+</td>
<td>Data Lovers</td>
<td><strong>EVERYTHING!</strong> Complete tracking, analytics, performance, quality metrics.</td>
</tr>
<tr>
<td><strong>💼 developer</strong></td>
<td align="center">15</td>
<td>Professionals</td>
<td>Code quality, testing, deployment tracking for serious developers.</td>
</tr>
<tr>
<td><strong>🔥 power_user</strong></td>
<td align="center">20</td>
<td>Advanced Users</td>
<td>Performance monitoring, workflow optimization, productivity analytics.</td>
</tr>
<tr>
<td><strong>🔬 research</strong></td>
<td align="center">25</td>
<td>Researchers</td>
<td>Learning patterns, exploration tracking, knowledge gap analysis.</td>
</tr>
<tr>
<td><strong>👥 team</strong></td>
<td align="center">18</td>
<td>Collaborative Teams</td>
<td>Collaboration insights, sharing patterns, team productivity metrics.</td>
</tr>
</table>

<div align="center">

**🎮 Switch profiles anytime:** `./install-hooks.sh power_user`

</div>

---

## 🏗️ **Architecture That Actually Makes Sense**

<div align="center">

*We built this right. Modern, scalable, maintainable.*

</div>

```mermaid
graph TB
    A[🌐 Claude Code] --> B[🎯 Hooks System]
    B --> C[🚀 FastAPI Backend]
    C --> D[📊 SQLite Database]
    C --> E[🎨 Bootstrap Dashboard]
    F[📁 File Upload] --> C
    G[🐳 Docker Container] --> H[🔒 Caddy Proxy]
    H --> I[🌍 Your Domain]
    
    style A fill:#e1f5fe
    style C fill:#f3e5f5
    style E fill:#e8f5e8
    style I fill:#fff3e0
```

### 🛠️ **Tech Stack That Rocks**

| Component | Technology | Why It's Awesome |
|-----------|------------|------------------|
| **Backend** | FastAPI + Python 3.12 | ⚡ Blazing fast, async everything, automatic OpenAPI docs |
| **Database** | SQLite + SQLAlchemy 2.0 | 🗃️ Zero config, async ORM, perfect for single-user deployments |
| **Frontend** | Bootstrap 5 + Jinja2 | 🎨 Responsive, accessible, server-side rendered |
| **Deployment** | Docker + Caddy | 🚀 One command deploy, automatic SSL, reverse proxy magic |
| **Package Manager** | uv | ⚡ 10-100x faster than pip, modern Python tooling |

---

## 📸 **Screenshots Worth a Thousand Words**

<div align="center">

*Because seeing is believing*

</div>

### 🎯 **Dashboard Overview**
> *See your development activity at a glance with beautiful charts and metrics*

### 📊 **Project Analytics**  
> *Deep dive into individual projects with timelines, language breakdowns, and activity patterns*

### 🔍 **Conversation Search**
> *Find any Claude Code interaction instantly with powerful full-text search*

### 📁 **File Upload Magic**
> *Drag and drop your .claude.json file and watch the AI analyze and preview your data*

---

## 🎮 **Advanced Usage & Pro Tips**

<details>
<summary><strong>🔥 Power User Tricks (Click to expand)</strong></summary>

### 🎯 **Custom Hook Profiles**
```bash
# Create your own profile by copying and modifying existing ones
cp claude-hooks-comprehensive.json claude-hooks-myprofile.json
# Edit the file to your needs
./install-hooks.sh myprofile
```

### 🔄 **Profile Switching Made Easy**
```bash
# Switch between profiles anytime
./install-hooks.sh basic        # Start simple
./install-hooks.sh comprehensive  # Go full power
./install-hooks.sh --verify     # Check what's installed
```

### 🛠️ **Domain Management**
```bash
# Switch domains without rebuilding
./install-hooks.sh -d new-domain.com comprehensive

# Multiple environments
./install-hooks.sh -d localhost:8000 developer    # Local dev
./install-hooks.sh -d staging.example.com team    # Staging
./install-hooks.sh -d prod.example.com comprehensive  # Production
```

### 🔍 **Debugging & Troubleshooting**
```bash
# Verify everything is working
./install-hooks.sh --verify

# Check Docker logs
docker-compose logs -f

# Test connectivity
curl https://your-domain.com/health

# Uninstall cleanly
./install-hooks.sh --uninstall
```

</details>

<details>
<summary><strong>🐳 Docker Deployment Deep Dive (Click to expand)</strong></summary>

### 🏗️ **Production-Ready Features**
- **Multi-stage builds** with uv for lightning-fast dependency installation
- **Health checks** with automatic restart policies
- **Resource limits** to prevent runaway processes
- **Volume mounting** for data persistence
- **Automatic SSL** via Caddy docker-proxy integration

### 🔧 **Environment Configuration**
```bash
# .env file configuration
DOMAIN=your-domain.com
DATABASE_URL=sqlite+aiosqlite:////app/data/tracker.db
DEBUG=false
PYTHONPATH=/app
```

### 📊 **Monitoring & Maintenance**
```bash
# Container health
docker-compose ps
docker-compose logs

# Database backup
cp ./data/tracker.db ./backups/tracker-$(date +%Y%m%d).db

# Updates
git pull
docker-compose build --no-cache
docker-compose up -d
```

</details>

---

## 🤝 **Contributing & Community**

<div align="center">

*Join the revolution! Help make Claude Code tracking even more awesome*

</div>

### 🎯 **Ways to Contribute**
- 🐛 **Bug Reports** - Found something broken? We want to know!
- 💡 **Feature Requests** - Got ideas? Share them!
- 📝 **Documentation** - Help others discover the magic
- 🔧 **Code Contributions** - PRs welcome and appreciated
- 🎨 **UI/UX Improvements** - Make it even more beautiful
- 🧪 **Testing** - Help us ensure quality across environments

### 🏆 **Recognition Wall**
*Contributors who made this project awesome:*

- **You!** - For considering contributing to this amazing project

---

## 📚 **Documentation That Actually Helps**

<div align="center">

*Comprehensive guides that get you from zero to hero*

</div>

| 📖 Guide | 🎯 Purpose | ⏱️ Time |
|----------|-----------|---------|
| [🚀 Getting Started](./app/dashboard/templates/docs/getting-started.html) | Your first steps to tracking mastery | 5 min |
| [📁 Data Import Guide](./app/dashboard/templates/docs/data-import.html) | Master the file upload system | 3 min |
| [🐳 Docker Deployment](./app/dashboard/templates/docs/docker-deployment.html) | Production deployment like a pro | 10 min |
| [🎯 Hook Setup](./app/dashboard/templates/docs/hook-setup.html) | Automated and manual installation | 7 min |
| [📋 Hook Reference](./app/dashboard/templates/docs/hook-reference.html) | Complete hook documentation | Reference |
| [🔧 API Documentation](./docs) | Interactive API exploration | Reference |

---

## 🎊 **What Users Are Saying**

<div align="center">

> *"I wish I had this when I started using Claude Code. The insights are incredible!"* 
> **- Future You**

> *"The Docker setup just works. One command and I had a professional tracking system running."*
> **- Developers Everywhere**

> *"39+ hooks?! This tracks everything I didn't even know I wanted to track."*
> **- Data Enthusiasts**

</div>

---

## 🔮 **What's Coming Next**

<div align="center">

*The future is bright! Here's what we're cooking up*

</div>

- 📱 **Mobile Dashboard** - Check your stats on the go
- 🤖 **AI Insights** - Let AI analyze your patterns and suggest improvements  
- 🔄 **Team Features** - Collaborative tracking and insights
- 📊 **Advanced Analytics** - Even more beautiful visualizations
- 🔌 **Plugin System** - Extend functionality with custom plugins
- 🌐 **Multi-Language Support** - Because code is universal

---

## 🚨 **FAQ: The Questions Everyone Asks**

<details>
<summary><strong>❓ Is my data safe and private?</strong></summary>

**Absolutely!** Everything runs on your server. No data ever leaves your infrastructure. It's like having your own private Google Analytics for coding.

</details>

<details>
<summary><strong>❓ Will this slow down Claude Code?</strong></summary>

**Nope!** Hooks are lightweight HTTP calls that run asynchronously. You won't notice any difference in Claude Code performance.

</details>

<details>
<summary><strong>❓ Can I use this with multiple domains?</strong></summary>

**Yes!** Switch domains anytime with `./install-hooks.sh -d new-domain.com`. Perfect for dev/staging/prod environments.

</details>

<details>
<summary><strong>❓ What if I want to stop tracking?</strong></summary>

**Easy!** Run `./install-hooks.sh --uninstall` and everything goes back to normal. No traces left behind.

</details>

<details>
<summary><strong>❓ Can I customize what gets tracked?</strong></summary>

**Totally!** Choose from 7 profiles or create your own by editing the JSON files. Full control over your data.

</details>

---

## 📄 **License & Legal**

<div align="center">

**MIT Licensed** - Use it, modify it, love it, share it

*This project is not affiliated with Anthropic. Claude Code is a trademark of Anthropic.*

</div>

---

<div align="center">

## 🎉 **Ready to Transform Your Development Experience?**

### 🚀 **One Command to Rule Them All**

```bash
git clone https://git.supported.systems/claude/claude-code-tracker.git && cd claude-code-tracker && docker-compose up -d && ./setup-hooks
```

**That's it!** Welcome to the future of development intelligence 🎊

---

[![Made with ❤️](https://img.shields.io/badge/Made%20with-❤️-red?style=for-the-badge)](https://github.com/yourusername)
[![For Claude Code](https://img.shields.io/badge/For-Claude%20Code-blue?style=for-the-badge&logo=anthropic)](https://claude.ai/code)
[![Powered by Coffee](https://img.shields.io/badge/Powered%20by-Coffee-brown?style=for-the-badge&logo=buy-me-a-coffee)](https://buymeacoffee.com/yourhandle)

**⭐ Star this repo if it made your coding life better!**

</div>