claude-code-templates 1.13.1 → 1.14.0

package/README.md

@@ -7,269 +7,74 @@
 
 # Claude Code Templates
 
-**CLI tool for configuring and monitoring Claude Code** - Quick setup for any project with framework-specific commands and real-time monitoring dashboard. Open source and runs locally.
+**CLI tool for configuring and monitoring Claude Code** - Quick setup for any project with framework-specific commands and real-time monitoring dashboard.
 
-## 📋 Quick Start
+## 🚀 Quick Start
 
 ```bash
-# Run the tool (no installation required!)
+# Interactive setup (recommended)
 npx claude-code-templates@latest
-```
-
-## Core Features
-
-### 📊 Real-time Analytics Dashboard
-Monitor and optimize your Claude Code agents with our comprehensive analytics dashboard:
-- **Live Session Tracking**: See active conversations and their status in real-time
-- **Real-time State Detection**: "Claude Code working...", "User typing...", "Awaiting user input..."
-- **Usage Statistics**: Total sessions, tokens, and project activity with interactive charts
-- **Conversation History**: Complete session logs with export capabilities (CSV/JSON)
-- **Browser Notifications**: Get notified when Claude is waiting for your input
-- **Performance Monitoring**: Track Claude Code agent performance and optimization opportunities
-- **Web Interface**: Clean, terminal-style dashboard at `http://localhost:3333`
-
-### 🔍 Comprehensive Health Check
-Complete system validation and configuration verification:
-- **System Requirements**: Validate OS, Node.js, memory, and network connectivity
-- **Claude Code Setup**: Verify installation, authentication, and permissions
-- **Project Configuration**: Check project structure and configuration files
-- **Custom Commands**: Validate slash commands and syntax
-- **Hooks Configuration**: Verify automation hooks and command availability
-- **Interactive Results**: Real-time progress with immediate feedback and recommendations
-- **Health Score**: Overall system health percentage with actionable insights
-
-### 📋 Smart Project Setup
-Intelligent project configuration with framework-specific commands:
-- **Auto-Detection**: Automatically detect your project type and suggest optimal configurations
-- **Quick Setup**: Framework-specific commands for testing, linting, building, debugging, and deployment
-- **Optimized Workflows**: Pre-configured commands tailored to your development stack
-- **Best Practices**: Industry-standard configurations and development patterns
-
-## What Gets Installed
-
-### Core Files
-- **`CLAUDE.md`** - Main configuration file with language-specific best practices
-- **`.claude/settings.json`** - Automation hooks and Claude Code settings
-- **`.claude/commands/`** - Custom commands for common development tasks
-- **`.mcp.json`** - Model Context Protocol server configurations
-
-## Supported Languages & Frameworks
-
-| Language | Frameworks | Status | Commands | Hooks | MCP |
-|----------|------------|---------|----------|--------|-----|
-| **JavaScript/TypeScript** | React, Vue, Angular, Node.js | ✅ Ready | 7+ | 9+ | 4+ |
-| **Python** | Django, Flask, FastAPI | ✅ Ready | 5+ | 8+ | 4+ |
-| **Common** | Universal | ✅ Ready | 2+ | 1+ | 4+ |
-| **Go** | Gin, Echo, Fiber | 🚧 Coming Soon | - | - | - |
-| **Rust** | Axum, Warp, Actix | 🚧 Coming Soon | - | - | - |
-
-## Usage Examples
-
-### Interactive Setup (Recommended)
-```bash
-cd my-react-app
-npx claude-code-templates
-# Choose between Analytics Dashboard, Health Check, or Project Setup
-```
 
-### Analytics Dashboard
-```bash
-# Launch real-time analytics dashboard
-npx claude-code-templates --analytics
+# Real-time analytics dashboard
+npx claude-code-templates@latest --analytics
 
-# Launch chats/conversations dashboard (opens directly to conversations)
-npx claude-code-templates --chats
-npx claude-code-templates --agents
+# System health check
+npx claude-code-templates@latest --health-check
 ```
 
-### Health Check
-```bash
-# Run comprehensive system validation
-npx claude-code-templates --health-check
-npx claude-code-templates --health
-npx claude-code-templates --check
-npx claude-code-templates --verify
-```
+## ✨ Core Features
 
