{% extends "base.html" %} {% block title %}{{ title }}{% endblock %} {% block content %}

Frequently Asked Questions

Common questions and troubleshooting guide

General Questions

Claude Code Tracker is a development intelligence system that helps you understand and analyze your coding activity when using Claude Code. It provides:

  • Session Tracking: Monitor your development sessions and time spent
  • Conversation History: Search and browse through all your Claude conversations
  • Project Analytics: Get insights into file modifications, lines changed, and productivity patterns
  • Timeline Visualization: See your development progress over time
  • Data Privacy: All data stays local on your machine

Yes, your data is completely secure!

Claude Code Tracker prioritizes your privacy:

  • Local Storage: All data is stored locally in an SQLite database on your machine
  • No Cloud Services: No data is sent to external servers or cloud services
  • No Network Dependencies: Works completely offline after initial setup
  • Your Control: You have full control over your data and can delete it anytime

Database Location: ./data/tracker.db in your installation directory

Minimum Requirements:
  • Python 3.8 or higher
  • 2GB RAM
  • 100MB free disk space
  • Modern web browser
Supported Platforms:
  • Windows 10/11
  • macOS 10.15+
  • Linux (Ubuntu, CentOS, etc.)
Claude Code CLI must be installed and configured separately.

Setup & Installation

  1. Download: Clone or download the repository
  2. Install Dependencies: Run pip install -r requirements.txt
  3. Start Server: Run python main.py
  4. Access Dashboard: Open http://localhost:8000/dashboard
  5. Import Data: Use the Import Data page to load your existing Claude data
See the Getting Started Guide for detailed instructions.

The claude.json file contains your Claude Code conversation history. Location varies by operating system:

macOS
~/.claude.json
Linux
~/.claude.json
Windows
%USERPROFILE%\.claude.json
Quick commands to locate the file:

macOS/Linux: ls -la ~/.claude.json

Windows: dir %USERPROFILE%\.claude.json

Hooks enable real-time tracking of your Claude Code sessions. Here's the quick setup:

  1. Locate your Claude Code settings file:
    • macOS/Linux: ~/.config/claude/settings.json
    • Windows: %APPDATA%\claude\settings.json
  2. Add hook configuration to the settings file
  3. Ensure Claude Code Tracker server is running
  4. Test by starting a new Claude Code session
Detailed Instructions: See the Hook Setup Guide for complete configuration examples.

Troubleshooting

Common causes and solutions:

File Issues:
  • Verify the JSON file is valid
  • Check file permissions (readable)
  • Ensure file is not corrupted
  • Try with a smaller JSON file first
System Issues:
  • Check available disk space (need ~100MB)
  • Verify database permissions
  • Restart the server and try again
  • Check server logs for detailed errors
Validate your JSON file:
python -m json.tool ~/.claude.json > /dev/null && echo "Valid JSON" || echo "Invalid JSON"

This commonly happens after importing data. The statistics need to be recalculated.

Quick Fix: Run the recalculation script
Run this command in your installation directory:
python recalculate_project_stats.py

This script will:

  • Recalculate session counts and duration
  • Count file modifications and line changes
  • Update last session times
  • Fix all project statistics

Note: The process may take a few minutes for large datasets.

Checklist to troubleshoot hooks:

Server Status:
  • ✅ Tracker server is running
  • ✅ Server accessible at localhost:8000
  • ✅ No firewall blocking connections
  • ✅ Check server logs for errors
Configuration:
  • ✅ Settings.json file exists
  • ✅ Hook URLs are correct
  • ✅ JSON syntax is valid
  • ✅ curl is installed
Test hook manually:
curl -X POST http://localhost:8000/api/sessions/start -H 'Content-Type: application/json' -d '{"project_path": "/test", "start_time": "2024-01-01T12:00:00"}'
See the Hook Setup Guide for detailed troubleshooting steps.

Common issues and solutions:

Error Cause Solution
Port 8000 in use Another service using port Kill process or use different port
Permission denied Insufficient file permissions Check directory permissions
Module not found Missing dependencies Run pip install -r requirements.txt
Database error Corrupted database Delete data/tracker.db and restart
Check what's using port 8000:

macOS/Linux: lsof -i :8000

Windows: netstat -ano | findstr :8000

Usage Questions

The Conversations page provides powerful search capabilities:

Search Options:
  • Text Search: Search message content
  • Project Filter: Filter by specific project
  • Date Range: Filter by time period
  • Role Filter: User vs Assistant messages
Search Tips:
  • Use quotes for exact phrases
  • Search is case-insensitive
  • Combine filters for precise results
  • Use wildcards (*) for partial matches
Pro Tip: Use the project filter to focus on conversations from specific coding projects.

Yes! You have full control over your data:

Database Backup:

The complete database is stored in:

./data/tracker.db

Simply copy this file to create a complete backup.

API Export:

Use the API to export specific data:

  • GET /api/projects (all projects)
  • GET /api/sessions (all sessions)
  • GET /api/conversations (all conversations)
Recommendation: Regularly backup the data/ directory to preserve your development history.

Note: Currently, there's no built-in UI for deleting individual items. This feature is planned for future releases.

Workarounds:

  1. Database Access: Use an SQLite client to directly modify the database
  2. Fresh Start: Delete the entire database file and re-import
  3. API (Advanced): Use custom scripts with the API endpoints
Nuclear option - Clear all data:
rm data/tracker.db && python main.py
This will create a fresh database on next startup

Performance & Optimization

Optimization strategies for large datasets:

Quick Fixes:
  • Use date filters to limit results
  • Filter by specific projects
  • Close unused browser tabs
  • Restart the server periodically
Advanced Options:
  • Increase server memory allocation
  • Use pagination for large results
  • Consider archiving old data
  • Run server on more powerful hardware
Typical Performance: The system handles 10,000+ conversations efficiently. Performance degrades with 50,000+ entries.

Typical storage requirements:

Data Size Conversations Disk Usage Performance
Small < 1,000 < 10MB Excellent
Medium 1,000 - 10,000 10-100MB Good
Large 10,000 - 50,000 100MB-1GB Fair
Very Large > 50,000 > 1GB Consider archiving
Check current database size:

Unix: du -h data/tracker.db

Windows: dir data\tracker.db

Quick Help
Getting Started Hook Setup Guide API Reference
Categories
General Setup Troubleshooting Usage Performance
Top Issues
{% endblock %}