claude-code-templates 1.12.2 → 1.13.1

package/bin/create-claude-config.js

@@ -54,6 +54,9 @@ program
   .option('--analytics', 'launch real-time Claude Code analytics dashboard')
   .option('--chats, --agents', 'launch Claude Code chats/agents dashboard (opens directly to conversations)')
   .option('--health-check, --health, --check, --verify', 'run comprehensive health check to verify Claude Code setup')
+  .option('--agent <agent>', 'install specific agent component')
+  .option('--command <command>', 'install specific command component')
+  .option('--mcp <mcp>', 'install specific MCP component')
   .action(async (options) => {
     try {
       await createClaudeConfig(options);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-templates",
-  "version": "1.12.2",
+  "version": "1.13.1",
   "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/core/AgentAnalyzer.js

@@ -0,0 +1,341 @@
+/**
+ * AgentAnalyzer - Analyzes Claude Code specialized agent usage patterns
+ * Extracts agent invocation data, usage frequency, and workflow patterns
+ */
+const chalk = require('chalk');
+const fs = require('fs-extra');
+const path = require('path');
+
+class AgentAnalyzer {
+  constructor() {
+    // Known Claude Code specialized agents
+    this.AGENT_TYPES = {
+      'general-purpose': {
+        name: 'General Purpose',
+        description: 'Multi-step tasks and research',
+        color: '#3fb950',
+        icon: '🔧'
+      },
+      'claude-code-best-practices': {
+        name: 'Claude Code Best Practices',
+        description: 'Workflow optimization and setup guidance',
+        color: '#f97316',
+        icon: '⚡'
+      },
+      'docusaurus-expert': {
+        name: 'Docusaurus Expert',
+        description: 'Documentation site management',
+        color: '#0969da',
+        icon: '📚'
+      }
+    };
+  }
+
+  /**
+   * Analyze agent usage across all conversations
+   * @param {Array} conversations - Array of conversation objects with parsed messages
+   * @param {Object} dateRange - Optional date range filter
+   * @returns {Object} Agent usage analysis
+   */
+  async analyzeAgentUsage(conversations, dateRange = null) {
+    const agentStats = {};
+    const agentTimeline = [];
+    const agentWorkflows = {};
+    let totalAgentInvocations = 0;
+
+    for (const conversation of conversations) {
+      // Parse messages from JSONL file if not already parsed
+      let messages = conversation.parsedMessages;
+      if (!messages && conversation.filePath) {
+        messages = await this.parseJsonlFile(conversation.filePath);
+      }
+      
+      if (!messages) continue;
+
+      messages.forEach(message => {
+        // Skip if outside date range
+        if (dateRange && !this.isWithinDateRange(message.timestamp, dateRange)) {
+          return;
+        }
+
+        // Look for Task tool usage with subagent_type
+        // Handle both direct message structure and nested message structure
+        const messageContent = message.message ? message.message.content : message.content;
+        const messageRole = message.message ? message.message.role : message.role;
+        
+        if (messageRole === 'assistant' && 
+            messageContent && 
+            Array.isArray(messageContent)) {
+          
+          messageContent.forEach(content => {
+            if (content.type === 'tool_use' && 
+                content.name === 'Task' && 
+                content.input && 
+                content.input.subagent_type) {
+              
+              const agentType = content.input.subagent_type;
+              const timestamp = new Date(message.timestamp);
+              const prompt = content.input.prompt || content.input.description || 'No description';
+              
+              // Initialize agent stats
+              if (!agentStats[agentType]) {
+                agentStats[agentType] = {
+                  type: agentType,
+                  name: this.AGENT_TYPES[agentType]?.name || agentType,
+                  description: this.AGENT_TYPES[agentType]?.description || 'Custom agent',
+                  color: this.AGENT_TYPES[agentType]?.color || '#8b5cf6',
+                  icon: this.AGENT_TYPES[agentType]?.icon || '🤖',
+                  totalInvocations: 0,
+                  uniqueConversations: new Set(),
+                  firstUsed: timestamp,
+                  lastUsed: timestamp,
+                  prompts: [],
+                  hourlyDistribution: new Array(24).fill(0),
+                  dailyUsage: {}
+                };
+              }
+
+              const stats = agentStats[agentType];
+              
+              // Update stats
+              stats.totalInvocations++;
+              stats.uniqueConversations.add(conversation.id);
+              stats.lastUsed = new Date(Math.max(stats.lastUsed, timestamp));
+              stats.firstUsed = new Date(Math.min(stats.firstUsed, timestamp));
+              
+              // Store prompt for analysis
+              stats.prompts.push({
+                text: prompt,
+                timestamp: timestamp,
+                conversationId: conversation.id
+              });
+              
+              // Track hourly distribution
+              const hour = timestamp.getHours();
+              stats.hourlyDistribution[hour]++;
+              
+              // Track daily usage
+              const dateKey = timestamp.toISOString().split('T')[0];
+              stats.dailyUsage[dateKey] = (stats.dailyUsage[dateKey] || 0) + 1;
+              
+              // Add to timeline
+              agentTimeline.push({
+                timestamp: timestamp,
+                agentType: agentType,
+                agentName: stats.name,
+                prompt: prompt.substring(0, 100) + (prompt.length > 100 ? '...' : ''),
+                conversationId: conversation.id,
+                color: stats.color,
+                icon: stats.icon
+              });
+              
+              totalAgentInvocations++;
+            }
+          });
+        }
+      });
+    }
+
+    // Convert Sets to counts and finalize stats
+    Object.keys(agentStats).forEach(agentType => {
+      const stats = agentStats[agentType];
+      stats.uniqueConversations = stats.uniqueConversations.size;
+      stats.averageUsagePerConversation = stats.uniqueConversations > 0 ? 
+        (stats.totalInvocations / stats.uniqueConversations).toFixed(1) : 0;
+    });
+
+    // Sort timeline by timestamp
+    agentTimeline.sort((a, b) => new Date(a.timestamp) - new Date(b.timestamp));
+
+    // Calculate agent workflows (sequences of agent usage)
+    const workflowPatterns = this.analyzeAgentWorkflows(agentTimeline);
+
+    return {
+      totalAgentInvocations,
+      totalAgentTypes: Object.keys(agentStats).length,
+      agentStats: Object.values(agentStats).sort((a, b) => b.totalInvocations - a.totalInvocations),
+      agentTimeline,
+      workflowPatterns,
+      popularHours: this.calculatePopularHours(agentStats),
+      usageByDay: this.calculateDailyUsage(agentStats),
+      efficiency: this.calculateAgentEfficiency(agentStats)
+    };
+  }
+
+  /**
+   * Analyze agent workflow patterns
+   * @param {Array} timeline - Chronological agent invocations
+   * @returns {Object} Workflow patterns
+   */
+  analyzeAgentWorkflows(timeline) {
+    const workflows = {};
+    const SESSION_GAP_MINUTES = 30; // Minutes between workflow sessions
+
+    let currentWorkflow = [];
+    let lastTimestamp = null;
+
+    timeline.forEach(event => {
+      const currentTime = new Date(event.timestamp);
+      
+      // Start new workflow if gap is too large or first event
+      if (!lastTimestamp || 
+          (currentTime - lastTimestamp) > (SESSION_GAP_MINUTES * 60 * 1000)) {
+        
+        // Save previous workflow if it had multiple agents
+        if (currentWorkflow.length > 1) {
+          const workflowKey = currentWorkflow.map(e => e.agentType).join(' → ');
+          workflows[workflowKey] = (workflows[workflowKey] || 0) + 1;
+        }
+        
+        currentWorkflow = [event];
+      } else {
+        currentWorkflow.push(event);
+      }
+      
+      lastTimestamp = currentTime;
+    });
+
+    // Don't forget the last workflow
+    if (currentWorkflow.length > 1) {
+      const workflowKey = currentWorkflow.map(e => e.agentType).join(' → ');
+      workflows[workflowKey] = (workflows[workflowKey] || 0) + 1;
+    }
+
+    // Convert to sorted array
+    return Object.entries(workflows)
+      .map(([pattern, count]) => ({ pattern, count }))
+      .sort((a, b) => b.count - a.count)
+      .slice(0, 10); // Top 10 workflows
+  }
+
+  /**
+   * Calculate popular usage hours across all agents
+   * @param {Object} agentStats - Agent statistics
+   * @returns {Array} Hour usage data
+   */
+  calculatePopularHours(agentStats) {
+    const hourlyTotals = new Array(24).fill(0);
+    
+    Object.values(agentStats).forEach(stats => {
+      stats.hourlyDistribution.forEach((count, hour) => {
+        hourlyTotals[hour] += count;
+      });
+    });
+
+    return hourlyTotals.map((count, hour) => ({
+      hour,
+      count,
+      label: `${hour.toString().padStart(2, '0')}:00`
+    }));
+  }
+
+  /**
+   * Calculate daily usage across all agents
+   * @param {Object} agentStats - Agent statistics
+   * @returns {Array} Daily usage data
+   */
+  calculateDailyUsage(agentStats) {
+    const dailyTotals = {};
+    
+    Object.values(agentStats).forEach(stats => {
+      Object.entries(stats.dailyUsage).forEach(([date, count]) => {
+        dailyTotals[date] = (dailyTotals[date] || 0) + count;
+      });
+    });
+
+    return Object.entries(dailyTotals)
+      .map(([date, count]) => ({
+        date,
+        count,
+        timestamp: new Date(date)
+      }))
+      .sort((a, b) => a.timestamp - b.timestamp);
+  }
+
+  /**
+   * Calculate agent efficiency metrics
+   * @param {Object} agentStats - Agent statistics
+   * @returns {Object} Efficiency metrics
+   */
+  calculateAgentEfficiency(agentStats) {
+    const agents = Object.values(agentStats);
+    if (agents.length === 0) return {};
+
+    const totalInvocations = agents.reduce((sum, agent) => sum + agent.totalInvocations, 0);
+    const totalConversations = agents.reduce((sum, agent) => sum + agent.uniqueConversations, 0);
+
+    return {
+      averageInvocationsPerAgent: (totalInvocations / agents.length).toFixed(1),
+      averageConversationsPerAgent: (totalConversations / agents.length).toFixed(1),
+      mostUsedAgent: agents[0],
+      agentDiversity: agents.length,
+      adoptionRate: (agents.filter(a => a.totalInvocations > 1).length / agents.length * 100).toFixed(1)
+    };
+  }
+
+  /**
+   * Parse JSONL file to extract messages
+   * @param {string} filePath - Path to the JSONL file
+   * @returns {Array} Array of parsed messages
+   */
+  async parseJsonlFile(filePath) {
+    try {
+      if (!await fs.pathExists(filePath)) {
+        return null;
+      }
+
+      const content = await fs.readFile(filePath, 'utf8');
+      const lines = content.trim().split('\n').filter(line => line.trim());
+      
+      return lines.map(line => {
+        try {
+          return JSON.parse(line);
+        } catch (error) {
+          console.warn(`Error parsing JSONL line in ${filePath}:`, error.message);
+          return null;
+        }
+      }).filter(Boolean);
+    } catch (error) {
+      console.error(`Error reading JSONL file ${filePath}:`, error);
+      return null;
+    }
+  }
+
+  /**
+   * Check if timestamp is within date range
+   * @param {string|Date} timestamp - Message timestamp
+   * @param {Object} dateRange - Date range with startDate and endDate
+   * @returns {boolean} Whether timestamp is in range
+   */
+  isWithinDateRange(timestamp, dateRange) {
+    if (!dateRange || (!dateRange.startDate && !dateRange.endDate)) return true;
+    
+    const messageDate = new Date(timestamp);
+    const startDate = dateRange.startDate ? new Date(dateRange.startDate) : new Date(0);
+    const endDate = dateRange.endDate ? new Date(dateRange.endDate) : new Date();
+    
+    return messageDate >= startDate && messageDate <= endDate;
+  }
+
+  /**
+   * Generate agent usage summary for display
+   * @param {Object} analysisResult - Result from analyzeAgentUsage
+   * @returns {Object} Summary data
+   */
+  generateSummary(analysisResult) {
+    const { totalAgentInvocations, totalAgentTypes, agentStats, efficiency } = analysisResult;
+    
+    return {
+      totalInvocations: totalAgentInvocations,
+      totalAgentTypes,
+      topAgent: agentStats[0] || null,
+      averageUsage: efficiency.averageInvocationsPerAgent,
+      adoptionRate: efficiency.adoptionRate,
+      summary: totalAgentInvocations > 0 ? 
+        `${totalAgentInvocations} agent invocations across ${totalAgentTypes} different agents` :
+        'No agent usage detected'
+    };
+  }
+}
+
+module.exports = AgentAnalyzer;

package/src/analytics/core/SessionAnalyzer.js

@@ -6,34 +6,40 @@ const chalk = require('chalk');
 
 class SessionAnalyzer {
   constructor() {
-    this.SESSION_DURATION = 5 * 60 * 60 * 1000; // 5 hours in milliseconds
+    // CORRECTED: Sessions don't have fixed duration - they reset at scheduled times
+    // Reset hours: 1am, 7am, 1pm, 7pm local time
+    this.RESET_HOURS = [1, 7, 13, 19];
     this.MONTHLY_SESSION_LIMIT = 50;
     
-    // Plan-specific message limits (conservative estimates)
+    // Plan-specific usage information (Claude uses complexity-based limits, not fixed message counts)
     this.PLAN_LIMITS = {
       'free': {
         name: 'Free Plan',
-        messagesPerSession: null,
+        estimatedMessagesPerSession: null,
         monthlyPrice: 0,
-        hasSessionLimits: false
+        hasSessionLimits: false,
+        description: 'Daily usage limits apply'
       },
       'standard': {
         name: 'Pro Plan',
-        messagesPerSession: 45,
+        estimatedMessagesPerSession: 45, // Rough estimate for ~200 sentence messages
         monthlyPrice: 20,
-        hasSessionLimits: true
+        hasSessionLimits: true,
+        description: 'Usage based on message complexity, conversation length, and current capacity. Limits reset every 5 hours.'
       },
       'max': {
         name: 'Max Plan (5x)',
-        messagesPerSession: 225,
+        estimatedMessagesPerSession: null, // 5x more than Pro, but still complexity-based
         monthlyPrice: 100,
-        hasSessionLimits: true
+        hasSessionLimits: true,
+        description: '5x the usage of Pro plan. Complexity-based limits.'
       },
       'premium': {
-        name: 'Max Plan (5x)',
-        messagesPerSession: 900,
+        name: 'Max Plan (20x)',
+        estimatedMessagesPerSession: null, // 20x more than Pro
         monthlyPrice: 200,
-        hasSessionLimits: true
+        hasSessionLimits: true,
+        description: '20x the usage of Pro plan. Complexity-based limits.'
       }
     };
   }
@@ -325,7 +331,7 @@ class SessionAnalyzer {
 
     // Create current session based on Claude's actual session window
     const sessionStartTime = new Date(claudeSessionInfo.startTime);
-    const sessionEndTime = new Date(claudeSessionInfo.startTime + claudeSessionInfo.sessionLimit.ms);
+    const sessionEndTime = new Date(claudeSessionInfo.sessionLimit.nextResetTime);
     const now = new Date();
     
     // Find the first user message that occurred AT OR AFTER the Claude session started
@@ -346,8 +352,50 @@ class SessionAnalyzer {
       return msgTime >= effectiveSessionStart && msgTime < sessionEndTime;
     });
 
+    // If no estimated messages found in session window, check for active conversations by lastModified
     if (currentSessionMessages.length === 0) {
-      return [];
+      const RECENT_ACTIVITY_THRESHOLD = 10 * 60 * 1000; // 10 minutes
+      const now = new Date();
+      
+      // Find conversations with recent activity (lastModified within session timeframe)
+      const activeConversations = conversations.filter(conversation => {
+        if (!conversation.lastModified) return false;
+        
+        const lastModified = new Date(conversation.lastModified);
+        const timeSinceModified = now - lastModified;
+        
+        // Consider conversation active if:
+        // 1. Modified after session start, AND
+        // 2. Recently modified (within threshold)
+        return lastModified >= sessionStartTime && timeSinceModified < RECENT_ACTIVITY_THRESHOLD;
+      });
+      
+      if (activeConversations.length === 0) {
+        return [];
+      }
+      
+      // Create messages for active conversations based on their real message count
+      activeConversations.forEach(conversation => {
+        const lastModified = new Date(conversation.lastModified);
+        const messageCount = conversation.messageCount || 0;
+        
+        // Create messages based on real message count, distributing them over the session
+        const sessionDuration = now - sessionStartTime;
+        const timePerMessage = sessionDuration / messageCount;
+        
+        for (let i = 0; i < messageCount; i++) {
+          // Distribute messages over the session timeline, alternating user/assistant
+          const messageTime = new Date(sessionStartTime.getTime() + (i * timePerMessage));
+          const role = i % 2 === 0 ? 'user' : 'assistant';
+          
+          currentSessionMessages.push({
+            timestamp: messageTime,
+            role: role,
+            conversationId: conversation.id,
+            usage: conversation.tokenUsage || null
+          });
+        }
+      });
     }
 
     // Create the current session object
@@ -409,12 +457,19 @@ class SessionAnalyzer {
   getCurrentActiveSessionFromClaudeInfo(sessions, claudeSessionInfo) {
     if (sessions.length === 0) return null;
     
-    // If Claude session is expired, return null
-    if (claudeSessionInfo.estimatedTimeRemaining.isExpired) {
-      return null;
+    const now = Date.now();
+    const RECENT_ACTIVITY_THRESHOLD = 5 * 60 * 1000; // 5 minutes
+    
+    // Check if there's recent activity - sessions can be renewed at reset time
+    const timeSinceLastUpdate = now - claudeSessionInfo.lastUpdate;
+    const hasRecentActivity = timeSinceLastUpdate < RECENT_ACTIVITY_THRESHOLD;
+    
+    // Session is active if not expired OR has recent activity (session was renewed)
+    if (!claudeSessionInfo.estimatedTimeRemaining.isExpired || hasRecentActivity) {
+      return sessions[0];
     }
     
-    return sessions[0]; // Since we only create one session based on Claude's current session
+    return null;
   }
 
   /**
@@ -516,38 +571,33 @@ class SessionAnalyzer {
     const warnings = [];
     const planLimits = this.PLAN_LIMITS[userPlan.planType] || this.PLAN_LIMITS['standard'];
 
-    // Session-level warnings
+    // Session-level warnings - only for time remaining and token usage
     if (currentSession) {
-      const sessionProgress = currentSession.messageCount / planLimits.messagesPerSession;
-      
-      if (sessionProgress >= 0.9) {
-        warnings.push({
-          type: 'session_limit_critical',
-          level: 'error',
-          message: `You're near your session message limit (${currentSession.messageCount}/${planLimits.messagesPerSession})`,
-          timeRemaining: currentSession.timeRemaining
-        });
-      } else if (sessionProgress >= 0.75) {
+      // Time remaining warning (30 minutes before reset)
+      if (currentSession.timeRemaining < 30 * 60 * 1000) { // 30 minutes
         warnings.push({
-          type: 'session_limit_warning',
-          level: 'warning',
-          message: `75% of session messages used (${currentSession.messageCount}/${planLimits.messagesPerSession})`,
+          type: 'session_time_warning',
+          level: 'info',
+          message: `Session resets in ${Math.round(currentSession.timeRemaining / 60000)} minutes`,
           timeRemaining: currentSession.timeRemaining
         });
       }
 
-      // Time remaining warning
-      if (currentSession.timeRemaining < 30 * 60 * 1000) { // 30 minutes
+      // High token usage warning (if we have token data and it's exceptionally high)
+      if (currentSession.tokenUsage && currentSession.tokenUsage.total > 1000000) { // 1M tokens
         warnings.push({
-          type: 'session_time_warning',
+          type: 'high_token_usage',
           level: 'info',
-          message: `Session expires in ${Math.round(currentSession.timeRemaining / 60000)} minutes`,
-          timeRemaining: currentSession.timeRemaining
+          message: `High token usage in this session (${Math.round(currentSession.tokenUsage.total / 1000)}K tokens)`,
+          tokenUsage: currentSession.tokenUsage.total
         });
       }
+
+      // Note: We don't warn about message counts since Claude uses complexity-based limits
+      // that can't be accurately predicted from simple message counts
     }
 
-    // Monthly warnings
+    // Monthly warnings (these limits are more predictable)
     const monthlyProgress = monthlyUsage.sessionCount / this.MONTHLY_SESSION_LIMIT;
     
     if (monthlyProgress >= 0.9) {
@@ -605,25 +655,30 @@ class SessionAnalyzer {
     // Ensure limits exist, fallback to standard plan
     const planLimits = limits || this.PLAN_LIMITS['standard'];
     
-    // Use weighted message calculation for more accurate progress
-    const weightedProgress = (currentSession.messageWeight / planLimits.messagesPerSession) * 100;
+    // Calculate only user messages (Claude only counts prompts toward limits)
+    const userMessages = currentSession.messages ? currentSession.messages.filter(msg => msg.role === 'user') : [];
+    const userMessageCount = userMessages.length;
     
     return {
       hasActiveSession: true,
       timeRemaining: currentSession.timeRemaining,
       timeRemainingFormatted: this.formatTimeRemaining(currentSession.timeRemaining),
-      messagesUsed: currentSession.messageCount,
-      messagesLimit: planLimits.messagesPerSession,
-      messageWeight: currentSession.messageWeight,
-      usageDetails: currentSession.usageDetails,
+      messagesUsed: userMessageCount,
+      messagesEstimate: planLimits.estimatedMessagesPerSession, // Show as estimate, not limit
       tokensUsed: currentSession.tokenUsage.total,
-      sessionProgress: weightedProgress,
-      sessionProgressSimple: (currentSession.messageCount / planLimits.messagesPerSession) * 100,
       planName: planLimits.name,
+      planDescription: planLimits.description,
       monthlySessionsUsed: monthlyUsage.sessionCount,
       monthlySessionsLimit: this.MONTHLY_SESSION_LIMIT,
       warnings: warnings.filter(w => w.type.includes('session')),
-      willResetAt: currentSession.endTime
+      willResetAt: currentSession.endTime,
+      // Usage insights
+      usageInsights: {
+        tokensPerMessage: userMessageCount > 0 ? Math.round(currentSession.tokenUsage.total / userMessageCount) : 0,
+        averageMessageComplexity: userMessageCount > 0 ? currentSession.messageWeight / userMessageCount : 0,
+        conversationLength: currentSession.messages ? currentSession.messages.length : 0,
+        sessionDuration: Date.now() - currentSession.startTime
+      }
     };
   }
 }