-### Framework-Specific Quick Setup
-```bash
-# React + TypeScript project
-npx claude-code-templates --language javascript-typescript --framework react --yes
+- **📋 Smart Project Setup** - Auto-detect and configure any project with framework-specific commands
+- **📊 Real-time Analytics** - Monitor Claude Code sessions with live state detection and performance metrics
+- **🔍 Health Check** - Comprehensive system validation with actionable recommendations
+- **🧩 Individual Components** - Install specialized agents, commands, and MCPs individually
 
-# Python + Django project
-npx claude-code-templates --language python --framework django --yes
-```
-
-### Analysis Tools
-```bash
-# Analyze existing commands 
-npx claude-code-templates --commands-stats
+## 🎯 What You Get
 
-# Analyze automation hooks
-npx claude-code-templates --hooks-stats
-
-# Analyze MCP server configurations 
-npx claude-code-templates --mcps-stats
-```
-
-### Alternative Commands
-All these commands work exactly the same way:
-
-```bash
-npx claude-code-templates    # ✅ Recommended (package name)
-npx cct                      # ⚡ Super short (3 letters)
-npx claude-setup             # Setup-style command
-npx create-claude-config     # Create-style command
-```
+| Component | Description | Example |
+|-----------|-------------|---------|
+| **CLAUDE.md** | Project-specific Claude Code configuration | Framework best practices, coding standards |
+| **Commands** | Custom slash commands for development tasks | `/generate-tests`, `/check-file`, `/optimize-bundle` |
+| **Agents** | AI specialists for specific domains | API security audit, React performance, database optimization |
+| **MCPs** | External service integrations | GitHub, databases, development tools |
+| **Analytics** | Real-time monitoring dashboard | Live session tracking, usage statistics, exports |
 
-## CLI Options
+## 🛠️ Supported Technologies
 
-| Option | Description | Example |
-|--------|-------------|---------|
-| `-l, --language` | Specify programming language | `--language python` |
-| `-f, --framework` | Specify framework | `--framework react` |
-| `-d, --directory` | Target directory | `--directory /path/to/project` |
-| `-y, --yes` | Skip prompts and use defaults | `--yes` |
-| `--dry-run` | Show what would be installed | `--dry-run` |
-| `--analytics` | Launch real-time analytics dashboard | `--analytics` |
-| `--chats` | Launch chats/conversations dashboard | `--chats` |
-| `--agents` | Launch agents dashboard (alias for chats) | `--agents` |
-| `--health-check` | Run comprehensive system validation | `--health-check` |
-| `--health` | Run system health check (alias) | `--health` |
-| `--check` | Run system validation (alias) | `--check` |
-| `--verify` | Verify system configuration (alias) | `--verify` |
-| `--commands-stats` | Analyze existing commands | `--commands-stats` |
-| `--hooks-stats` | Analyze automation hooks | `--hooks-stats` |
-| `--mcps-stats` | Analyze MCP server configurations | `--mcps-stats` |
-| `--help` | Show help information | `--help` |
+| Language | Frameworks | Status |
+|----------|------------|---------|
+| **JavaScript/TypeScript** | React, Vue, Angular, Node.js | ✅ Ready |
+| **Python** | Django, Flask, FastAPI | ✅ Ready |
+| **Common** | Universal configurations | ✅ Ready |
+| **Go** | Gin, Echo, Fiber | 🚧 Coming Soon |
+| **Rust** | Axum, Warp, Actix | 🚧 Coming Soon |
 
-## 🏗️ Modular Architecture
+## 📖 Documentation
 
