Ryan Malloy
50c80596d0
Features Added: • Docker containerization with multi-stage Python 3.12 build • Caddy reverse proxy integration with automatic SSL • File upload interface for .claude.json imports with preview • Comprehensive hook system with 39+ hook types across 9 categories • Complete documentation system with Docker and import guides Technical Improvements: • Enhanced database models with hook tracking capabilities • Robust file validation and error handling for uploads • Production-ready Docker compose configuration • Health checks and resource limits for containers • Database initialization scripts for containerized deployments Documentation: • Docker Deployment Guide with troubleshooting • Data Import Guide with step-by-step instructions • Updated Getting Started guide with new features • Enhanced documentation index with responsive grid layout 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
562 lines
28 KiB
HTML
562 lines
28 KiB
HTML
{% extends "docs/base.html" %}
|
|
|
|
{% block title %}Data Import Guide - Claude Code Project Tracker{% endblock %}
|
|
|
|
{% block doc_content %}
|
|
<div class="row">
|
|
<div class="col-lg-8">
|
|
<h1 class="mb-4">
|
|
<i class="fas fa-cloud-upload-alt text-primary me-2"></i>
|
|
Data Import Guide
|
|
</h1>
|
|
|
|
<p class="lead">
|
|
Learn how to import your Claude Code usage history using the <code>~/.claude.json</code> file.
|
|
</p>
|
|
|
|
<!-- Overview -->
|
|
<section class="mb-5">
|
|
<h2><i class="fas fa-info-circle me-2"></i>What is .claude.json?</h2>
|
|
<p>
|
|
The <code>~/.claude.json</code> file is automatically created by Claude Code and contains your usage history,
|
|
including project paths, conversation summaries, and usage statistics.
|
|
</p>
|
|
|
|
<div class="card mb-3">
|
|
<div class="card-header bg-light">
|
|
<h5 class="mb-0">Typical Location</h5>
|
|
</div>
|
|
<div class="card-body">
|
|
<div class="row">
|
|
<div class="col-md-4">
|
|
<strong>macOS:</strong><br>
|
|
<code>~/.claude.json</code>
|
|
</div>
|
|
<div class="col-md-4">
|
|
<strong>Linux:</strong><br>
|
|
<code>~/.claude.json</code>
|
|
</div>
|
|
<div class="col-md-4">
|
|
<strong>Windows:</strong><br>
|
|
<code>%USERPROFILE%\.claude.json</code>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
|
|
<!-- Import Methods -->
|
|
<section class="mb-5">
|
|
<h2><i class="fas fa-upload me-2"></i>Import Methods</h2>
|
|
<p>There are two ways to import your Claude Code data:</p>
|
|
|
|
<div class="row">
|
|
<div class="col-md-6">
|
|
<div class="card h-100">
|
|
<div class="card-header bg-primary text-white">
|
|
<h5 class="mb-0"><i class="fas fa-cloud-upload-alt me-1"></i>File Upload</h5>
|
|
</div>
|
|
<div class="card-body">
|
|
<p><strong>Recommended method</strong></p>
|
|
<ul>
|
|
<li>Upload file directly through web interface</li>
|
|
<li>Works with any .claude.json file</li>
|
|
<li>Preview before importing</li>
|
|
<li>No server file system access needed</li>
|
|
</ul>
|
|
<p class="text-success mb-0"><i class="fas fa-check me-1"></i>Best for most users</p>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="col-md-6">
|
|
<div class="card h-100">
|
|
<div class="card-header bg-secondary text-white">
|
|
<h5 class="mb-0"><i class="fas fa-folder-open me-1"></i>File Path</h5>
|
|
</div>
|
|
<div class="card-body">
|
|
<p><strong>Server-side import</strong></p>
|
|
<ul>
|
|
<li>Specify path to .claude.json file</li>
|
|
<li>Uses default ~/.claude.json if no path given</li>
|
|
<li>Requires file system access</li>
|
|
<li>Good for server deployments</li>
|
|
</ul>
|
|
<p class="text-info mb-0"><i class="fas fa-info me-1"></i>For advanced users</p>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
|
|
<!-- File Upload Guide -->
|
|
<section class="mb-5">
|
|
<h2><i class="fas fa-step-forward me-2"></i>File Upload Step-by-Step</h2>
|
|
|
|
<div class="accordion" id="uploadStepsAccordion">
|
|
<div class="accordion-item">
|
|
<h2 class="accordion-header" id="step1">
|
|
<button class="accordion-button" type="button" data-bs-toggle="collapse" data-bs-target="#collapseStep1">
|
|
Step 1: Locate your .claude.json file
|
|
</button>
|
|
</h2>
|
|
<div id="collapseStep1" class="accordion-collapse collapse show" data-bs-parent="#uploadStepsAccordion">
|
|
<div class="accordion-body">
|
|
<p>Find the .claude.json file on your system:</p>
|
|
|
|
<div class="row">
|
|
<div class="col-md-6">
|
|
<div class="card">
|
|
<div class="card-header">
|
|
<strong>macOS/Linux</strong>
|
|
</div>
|
|
<div class="card-body">
|
|
<pre><code class="language-bash"># Open terminal and check if file exists
|
|
ls -la ~/.claude.json
|
|
|
|
# Or use finder/file manager
|
|
open ~/.claude.json</code></pre>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="col-md-6">
|
|
<div class="card">
|
|
<div class="card-header">
|
|
<strong>Windows</strong>
|
|
</div>
|
|
<div class="card-body">
|
|
<pre><code class="language-cmd"># Open Command Prompt
|
|
dir %USERPROFILE%\.claude.json
|
|
|
|
# Or use File Explorer
|
|
explorer %USERPROFILE%</code></pre>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="alert alert-info mt-3">
|
|
<i class="fas fa-lightbulb me-1"></i>
|
|
<strong>Tip:</strong> If the file doesn't exist, use Claude Code for a few sessions to generate usage data first.
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="accordion-item">
|
|
<h2 class="accordion-header" id="step2">
|
|
<button class="accordion-button collapsed" type="button" data-bs-toggle="collapse" data-bs-target="#collapseStep2">
|
|
Step 2: Access the Import Page
|
|
</button>
|
|
</h2>
|
|
<div id="collapseStep2" class="accordion-collapse collapse" data-bs-parent="#uploadStepsAccordion">
|
|
<div class="accordion-body">
|
|
<p>Navigate to the data import page:</p>
|
|
<ol>
|
|
<li>Go to your Claude Code Tracker dashboard</li>
|
|
<li>Click <strong>"Import Data"</strong> in the navigation menu</li>
|
|
<li>Ensure the <strong>"Upload File"</strong> tab is selected (default)</li>
|
|
</ol>
|
|
|
|
<div class="alert alert-success">
|
|
<i class="fas fa-link me-1"></i>
|
|
<strong>Direct Link:</strong> <a href="/dashboard/import" class="alert-link">Go to Import Page</a>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="accordion-item">
|
|
<h2 class="accordion-header" id="step3">
|
|
<button class="accordion-button collapsed" type="button" data-bs-toggle="collapse" data-bs-target="#collapseStep3">
|
|
Step 3: Select and Upload File
|
|
</button>
|
|
</h2>
|
|
<div id="collapseStep3" class="accordion-collapse collapse" data-bs-parent="#uploadStepsAccordion">
|
|
<div class="accordion-body">
|
|
<p>Upload your .claude.json file:</p>
|
|
<ol>
|
|
<li>Click <strong>"Select .claude.json file"</strong> button</li>
|
|
<li>Navigate to and select your .claude.json file</li>
|
|
<li>File information will be displayed (name, size, modified date)</li>
|
|
<li>The upload buttons will become enabled</li>
|
|
</ol>
|
|
|
|
<div class="card mt-3">
|
|
<div class="card-header">
|
|
<strong>File Validation</strong>
|
|
</div>
|
|
<div class="card-body">
|
|
<ul class="mb-0">
|
|
<li>Must be a .json file</li>
|
|
<li>Maximum size: 10 MB</li>
|
|
<li>Must be UTF-8 encoded</li>
|
|
<li>Must contain valid JSON</li>
|
|
</ul>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="accordion-item">
|
|
<h2 class="accordion-header" id="step4">
|
|
<button class="accordion-button collapsed" type="button" data-bs-toggle="collapse" data-bs-target="#collapseStep4">
|
|
Step 4: Preview Import (Recommended)
|
|
</button>
|
|
</h2>
|
|
<div id="collapseStep4" class="accordion-collapse collapse" data-bs-parent="#uploadStepsAccordion">
|
|
<div class="accordion-body">
|
|
<p>Before importing, preview what data will be imported:</p>
|
|
|
|
<ol>
|
|
<li>Click <strong>"Preview Upload"</strong> button</li>
|
|
<li>Review the import summary showing:
|
|
<ul>
|
|
<li>Number of projects to be imported</li>
|
|
<li>Total history entries</li>
|
|
<li>Claude usage statistics</li>
|
|
<li>Sample project paths</li>
|
|
</ul>
|
|
</li>
|
|
<li>Verify the data looks correct</li>
|
|
</ol>
|
|
|
|
<div class="alert alert-warning">
|
|
<i class="fas fa-eye me-1"></i>
|
|
<strong>Preview Benefits:</strong> Catch potential issues before importing and verify data integrity.
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="accordion-item">
|
|
<h2 class="accordion-header" id="step5">
|
|
<button class="accordion-button collapsed" type="button" data-bs-toggle="collapse" data-bs-target="#collapseStep5">
|
|
Step 5: Import Data
|
|
</button>
|
|
</h2>
|
|
<div id="collapseStep5" class="accordion-collapse collapse" data-bs-parent="#uploadStepsAccordion">
|
|
<div class="accordion-body">
|
|
<p>Complete the import process:</p>
|
|
|
|
<ol>
|
|
<li>Click <strong>"Import Upload"</strong> button (or "Looks good - Import this data" after preview)</li>
|
|
<li>Confirm the import when prompted</li>
|
|
<li>Wait for the import to complete</li>
|
|
<li>Review the success summary showing imported counts</li>
|
|
<li>Use the provided links to view your data</li>
|
|
</ol>
|
|
|
|
<div class="card mt-3">
|
|
<div class="card-header">
|
|
<strong>Import Results</strong>
|
|
</div>
|
|
<div class="card-body">
|
|
<p>After successful import, you'll see:</p>
|
|
<ul class="mb-0">
|
|
<li>Number of projects imported</li>
|
|
<li>Number of estimated sessions created</li>
|
|
<li>Number of conversations imported</li>
|
|
<li>Any warnings or errors encountered</li>
|
|
</ul>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
|
|
<!-- What Gets Imported -->
|
|
<section class="mb-5">
|
|
<h2><i class="fas fa-database me-2"></i>What Gets Imported</h2>
|
|
|
|
<div class="row">
|
|
<div class="col-md-6">
|
|
<div class="card h-100">
|
|
<div class="card-header bg-primary text-white">
|
|
<h5 class="mb-0"><i class="fas fa-folder me-1"></i>Projects</h5>
|
|
</div>
|
|
<div class="card-body">
|
|
<ul class="mb-0">
|
|
<li>Project directory paths</li>
|
|
<li>Automatically detected programming languages</li>
|
|
<li>Project names (derived from directory names)</li>
|
|
<li>Creation timestamps (estimated)</li>
|
|
</ul>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="col-md-6">
|
|
<div class="card h-100">
|
|
<div class="card-header bg-success text-white">
|
|
<h5 class="mb-0"><i class="fas fa-chart-line me-1"></i>Usage Statistics</h5>
|
|
</div>
|
|
<div class="card-body">
|
|
<ul class="mb-0">
|
|
<li>Total Claude Code startup count</li>
|
|
<li>First usage timestamp</li>
|
|
<li>Prompt queue usage statistics</li>
|
|
<li>Estimated session distribution over time</li>
|
|
</ul>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="row mt-3">
|
|
<div class="col-md-6">
|
|
<div class="card h-100">
|
|
<div class="card-header bg-info text-white">
|
|
<h5 class="mb-0"><i class="fas fa-comments me-1"></i>Conversations</h5>
|
|
</div>
|
|
<div class="card-body">
|
|
<ul class="mb-0">
|
|
<li>Conversation topic summaries from project history</li>
|
|
<li>Estimated timestamps</li>
|
|
<li>Association with imported projects</li>
|
|
<li>Import metadata for tracking</li>
|
|
</ul>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="col-md-6">
|
|
<div class="card h-100">
|
|
<div class="card-header bg-warning text-dark">
|
|
<h5 class="mb-0"><i class="fas fa-clock me-1"></i>Sessions</h5>
|
|
</div>
|
|
<div class="card-body">
|
|
<ul class="mb-0">
|
|
<li>Estimated sessions based on startup count</li>
|
|
<li>Distributed over your usage period</li>
|
|
<li>Random but realistic session durations</li>
|
|
<li>Associated activity and conversation counts</li>
|
|
</ul>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
|
|
<!-- Data Privacy & Security -->
|
|
<section class="mb-5">
|
|
<h2><i class="fas fa-shield-alt me-2"></i>Data Privacy & Security</h2>
|
|
|
|
<div class="alert alert-success">
|
|
<h5><i class="fas fa-lock me-1"></i>Your Data Stays Local</h5>
|
|
<ul class="mb-0">
|
|
<li>All data is processed and stored locally on your server</li>
|
|
<li>No external services are contacted during import</li>
|
|
<li>Upload is handled securely over HTTPS</li>
|
|
<li>Files are processed in memory and not stored on disk</li>
|
|
<li>Only the structured data is saved to your database</li>
|
|
</ul>
|
|
</div>
|
|
|
|
<div class="row mt-3">
|
|
<div class="col-md-6">
|
|
<div class="card">
|
|
<div class="card-header">
|
|
<strong>File Security</strong>
|
|
</div>
|
|
<div class="card-body">
|
|
<ul class="mb-0">
|
|
<li>10 MB upload size limit</li>
|
|
<li>JSON format validation</li>
|
|
<li>UTF-8 encoding requirement</li>
|
|
<li>No executable code processing</li>
|
|
</ul>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="col-md-6">
|
|
<div class="card">
|
|
<div class="card-header">
|
|
<strong>Data Handling</strong>
|
|
</div>
|
|
<div class="card-body">
|
|
<ul class="mb-0">
|
|
<li>Files processed in memory only</li>
|
|
<li>No temporary file creation</li>
|
|
<li>Immediate cleanup after processing</li>
|
|
<li>Error handling for malformed data</li>
|
|
</ul>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
|
|
<!-- Troubleshooting -->
|
|
<section class="mb-5">
|
|
<h2><i class="fas fa-tools me-2"></i>Troubleshooting</h2>
|
|
|
|
<div class="accordion" id="troubleshootingAccordion">
|
|
<div class="accordion-item">
|
|
<h2 class="accordion-header" id="troubleFile">
|
|
<button class="accordion-button collapsed" type="button" data-bs-toggle="collapse" data-bs-target="#collapseTroubleFile">
|
|
"File must be a JSON file" error
|
|
</button>
|
|
</h2>
|
|
<div id="collapseTroubleFile" class="accordion-collapse collapse" data-bs-parent="#troubleshootingAccordion">
|
|
<div class="accordion-body">
|
|
<p><strong>Cause:</strong> The selected file doesn't have a .json extension.</p>
|
|
<p><strong>Solution:</strong></p>
|
|
<ul>
|
|
<li>Ensure you're selecting the correct .claude.json file</li>
|
|
<li>Check the file extension is exactly ".json"</li>
|
|
<li>On some systems, file extensions might be hidden</li>
|
|
<li>Try copying the file and renaming it to ensure .json extension</li>
|
|
</ul>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="accordion-item">
|
|
<h2 class="accordion-header" id="troubleSize">
|
|
<button class="accordion-button collapsed" type="button" data-bs-toggle="collapse" data-bs-target="#collapseTroubleSize">
|
|
"File too large" error
|
|
</button>
|
|
</h2>
|
|
<div id="collapseTroubleSize" class="accordion-collapse collapse" data-bs-parent="#troubleshootingAccordion">
|
|
<div class="accordion-body">
|
|
<p><strong>Cause:</strong> The .claude.json file is larger than 10 MB.</p>
|
|
<p><strong>Solutions:</strong></p>
|
|
<ul>
|
|
<li>Use the "File Path" import method instead</li>
|
|
<li>Contact your administrator to increase upload limits</li>
|
|
<li>Try importing a newer, smaller version of the file</li>
|
|
<li>Clean up the .claude.json file by backing up old data</li>
|
|
</ul>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="accordion-item">
|
|
<h2 class="accordion-header" id="troubleJson">
|
|
<button class="accordion-button collapsed" type="button" data-bs-toggle="collapse" data-bs-target="#collapseTroubleJson">
|
|
"Invalid JSON" error
|
|
</button>
|
|
</h2>
|
|
<div id="collapseTroubleJson" class="accordion-collapse collapse" data-bs-parent="#troubleshootingAccordion">
|
|
<div class="accordion-body">
|
|
<p><strong>Cause:</strong> The file contains malformed JSON data.</p>
|
|
<p><strong>Solutions:</strong></p>
|
|
<ul>
|
|
<li>Check if the file was corrupted during transfer</li>
|
|
<li>Try re-generating the file by using Claude Code again</li>
|
|
<li>Use a JSON validator to check the file structure</li>
|
|
<li>Ensure the file wasn't partially downloaded</li>
|
|
</ul>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="accordion-item">
|
|
<h2 class="accordion-header" id="troubleImport">
|
|
<button class="accordion-button collapsed" type="button" data-bs-toggle="collapse" data-bs-target="#collapseTroubleImport">
|
|
Import completed but no data appears
|
|
</button>
|
|
</h2>
|
|
<div id="collapseTroubleImport" class="accordion-collapse collapse" data-bs-parent="#troubleshootingAccordion">
|
|
<div class="accordion-body">
|
|
<p><strong>Possible causes and solutions:</strong></p>
|
|
<ul>
|
|
<li><strong>Empty file:</strong> The .claude.json file might be empty or contain no project data</li>
|
|
<li><strong>Duplicate import:</strong> Data might already exist and wasn't imported again (this is normal)</li>
|
|
<li><strong>Filtering:</strong> Check if any filters are applied in the project view</li>
|
|
<li><strong>Refresh:</strong> Try refreshing the page or clicking the "Refresh" button</li>
|
|
<li><strong>Check import results:</strong> Review the import summary for any warnings or errors</li>
|
|
</ul>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
|
|
<!-- Advanced Topics -->
|
|
<section class="mb-5">
|
|
<h2><i class="fas fa-cogs me-2"></i>Advanced Topics</h2>
|
|
|
|
<div class="row">
|
|
<div class="col-md-6">
|
|
<div class="card h-100">
|
|
<div class="card-header">
|
|
<h5 class="mb-0">Multiple Imports</h5>
|
|
</div>
|
|
<div class="card-body">
|
|
<p>The import system prevents duplicates:</p>
|
|
<ul>
|
|
<li>Projects are identified by path</li>
|
|
<li>Duplicate projects won't be re-created</li>
|
|
<li>Safe to import multiple times</li>
|
|
<li>New data will be added to existing projects</li>
|
|
</ul>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="col-md-6">
|
|
<div class="card h-100">
|
|
<div class="card-header">
|
|
<h5 class="mb-0">Data Estimation</h5>
|
|
</div>
|
|
<div class="card-body">
|
|
<p>Since .claude.json has limited data:</p>
|
|
<ul>
|
|
<li>Session times are estimated</li>
|
|
<li>Durations are randomized realistically</li>
|
|
<li>Activity counts are approximated</li>
|
|
<li>Language detection uses file system</li>
|
|
</ul>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
</div>
|
|
|
|
<!-- Sidebar -->
|
|
<div class="col-lg-4">
|
|
<div class="card sticky-top" style="top: 1rem;">
|
|
<div class="card-header">
|
|
<h5 class="mb-0"><i class="fas fa-rocket me-1"></i>Quick Start</h5>
|
|
</div>
|
|
<div class="card-body">
|
|
<ol class="mb-3">
|
|
<li>Find your <code>~/.claude.json</code> file</li>
|
|
<li><a href="/dashboard/import">Go to Import Page</a></li>
|
|
<li>Click "Select .claude.json file"</li>
|
|
<li>Choose your file</li>
|
|
<li>Click "Preview Upload"</li>
|
|
<li>Click "Import Upload"</li>
|
|
</ol>
|
|
|
|
<div class="alert alert-success">
|
|
<i class="fas fa-lightbulb me-1"></i>
|
|
<strong>Pro Tip:</strong> Always preview before importing to catch any issues early.
|
|
</div>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="card mt-3">
|
|
<div class="card-header">
|
|
<h5 class="mb-0"><i class="fas fa-question-circle me-1"></i>Need Help?</h5>
|
|
</div>
|
|
<div class="card-body">
|
|
<p>Common import questions:</p>
|
|
<ul class="mb-0">
|
|
<li><a href="#troubleshootingAccordion">Troubleshooting Guide</a></li>
|
|
<li><a href="/dashboard/docs/faq">FAQ Page</a></li>
|
|
<li><a href="/dashboard/docs/api-reference">API Documentation</a></li>
|
|
</ul>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
{% endblock %} |