claude/claude-code-tracker
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Add comprehensive hook installation system and update documentation

Browse source 
Major Features Added:
• Automated hook installation scripts (install-hooks.sh and setup-hooks)
• User-scope installation with automatic domain configuration
• 7 pre-configured hook profiles for different user types
• Comprehensive documentation updates across all guides

Hook Installation System:
• ./setup-hooks - One-liner installation for most users
• ./install-hooks.sh - Full-featured installer with profile selection
• Automatic domain replacement using $DOMAIN environment variable
• Settings backup and verification capabilities
• Safe uninstallation with rollback support

Documentation Enhancements:
• Updated README.md with complete project overview and proper git repository URL
• Enhanced Getting Started guide with automated hook installation
• Improved Docker deployment guide with hook installation step
• Reorganized documentation index with better visual hierarchy
• Added repository URL: https://git.supported.systems/claude/claude-code-tracker.git

Technical Improvements:
• Rebuilt Docker containers with all latest changes
• Verified application health and functionality
• Updated all installation examples with correct repository URL
• Improved quick start workflow with 3-step visual process

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Ryan Malloy 2025-08-11 09:30:37 -06:00
parent 50c80596d0
commit 1e1d4a995d
8 changed files with 1038 additions and 129 deletions
Download patch file Download diff file Expand all files Collapse all files

347
README.md
View file

@ -1,116 +1,279 @@
# Claude Code Hook Configurations
# Claude Code Project Tracker
This directory contains various pre-configured hook setups for different use cases:
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.
## Available Configurations
## 🚀 Features
### basic.json
Essential hooks for basic session and tool tracking.
- Session management
- Tool calls
- File modifications
- Conversations
### 🎯 **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
### comprehensive.json
Complete hook setup with all available hook types.
- All performance monitoring
- Code quality tracking
- Learning analytics
- Collaboration insights
- Project intelligence
### 🐳 **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
### essential.json
Minimal setup for core functionality.
### 📊 **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
### developer.json
Focused on development workflow and code quality.
- Essential hooks
- Performance monitoring
- Code quality checks
### 🔒 **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
### power_user.json
Advanced setup for productivity optimization.
- Essential hooks
- Performance tracking
- Workflow analysis
- Project intelligence
## 📦 Quick Start
### research.json
Optimized for learning and exploration.
- Essential hooks
- Learning tracking
- External resource usage
- Knowledge gap analysis
### Option 1: Docker Deployment (Recommended)
### team.json
Team-focused configuration for collaboration.
- Essential hooks
- Collaboration tracking
- Testing workflows
- Project intelligence
```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
## Installation
# 2. Deploy with Docker
docker-compose up -d
1. Choose the configuration that matches your needs
2. Copy the JSON content to your Claude Code settings file:
- macOS/Linux: `~/.config/claude/settings.json`
- Windows: `%APPDATA%\claude\settings.json`
3. Ensure Claude Code Tracker is running on port 8000
4. Start using Claude Code - hooks will automatically track your activity!
# 3. Install hooks on your development machine
export DOMAIN=your-domain.com
./setup-hooks
## Available Hook Variables
# 4. Start using Claude Code!
```
Each hook can use these variables that Claude Code provides:
### Option 2: Local Development
### Session Variables
- `$SESSION_ID` - Current session identifier
- `$TIMESTAMP` - Current timestamp (ISO format)
- `$PWD` - Current working directory
- `$USER` - System username
```bash
# 1. Install dependencies
pip install -r requirements.txt
### Tool Variables
- `$TOOL_NAME` - Name of tool being called
- `$TOOL_PARAMS` - Tool parameters (JSON)
- `$RESULT_STATUS` - Success/error status
- `$EXECUTION_TIME` - Tool execution time (ms)
- `$ERROR_TYPE` - Type of error
- `$ERROR_MESSAGE` - Error message
- `$STACK_TRACE` - Error stack trace
# 2. Initialize database
python init_db.py
### File Variables
- `$FILE_PATH` - Path to modified file
- `$ACTION` - File action (created/modified/deleted)
- `$FILE_SIZE_MB` - File size in megabytes
# 3. Start the server
python main.py
### Context Variables
- `$CONTENT` - Conversation content
- `$CONTEXT` - Current context description
- `$SEARCH_QUERY` - What you're searching for
- `$NEW_PROJECT` - Project being switched to
- `$OLD_PROJECT` - Project being switched from
# 4. Install hooks
export DOMAIN=localhost:8000
./setup-hooks
```
### Performance Variables
- `$MEMORY_MB` - Memory usage in MB
- `$DURATION_MS` - Duration in milliseconds
- `$THRESHOLD_EXCEEDED` - Boolean for threshold alerts
## 🛠️ Installation Scripts
And many more! Each hook type has specific variables available.
### Quick Setup (Most Users)
```bash
export DOMAIN=your-domain.com
./setup-hooks
```
## Customization
### Advanced Installation
```bash
# List available hook profiles
./install-hooks.sh --list
You can modify any configuration by:
1. Adding/removing specific hooks
2. Changing API endpoints or ports
3. Adjusting timeout and retry settings
4. Adding custom metadata to hook calls
# Install specific profile
./install-hooks.sh comprehensive
./install-hooks.sh developer
./install-hooks.sh basic
## Troubleshooting
# Custom domain
./install-hooks.sh -d your-domain.com comprehensive
If hooks aren't working:
1. Ensure Claude Code Tracker server is running
2. Check that curl is installed
3. Verify the API endpoints are accessible
4. Check Claude Code logs for hook execution errors
5. Test individual hooks manually with curl
# Verify installation
./install-hooks.sh --verify
For more help, see the documentation at `/dashboard/docs/hook-setup`.
# 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**