-The analytics dashboard is built with a modern, scalable modular architecture designed for performance and maintainability.
+**[📚 Complete Documentation](https://aitmpl.com/docu/)** - Comprehensive guides, examples, and API reference
 
-### Backend Architecture
-
-#### Core Modules
-- **`StateCalculator`** - Advanced conversation state detection with real-time analysis
-- **`ProcessDetector`** - Running process detection and conversation linking
-- **`ConversationAnalyzer`** - Message parsing, token counting, and conversation analysis
-- **`FileWatcher`** - Real-time file system monitoring with efficient change detection
-- **`DataCache`** - Multi-level caching system with smart invalidation strategies
-
-#### Data Layer
-- **`DataCache`** - Intelligent caching with file content, parsed data, and computation result caching
-- **Performance Monitoring** - Request tracking, memory monitoring, and system health metrics
-
-#### Notification System
-- **`WebSocketServer`** - Real-time WebSocket communication with client management
-- **`NotificationManager`** - Event-driven notification system with subscription management
-- **Real-time Updates** - Live conversation state changes and data refresh notifications
-
-#### Performance & Monitoring
-- **`PerformanceMonitor`** - Comprehensive performance tracking and system health monitoring
-- **Express Middleware** - Request timing, error tracking, and API performance metrics
-- **WebSocket Monitoring** - Connection tracking, message metrics, and client health monitoring
-
-### Frontend Architecture
-
-#### Modular Components
-- **`Dashboard`** - Main orchestration component with state management integration
-- **`ConversationTable`** - Interactive conversation display with real-time status updates
-- **`Charts`** - Dynamic data visualization with Chart.js integration
-- **`StateService`** - Reactive state management with subscriber patterns
-- **`DataService`** - API communication with intelligent caching and real-time integration
-- **`WebSocketService`** - Real-time communication with automatic reconnection
-
-#### Real-time Features
-- **Live State Detection** - Real-time conversation status: "Claude working...", "User typing...", "Awaiting input..."
-- **Auto-refresh** - Smart polling with WebSocket fallback for seamless data updates
-- **Browser Notifications** - Desktop notifications for important state changes
-- **Responsive Design** - Mobile-friendly interface with real-time data synchronization
-
-### Performance Optimizations
-
-#### Caching Strategy
-- **File Content Cache** - Reduces disk I/O with timestamp-based invalidation
-- **Parsed Data Cache** - Stores analyzed conversation data with dependency tracking
-- **API Response Cache** - Client-side caching with TTL and smart refresh
-- **Computation Cache** - Caches expensive calculations with automatic invalidation
-
-#### Real-time Efficiency
-- **WebSocket Integration** - Eliminates polling overhead for live updates
-- **Smart Refresh** - Only updates changed data with differential loading
-- **Process Detection** - Efficient system process monitoring without performance impact
-- **Memory Management** - Automatic cleanup of old metrics and cached data
-
-### Testing Framework
-
-#### Comprehensive Test Suite
-- **Unit Tests** - Individual module testing with 80%+ coverage requirement
-- **Integration Tests** - End-to-end system testing with real data scenarios
-- **Performance Tests** - Load testing and performance regression detection
-- **WebSocket Tests** - Real-time communication testing with mock clients
-
-#### Test Coverage
-- **Backend Modules**: StateCalculator, DataCache, WebSocketServer, PerformanceMonitor
-- **Frontend Services**: DataService, StateService, WebSocketService  
-- **Integration Testing**: Complete analytics system with real conversation data
-- **Performance Testing**: Concurrent operations, memory usage, and response times
-
-### Development Benefits
-
-#### Scalability
-- **Modular Design** - Easy to extend with new features and integrations
-- **Dependency Injection** - Loose coupling for flexible testing and development
-- **Event-driven Architecture** - Scalable notification system for future enhancements
-
-#### Maintainability  
-- **Separation of Concerns** - Clear boundaries between data, business logic, and presentation
-- **Comprehensive Logging** - Detailed performance and error tracking for debugging
-- **Type Safety** - Consistent error handling and data validation throughout
-
-#### Performance
-- **Multi-level Caching** - Optimized data access patterns with intelligent invalidation
-- **Real-time Updates** - WebSocket-based communication eliminates polling overhead
-- **Memory Optimization** - Automatic cleanup and configurable memory thresholds
-- **Request Monitoring** - Complete visibility into system performance and bottlenecks
-
-## Safety Features
-
-- **Automatic Backups**: Existing files are backed up before changes
-- **Confirmation Required**: Always asks before making changes (unless `--yes` flag)
-- **Dry Run Mode**: Preview installation with `--dry-run`
-- **Cancel Anytime**: Press Ctrl+C or answer 'No' to cancel
-
-## What Makes This Special?
-
-### Before (Manual Setup)
-- Hours of configuration research
-- Manual CLAUDE.md creation
-- Framework-specific command setup
-- Automation hook configuration
-- MCP server integration
-
-### After (With Templates)
-```bash
-npx claude-code-templates --language javascript-typescript --framework react --yes
-# ✅ Done in 30 seconds!
-```
+Quick links:
+- [Getting Started](https://aitmpl.com/docu/docs/intro) - Installation and first steps
+- [Project Setup](https://aitmpl.com/docu/docs/project-setup/interactive-setup) - Configure your projects
+- [Analytics Dashboard](https://aitmpl.com/docu/docs/analytics/overview) - Real-time monitoring
+- [Individual Components](https://aitmpl.com/docu/docs/components/overview) - Agents, Commands, MCPs
+- [CLI Options](https://aitmpl.com/docu/docs/cli-options) - All available commands
 
 ## 🤝 Contributing
 
-We welcome contributions from the open source community! 
-
-**See our [GitHub repository](https://github.com/davila7/claude-code-templates) for detailed guidelines**
+We welcome contributions! Browse available templates and components at **[aitmpl.com](https://aitmpl.com)**, then check our [contributing guidelines](https://github.com/davila7/claude-code-templates/blob/main/CONTRIBUTING.md).
 
 ## 📄 License
 
-This project is licensed under the MIT License.
+MIT License - see the [LICENSE](LICENSE) file for details.
 
-## 📞 Support
+## 🔗 Links
 
-- **🐛 Issues**: [Report bugs or request features](https://github.com/davila7/claude-code-templates/issues)
-- **💬 Discussions**: [Join community discussions](https://github.com/davila7/claude-code-templates/discussions)
-- **📖 Documentation**: [Claude Code Official Docs](https://docs.anthropic.com/en/docs/claude-code)
+- **🌐 Browse Components**: [aitmpl.com](https://aitmpl.com)
+- **📚 Documentation**: [aitmpl.com/docu](https://aitmpl.com/docu)
+- **🐛 Issues**: [GitHub Issues](https://github.com/davila7/claude-code-templates/issues)
+- **💬 Discussions**: [GitHub Discussions](https://github.com/davila7/claude-code-templates/discussions)
 
 ---
 
-**⭐ Found this useful? Give us a star on [GitHub](https://github.com/davila7/claude-code-templates) to support the project!**
+**⭐ Found this useful? Give us a star to support the project!**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-templates",
-  "version": "1.13.1",
+  "version": "1.14.0",
   "description": "CLI tool to setup Claude Code configurations with framework-specific commands, automation hooks and MCP Servers for your projects",
   "main": "src/index.js",
   "bin": {

package/src/analytics-web/components/AgentsPage.js

@@ -16,6 +16,9 @@ class AgentsPage {
     };
     this.isInitialized = false;
     
+    // Initialize header component
+    this.headerComponent = null;
+    
     // Pagination state for conversations
     this.pagination = {
       currentPage: 0,
@@ -586,22 +589,8 @@ class AgentsPage {
   async render() {
     this.container.innerHTML = `
       <div class="agents-page">
-        <!-- Page Header -->
-        <div class="page-header conversations-header">
-          <div class="header-content">
-            <div class="header-left">
-              <div class="status-header">
-                <span class="session-timer-status-dot active"></span>
-                <h1 class="page-title">
-                  Claude Code web UI
-                </h1>
-              </div>
-              <div class="page-subtitle">
-                Monitor and analyze Claude Code agent interactions in real-time
-              </div>
-            </div>
-          </div>
-        </div>
+        <!-- Page Header (will be replaced by HeaderComponent) -->
+        <div id="agents-header-container"></div>
 
         <!-- Filters Section -->
         <div class="conversations-filters">
@@ -784,6 +773,28 @@ class AgentsPage {
 
     this.bindEvents();
     this.setupInfiniteScroll();
+    this.initializeHeaderComponent();
+  }
+
+  /**
+   * Initialize the header component
+   */
+  initializeHeaderComponent() {
+    const headerContainer = this.container.querySelector('#agents-header-container');
+    if (headerContainer && typeof HeaderComponent !== 'undefined') {
+      this.headerComponent = new HeaderComponent(headerContainer, {
+        title: 'Claude Code Chats',
+        subtitle: 'Monitor and analyze Claude Code agent interactions in real-time',
+        version: 'v1.13.2', // Fallback version
+        showVersionBadge: true,
+        showLastUpdate: true,
+        showThemeSwitch: true,
+        showGitHubLink: true,
+        dataService: this.dataService // Pass DataService for dynamic version loading
+      });
+      
+      this.headerComponent.render();
+    }
   }
 
   /**
@@ -4716,6 +4727,12 @@ class AgentsPage {
    * Destroy agents page
    */
   destroy() {
+    // Cleanup header component
+    if (this.headerComponent) {
+      this.headerComponent.destroy();
+      this.headerComponent = null;
+    }
+    
     // Cleanup components
     Object.values(this.components).forEach(component => {
       if (component.destroy) {

package/src/analytics-web/components/DashboardPage.js

@@ -13,6 +13,9 @@ class DashboardPage {
     this.refreshInterval = null;
     this.isInitialized = false;
     
+    // Initialize header component
+    this.headerComponent = null;
+    
     // Subscribe to state changes
     this.unsubscribe = this.stateService.subscribe(this.handleStateChange.bind(this));
   }
@@ -118,42 +121,8 @@ class DashboardPage {
   async render() {
     this.container.innerHTML = `
       <div class="dashboard-page">
-        <!-- Page Header -->
-        <div class="page-header">
-          <div class="header-content">
-            <div class="header-left">
-              <div class="status-header">
-                <span class="session-timer-status-dot active" id="session-status-dot"></span>
-                <h1 class="page-title">
-                  Claude Code Analytics Dashboard
-                  <span class="version-badge">v1.10.1</span>
-                </h1>
-              </div>
-              <div class="page-subtitle">
-                Real-time monitoring and analytics for Claude Code sessions
-              </div>
-              <div class="last-update-header">
-                <span class="last-update-label">last update:</span>
-                <span id="last-update-header-text">Never</span>
-              </div>
-            </div>
-            <div class="header-right">
-              <div class="theme-switch-container" title="Toggle light/dark theme">
-                <div class="theme-switch" id="header-theme-switch">
-                  <div class="theme-switch-track">
-                    <div class="theme-switch-thumb" id="header-theme-switch-thumb">
-                      <span class="theme-switch-icon">🌙</span>
-                    </div>
-                  </div>
-                </div>
-              </div>
-              <a href="https://github.com/anthropics/claude-code-templates" target="_blank" class="github-link" title="Star on GitHub">
-                <span class="github-icon">⭐</span>
-                Star on GitHub
-              </a>
-            </div>
-          </div>
-        </div>
+        <!-- Page Header (will be replaced by HeaderComponent) -->
+        <div id="dashboard-header-container"></div>
 
         <!-- Action Buttons -->
         <div class="action-buttons-container">
@@ -394,7 +363,28 @@ class DashboardPage {
     `;
 
     this.bindEvents();
-    this.initializeTheme();
+    this.initializeHeaderComponent();
+  }
+
+  /**
+   * Initialize the header component
+   */
+  initializeHeaderComponent() {
+    const headerContainer = this.container.querySelector('#dashboard-header-container');
+    if (headerContainer && typeof HeaderComponent !== 'undefined') {
+      this.headerComponent = new HeaderComponent(headerContainer, {
+        title: 'Claude Code Analytics Dashboard',
+        subtitle: 'Real-time monitoring and analytics for Claude Code sessions',
+        version: 'v1.13.2', // Fallback version
+        showVersionBadge: true,
+        showLastUpdate: true,
+        showThemeSwitch: true,
+        showGitHubLink: true,
+        dataService: this.dataService // Pass DataService for dynamic version loading
+      });
+      
+      this.headerComponent.render();
+    }
   }
 
   /**
@@ -884,11 +874,6 @@ class DashboardPage {
       retryBtn.addEventListener('click', () => this.loadInitialData());
     }
 
-    // Theme toggle (header)
-    const headerThemeSwitch = this.container.querySelector('#header-theme-switch');
-    if (headerThemeSwitch) {
-      headerThemeSwitch.addEventListener('click', () => this.toggleTheme());
-    }
   }
 
   /**
@@ -2105,74 +2090,13 @@ class DashboardPage {
     }
   }
 
-  /**
-   * Initialize theme from localStorage
-   */
-  initializeTheme() {
-    const savedTheme = localStorage.getItem('claude-analytics-theme') || 'dark';
-    const body = document.body;
-    const headerThumb = this.container.querySelector('#header-theme-switch-thumb');
-    const headerIcon = headerThumb?.querySelector('.theme-switch-icon');
-    
-    body.setAttribute('data-theme', savedTheme);
-    if (headerThumb && headerIcon) {
-      if (savedTheme === 'light') {
-        headerThumb.classList.add('light');
-        headerIcon.textContent = '☀️';
-      } else {
-        headerThumb.classList.remove('light');
-        headerIcon.textContent = '🌙';
-      }
-    }
-  }
-
-  /**
-   * Toggle theme between light and dark
-   */
-  toggleTheme() {
-    const body = document.body;
-    const headerThumb = this.container.querySelector('#header-theme-switch-thumb');
-    const headerIcon = headerThumb?.querySelector('.theme-switch-icon');
-    
-    // Also sync with global theme switch
-    const globalThumb = document.getElementById('themeSwitchThumb');
-    const globalIcon = globalThumb?.querySelector('.theme-switch-icon');
-    
-    const isLight = body.getAttribute('data-theme') === 'light';
-    const newTheme = isLight ? 'dark' : 'light';
-    
-    body.setAttribute('data-theme', newTheme);
-    
-    // Update header theme switch
-    if (headerThumb && headerIcon) {
-      headerThumb.classList.toggle('light', newTheme === 'light');
-      headerIcon.textContent = newTheme === 'light' ? '☀️' : '🌙';
-    }
-    
-    // Sync with global theme switch
-    if (globalThumb && globalIcon) {
-      globalThumb.classList.toggle('light', newTheme === 'light');
-      globalIcon.textContent = newTheme === 'light' ? '☀️' : '🌙';
-    }
-    
-    localStorage.setItem('claude-analytics-theme', newTheme);
-  }
 
   /**
    * Update last update time
    */
   updateLastUpdateTime() {
-    const currentTime = new Date().toLocaleTimeString();
-    
-    // Update both locations
-    const lastUpdateText = this.container.querySelector('#last-update-text');
-    const lastUpdateHeaderText = this.container.querySelector('#last-update-header-text');
-    
-    if (lastUpdateText) {
-      lastUpdateText.textContent = currentTime;
-    }
-    if (lastUpdateHeaderText) {
-      lastUpdateHeaderText.textContent = currentTime;
+    if (this.headerComponent) {
+      this.headerComponent.updateLastUpdateTime();
     }
   }
 
@@ -2252,6 +2176,12 @@ class DashboardPage {
   destroy() {
     this.stopPeriodicRefresh();
     
+    // Cleanup header component
+    if (this.headerComponent) {
+      this.headerComponent.destroy();
+      this.headerComponent = null;
+    }
+    
     // Cleanup Chart.js instances specifically
     if (this.components.tokenChart) {
       this.components.tokenChart.destroy();

package/src/analytics-web/components/HeaderComponent.js

@@ -0,0 +1,307 @@
+/**
+ * HeaderComponent - Unified header for all analytics pages
+ * Provides consistent branding, navigation, and controls across the application
+ */
+class HeaderComponent {
+  constructor(container, options = {}) {
+    this.container = container;
+    this.options = {
+      title: options.title || 'Claude Code Analytics Dashboard',
+      subtitle: options.subtitle || 'Real-time monitoring and analytics for Claude Code sessions',
+      showVersionBadge: options.showVersionBadge !== false,
+      showLastUpdate: options.showLastUpdate !== false,
+      showThemeSwitch: options.showThemeSwitch !== false,
+      showGitHubLink: options.showGitHubLink !== false,
+      version: options.version || 'v1.13.2', // Default fallback
+      customActions: options.customActions || [],
+      dataService: options.dataService || null, // DataService for dynamic version loading
+      ...options
+    };
+    
+    this.lastUpdateTime = null;
+    this.updateInterval = null;
+    this.actualVersion = this.options.version; // Will be updated dynamically
+  }
+
+  /**
+   * Render the header component
+   */
+  render() {
+    const headerHTML = `
+      <div class="page-header">
+        <div class="header-content">
+          <div class="header-left">
+            <div class="status-header">
+              <span class="session-timer-status-dot active" id="session-status-dot"></span>
+              <h1 class="page-title">
+                ${this.options.title}
+                ${this.options.showVersionBadge ? `<span class="version-badge" id="version-badge">${this.actualVersion}</span>` : ''}
+              </h1>
+            </div>
+            <div class="page-subtitle">
+              ${this.options.subtitle}
+            </div>
+            ${this.options.showLastUpdate ? `
+              <div class="last-update-header">
+                <span class="last-update-label">last update:</span>
+                <span id="last-update-header-text">Never</span>
+              </div>
+            ` : ''}
+          </div>
+          <div class="header-right">
+            ${this.options.showThemeSwitch ? `
+              <div class="theme-switch-container" title="Toggle light/dark theme">
+                <div class="theme-switch" id="header-theme-switch">
+                  <div class="theme-switch-track">
+                    <div class="theme-switch-thumb" id="header-theme-switch-thumb">
+                      <span class="theme-switch-icon">🌙</span>
+                    </div>
+                  </div>
+                </div>
+              </div>
+            ` : ''}
+            ${this.options.showGitHubLink ? `
+              <a href="https://github.com/davila7/claude-code-templates" target="_blank" class="github-link" title="Star on GitHub">
+                <span class="github-icon">⭐</span>
+                Star on GitHub
+              </a>
+            ` : ''}
+            ${this.renderCustomActions()}
+          </div>
+        </div>
+      </div>
+    `;
+
+    this.container.innerHTML = headerHTML;
+    this.bindEvents();
+    this.initializeTheme();
+    
+    if (this.options.showLastUpdate) {
+      this.updateLastUpdateTime();
+      this.startUpdateInterval();
+    }
+
+    // Load version dynamically if DataService is available
+    if (this.options.dataService) {
+      this.loadVersion();
+    }
+  }
+
+  /**
+   * Render custom actions in header
+   */
+  renderCustomActions() {
+    if (!this.options.customActions || this.options.customActions.length === 0) {
+      return '';
+    }
+
+    return this.options.customActions.map(action => `
+      <button class="header-action-btn" id="${action.id}" title="${action.title || action.label}">
+        ${action.icon ? `<span class="btn-icon">${action.icon}</span>` : ''}
+        ${action.label}
+      </button>
+    `).join('');
+  }
+
+  /**
+   * Bind event listeners
+   */
+  bindEvents() {
+    // Theme toggle
+    if (this.options.showThemeSwitch) {
+      const themeSwitch = this.container.querySelector('#header-theme-switch');
+      if (themeSwitch) {
+        themeSwitch.addEventListener('click', () => this.toggleTheme());
+      }
+    }
+
+    // Custom action handlers
+    this.options.customActions.forEach(action => {
+      const btn = this.container.querySelector(`#${action.id}`);
+      if (btn && action.handler) {
+        btn.addEventListener('click', action.handler);
+      }
+    });
+  }
+
+  /**
+   * Initialize theme from localStorage
+   */
+  initializeTheme() {
+    if (!this.options.showThemeSwitch) return;
+
+    const savedTheme = localStorage.getItem('claude-analytics-theme') || 'dark';
+    const body = document.body;
+    const headerThumb = this.container.querySelector('#header-theme-switch-thumb');
+    const headerIcon = headerThumb?.querySelector('.theme-switch-icon');
+    
+    body.setAttribute('data-theme', savedTheme);
+    if (headerThumb && headerIcon) {
+      if (savedTheme === 'light') {
+        headerThumb.classList.add('light');
+        headerIcon.textContent = '☀️';
+      } else {
+        headerThumb.classList.remove('light');
+        headerIcon.textContent = '🌙';
+      }
+    }
+  }
+
+  /**
+   * Toggle theme between light and dark
+   */
+  toggleTheme() {
+    const body = document.body;
+    const headerThumb = this.container.querySelector('#header-theme-switch-thumb');
+    const headerIcon = headerThumb?.querySelector('.theme-switch-icon');
+    
+    // Also sync with global theme switch if exists
+    const globalThumb = document.getElementById('themeSwitchThumb');
+    const globalIcon = globalThumb?.querySelector('.theme-switch-icon');
+    
+    const isLight = body.getAttribute('data-theme') === 'light';
+    const newTheme = isLight ? 'dark' : 'light';
+    
+    body.setAttribute('data-theme', newTheme);
+    
+    // Update header theme switch
+    if (headerThumb && headerIcon) {
+      headerThumb.classList.toggle('light', newTheme === 'light');
+      headerIcon.textContent = newTheme === 'light' ? '☀️' : '🌙';
+    }
+    
+    // Sync with global theme switch
+    if (globalThumb && globalIcon) {
+      globalThumb.classList.toggle('light', newTheme === 'light');
+      globalIcon.textContent = newTheme === 'light' ? '☀️' : '🌙';
+    }
+    
+    localStorage.setItem('claude-analytics-theme', newTheme);
+  }
+
+  /**
+   * Update last update time
+   */
+  updateLastUpdateTime() {
+    if (!this.options.showLastUpdate) return;
+
+    const currentTime = new Date().toLocaleTimeString();
+    const lastUpdateText = this.container.querySelector('#last-update-header-text');
+    
+    if (lastUpdateText) {
+      lastUpdateText.textContent = currentTime;
+    }
+    
+    this.lastUpdateTime = currentTime;
+  }
+
+  /**
+   * Start periodic update of timestamp
+   */
+  startUpdateInterval() {
+    if (this.updateInterval) {
+      clearInterval(this.updateInterval);
+    }
+    
+    // Update every 30 seconds
+    this.updateInterval = setInterval(() => {
+      this.updateLastUpdateTime();
+    }, 30000);
+  }
+
+  /**
+   * Stop update interval
+   */
+  stopUpdateInterval() {
+    if (this.updateInterval) {
+      clearInterval(this.updateInterval);
+      this.updateInterval = null;
+    }
+  }
+
+  /**
+   * Load version dynamically from backend
+   */
+  async loadVersion() {
+    if (!this.options.dataService) return;
+
+    try {
+      const versionData = await this.options.dataService.getVersion();
+      if (versionData && versionData.version) {
+        this.actualVersion = `v${versionData.version}`;
+        this.updateVersionBadge();
+      }
+    } catch (error) {
+      console.error('Error loading version:', error);
+    }
+  }
+
+  /**
+   * Update version badge in the DOM
+   */
+  updateVersionBadge() {
+    const versionBadge = this.container.querySelector('#version-badge');
+    if (versionBadge) {
+      versionBadge.textContent = this.actualVersion;
+    }
+  }
+
+  /**
+   * Update header title
+   * @param {string} title - New title
+   */
+  updateTitle(title) {
+    this.options.title = title;
+    const titleElement = this.container.querySelector('.page-title');
+    if (titleElement) {
+      titleElement.innerHTML = `
+        ${title}
+        ${this.options.showVersionBadge ? `<span class="version-badge" id="version-badge">${this.actualVersion}</span>` : ''}
+      `;
+    }
+  }
+
+  /**
+   * Update header subtitle
+   * @param {string} subtitle - New subtitle
+   */
+  updateSubtitle(subtitle) {
+    this.options.subtitle = subtitle;
+    const subtitleElement = this.container.querySelector('.page-subtitle');
+    if (subtitleElement) {
+      subtitleElement.textContent = subtitle;
+    }
+  }
+
+  /**
+   * Update status dot state
+   * @param {boolean} active - Whether status should be active
+   */
+  updateStatusDot(active) {
+    const statusDot = this.container.querySelector('#session-status-dot');
+    if (statusDot) {
+      statusDot.classList.toggle('active', active);
+    }
+  }
+
+  /**
+   * Get current theme
+   * @returns {string} Current theme ('light' or 'dark')
+   */
+  getCurrentTheme() {
+    return document.body.getAttribute('data-theme') || 'dark';
+  }
+
+  /**
+   * Destroy header component
+   */
+  destroy() {
+    this.stopUpdateInterval();
+    this.container.innerHTML = '';
+  }
+}
+
+// Export for module use
+if (typeof module !== 'undefined' && module.exports) {
+  module.exports = HeaderComponent;
+}

package/src/analytics-web/index.html

@@ -12,6 +12,7 @@
     <script src="services/StateService.js"></script>
     
     <!-- Component Scripts -->
+    <script src="components/HeaderComponent.js"></script>
     <script src="components/Charts.js"></script>
     <!-- Dashboard.js removed - deprecated architecture -->
     <script src="components/SessionTimer.js"></script>
@@ -2644,6 +2645,7 @@
             flex: 1;
             display: flex;
             flex-direction: column;
+            margin-left: 56px;
             transition: margin-left 0.3s ease;
         }
         
@@ -2662,7 +2664,9 @@
             display: flex;
             flex-direction: column;
             transition: all 0.3s cubic-bezier(0.4, 0, 0.2, 1);
-            position: relative;
+            position: fixed;
+            top: 0;
+            left: 0;
             z-index: 1000;
             box-shadow: 2px 0 8px rgba(0, 0, 0, 0.1);
             overflow: visible;
@@ -2673,6 +2677,10 @@
             background: var(--bg-secondary);
             border-right: 1px solid var(--text-accent);
             box-shadow: 4px 0 16px rgba(213, 116, 85, 0.1);
+            position: fixed;
+            top: 0;
+            left: 0;
+            height: 100vh;
         }
         
         .sidebar-header {
@@ -4616,32 +4624,7 @@
             margin: 0 auto;
         }
 
-        /* App Layout Styles (App.js + Sidebar.js) */
-        .app {
-            display: flex;
-            min-height: 100vh;
-            background: var(--bg-primary);
-        }
-
-        .app-sidebar {
-            width: 60px;
-            background: var(--bg-secondary);
-            border-right: 1px solid var(--border-primary);
-            transition: width 0.3s ease;
-        }
-
-        .app-main {
-            flex: 1;
-            display: flex;
-            flex-direction: column;
-            min-width: 0;
-        }
-
-        .app-content {
-            flex: 1;
-            padding: 20px;
-            overflow-y: auto;
-        }
+        /* App Layout Styles (App.js + Sidebar.js) - Duplicates removed, using definitions above */
         
         /* Metrics Section */
         .metrics-section {

package/src/analytics-web/services/DataService.js

@@ -409,6 +409,19 @@ class DataService {
     this.setupWebSocketIntegration();
   }
   
+  /**
+   * Get application version from backend
+   * @returns {Promise<Object>} Version information
+   */
+  async getVersion() {
+    try {
+      return await this.cachedFetch('/api/version', 300000); // Cache for 5 minutes
+    } catch (error) {
+      console.error('Error fetching version:', error);
+      return { version: '1.13.2', name: 'claude-code-templates' }; // Fallback
+    }
+  }
+
   /**
    * Get cache statistics
    * @returns {Object} Cache statistics

package/src/health-check.js

@@ -394,58 +394,62 @@ class HealthChecker {
   }
 
   checkAuthentication() {
+    const homeDir = os.homedir();
+    
+    // Check for Claude Code OAuth authentication in ~/.claude.json
+    const claudeJsonPath = path.join(homeDir, '.claude.json');
+    
     try {
-      // Try to run claude command to check authentication status
-      const output = execSync('claude auth status 2>&1', { 
-        encoding: 'utf8', 
-        stdio: 'pipe',
-        timeout: 5000 
-      });
+      if (fs.existsSync(claudeJsonPath)) {
+        const claudeConfig = JSON.parse(fs.readFileSync(claudeJsonPath, 'utf8'));
+        
+        // Check for OAuth authentication
+        if (claudeConfig.oauthAccount && claudeConfig.oauthAccount.accountUuid) {
+          const email = claudeConfig.oauthAccount.emailAddress || 'OAuth user';
+          return {
+            status: 'pass',
+            message: `Authenticated via OAuth (${email})`
+          };
+        }
+        
+        // Check for API key authentication
+        if (claudeConfig.apiKey) {
+          return {
+            status: 'pass',
+            message: 'Authenticated via API key'
+          };
+        }
+      }
       
-      if (output.includes('authenticated') || output.includes('logged in') || output.includes('active')) {
+      // Check for environment variable API key
+      if (process.env.ANTHROPIC_API_KEY) {
         return {
           status: 'pass',
-          message: 'Authenticated and active'
+          message: 'Authenticated via ANTHROPIC_API_KEY environment variable'
         };
       }
       
-      // If command runs but no clear authentication status
-      return {
-        status: 'warn',
-        message: 'Authentication status unclear'
-      };
-      
-    } catch (error) {
-      // Try alternative method - check for session/config files
-      const homeDir = os.homedir();
-      const possibleAuthPaths = [
-        path.join(homeDir, '.claude', 'session'),
-        path.join(homeDir, '.claude', 'config'),
-        path.join(homeDir, '.config', 'claude', 'session'),
-        path.join(homeDir, '.config', 'claude', 'config'),
-        path.join(homeDir, '.anthropic', 'session'),
-        path.join(homeDir, '.anthropic', 'config')
-      ];
-      
-      for (const authPath of possibleAuthPaths) {
-        if (fs.existsSync(authPath)) {
-          try {
-            const stats = fs.statSync(authPath);
-            // Check if file was modified recently (within last 30 days)
-            const thirtyDaysAgo = new Date(Date.now() - 30 * 24 * 60 * 60 * 1000);
-            if (stats.mtime > thirtyDaysAgo) {
-              return {
-                status: 'pass',
-                message: 'Authentication session found'
-              };
-            }
-          } catch (statError) {
-            // Continue to next path
-          }
-        }
+      // Try to check if we can make a simple claude command
+      try {
+        execSync('claude --version', { 
+          encoding: 'utf8', 
+          stdio: 'pipe',
+          timeout: 3000 
+        });
+        
+        return {
+          status: 'warn',
+          message: 'Claude CLI available but authentication not configured'
+        };
+      } catch (cliError) {
+        return {
+          status: 'fail',
+          message: 'Claude CLI not available or not authenticated'
+        };
       }
       
-      // Try to check if we can make a simple claude command
+    } catch (error) {
+      // If we can't read the config file, check if CLI is at least installed
       try {
         execSync('claude --version', { 
           encoding: 'utf8', 
@@ -460,7 +464,7 @@ class HealthChecker {
       } catch (cliError) {
         return {
           status: 'fail',
-          message: 'Claude CLI not available or not authenticated'
+          message: 'Claude CLI not available or authentication check failed'
         };
       }
     }