# Claude Code Project Tracker

A comprehensive development intelligence system that tracks your Claude Code sessions, providing insights into your coding patterns, productivity, and learning journey.

## Overview

The Claude Code Project Tracker automatically captures your development workflow through Claude Code's hook system, creating a detailed record of:

- **Development Sessions** - When you start/stop working, what projects you focus on
- **Conversations** - Full dialogue history with Claude for context and learning analysis  
- **Code Changes** - File modifications, tool usage, and command executions
- **Thinking Patterns** - Wait times between interactions to understand your workflow
- **Git Activity** - Repository changes, commits, and branch operations
- **Productivity Metrics** - Engagement levels, output quality, and learning velocity

## Architecture

```
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Claude Code   │───▶│   Hook System   │───▶│  FastAPI Server │
│   (your IDE)    │    │                 │    │                 │
└─────────────────┘    └─────────────────┘    └─────────────────┘
                                                        │
                                                        ▼
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│  Web Dashboard  │◀───│  Analytics      │◀───│ SQLite Database │
│                 │    │     Engine      │    │                 │
└─────────────────┘    └─────────────────┘    └─────────────────┘
```

### Components

- **FastAPI Server**: REST API that receives hook data and serves analytics
- **SQLite Database**: Local storage for all tracking data
- **Hook Integration**: Claude Code hooks that capture development events
- **Analytics Engine**: Processes raw data into meaningful insights
- **Web Dashboard**: Interactive interface for exploring your development patterns

## Key Features

### 🎯 Session Tracking
- Automatic project detection and session management
- Working directory and git branch context
- Session duration and engagement analysis

### 💬 Conversation Intelligence  
- Full dialogue history with semantic search
- Problem-solving pattern recognition
- Learning topic identification and progress tracking

### 📊 Development Analytics
- Productivity metrics and engagement scoring
- Tool usage patterns and optimization insights
- Cross-project learning and code reuse analysis

### 🔍 Advanced Insights
- Think time analysis and flow state detection
- Git activity correlation with conversations
- Skill development velocity tracking
- Workflow optimization recommendations

## Data Privacy

- **Local-First**: All data stays on your machine
- **No External Services**: No data transmission to third parties
- **Full Control**: Complete ownership of your development history
- **Selective Tracking**: Configurable hook activation per project

## Quick Start

1. **Install Dependencies**
   ```bash
   pip install -r requirements.txt
   ```

2. **Start the Tracking Server**
   ```bash
   python main.py
   ```

3. **Configure Claude Code Hooks**
   ```bash
   # Add hooks to your Claude Code settings
   cp config/claude-hooks.json ~/.config/claude-code/
   ```

4. **Access Dashboard**
   ```
   Open http://localhost:8000 in your browser
   ```

## Project Structure

```
claude-tracker/
├── README.md              # This file
├── requirements.txt       # Python dependencies
├── main.py               # FastAPI application entry point
├── config/               # Configuration files
│   └── claude-hooks.json # Hook setup for Claude Code
├── app/                  # Application code
│   ├── models/          # Database models
│   ├── api/             # API endpoints
│   ├── analytics/       # Insights engine
│   └── dashboard/       # Web interface
├── tests/               # Test suite
├── docs/                # Detailed documentation
└── data/                # SQLite database location
```

## Documentation

- [API Specification](docs/api-spec.yaml) - Complete endpoint documentation
- [Database Schema](docs/database-schema.md) - Data model details
- [Hook Setup Guide](docs/hook-setup.md) - Claude Code integration
- [Development Guide](docs/development.md) - Local setup and contribution
- [Analytics Guide](docs/analytics.md) - Understanding insights and metrics

## Development

See [Development Guide](docs/development.md) for detailed setup instructions.

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

# Run tests
pytest

# Start development server with hot reload
uvicorn main:app --reload

# Generate API documentation
python -m app.generate_docs
```

## Contributing

This project follows test-driven development. Please ensure:
1. All new features have comprehensive tests
2. Documentation is updated for API changes
3. Analytics insights are validated with test data

## License

MIT License - See LICENSE file for details