claude-cli-advanced-starter-pack 1.0.16 → 1.8.0

package/templates/hooks/token-budget-loader.template.js

@@ -0,0 +1,234 @@
+/**
+ * Token Budget Loader Hook
+ *
+ * Pre-calculates daily token budget at session start.
+ * Tracks usage across sessions and provides health status alerts.
+ * Saves ~5K tokens/session by pre-loading budget state.
+ *
+ * Event: UserPromptSubmit (runs once per session)
+ *
+ * Configuration: Reads from .claude/config/hooks-config.json
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// Default configuration (can be overridden by hooks-config.json)
+const DEFAULT_CONFIG = {
+  daily_limit: 200000,        // Daily token budget
+  warning_percent: 60,        // Warn at this percentage
+  critical_percent: 80,       // Critical warning at this percentage
+  reset_hours: 24,            // Budget reset cycle in hours
+};
+
+// Paths
+const CONFIG_PATH = path.join(process.cwd(), '.claude', 'config', 'hooks-config.json');
+const BUDGET_PATH = path.join(process.cwd(), '.claude', 'config', 'token-budget.json');
+const SESSION_MARKER = path.join(process.cwd(), '.claude', 'config', '.budget-loaded');
+
+/**
+ * Load configuration with defaults
+ */
+function loadConfig() {
+  try {
+    if (fs.existsSync(CONFIG_PATH)) {
+      const config = JSON.parse(fs.readFileSync(CONFIG_PATH, 'utf8'));
+      return { ...DEFAULT_CONFIG, ...(config.token_budget || {}) };
+    }
+  } catch (e) {
+    // Use defaults on error
+  }
+  return DEFAULT_CONFIG;
+}
+
+/**
+ * Load budget state
+ */
+function loadBudget() {
+  try {
+    if (fs.existsSync(BUDGET_PATH)) {
+      return JSON.parse(fs.readFileSync(BUDGET_PATH, 'utf8'));
+    }
+  } catch (e) {
+    // Return fresh budget
+  }
+  return null;
+}
+
+/**
+ * Save budget state
+ */
+function saveBudget(budget) {
+  try {
+    const dir = path.dirname(BUDGET_PATH);
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+    }
+    fs.writeFileSync(BUDGET_PATH, JSON.stringify(budget, null, 2), 'utf8');
+  } catch (e) {
+    console.error(`[token-budget-loader] Failed to save budget: ${e.message}`);
+  }
+}
+
+/**
+ * Check if we've already loaded budget this session
+ */
+function hasLoadedThisSession() {
+  try {
+    if (fs.existsSync(SESSION_MARKER)) {
+      const content = fs.readFileSync(SESSION_MARKER, 'utf8');
+      const timestamp = parseInt(content, 10);
+      // Session valid for 4 hours
+      if (Date.now() - timestamp < 4 * 60 * 60 * 1000) {
+        return true;
+      }
+    }
+  } catch (e) {
+    // Continue with loading
+  }
+  return false;
+}
+
+/**
+ * Mark session as loaded
+ */
+function markSessionLoaded() {
+  try {
+    const dir = path.dirname(SESSION_MARKER);
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+    }
+    fs.writeFileSync(SESSION_MARKER, Date.now().toString(), 'utf8');
+  } catch (e) {
+    // Silent failure
+  }
+}
+
+/**
+ * Check if budget should reset (new day)
+ */
+function shouldResetBudget(budget, config) {
+  if (!budget || !budget.reset_at) {
+    return true;
+  }
+
+  const resetAt = new Date(budget.reset_at);
+  const now = new Date();
+
+  return now >= resetAt;
+}
+
+/**
+ * Calculate next reset time
+ */
+function getNextResetTime(config) {
+  const now = new Date();
+  const resetTime = new Date(now);
+
+  // Reset at midnight UTC by default
+  resetTime.setUTCHours(0, 0, 0, 0);
+  resetTime.setTime(resetTime.getTime() + config.reset_hours * 60 * 60 * 1000);
+
+  // If we've passed today's reset, move to next cycle
+  while (resetTime <= now) {
+    resetTime.setTime(resetTime.getTime() + config.reset_hours * 60 * 60 * 1000);
+  }
+
+  return resetTime.toISOString();
+}
+
+/**
+ * Estimate tokens from characters (rough approximation)
+ * Claude uses ~4 chars per token on average
+ */
+function estimateTokens(chars) {
+  return Math.ceil(chars / 4);
+}
+
+/**
+ * Get budget health status
+ */
+function getBudgetHealth(budget, config) {
+  const percentUsed = (budget.used / budget.limit) * 100;
+
+  if (percentUsed >= config.critical_percent) {
+    return {
+      status: 'critical',
+      message: `CRITICAL: ${percentUsed.toFixed(1)}% of daily budget used`,
+      color: 'red',
+    };
+  } else if (percentUsed >= config.warning_percent) {
+    return {
+      status: 'warning',
+      message: `WARNING: ${percentUsed.toFixed(1)}% of daily budget used`,
+      color: 'yellow',
+    };
+  } else {
+    return {
+      status: 'healthy',
+      message: `Budget healthy: ${percentUsed.toFixed(1)}% used`,
+      color: 'green',
+    };
+  }
+}
+
+/**
+ * Main hook handler
+ */
+module.exports = async function tokenBudgetLoader(context) {
+  // Always continue - never block
+  const approve = () => ({ continue: true });
+
+  try {
+    // Only run once per session
+    if (hasLoadedThisSession()) {
+      return approve();
+    }
+
+    // Mark this session as loaded
+    markSessionLoaded();
+
+    const config = loadConfig();
+    let budget = loadBudget();
+
+    // Check if we need to reset the budget
+    if (shouldResetBudget(budget, config)) {
+      budget = {
+        limit: config.daily_limit,
+        used: 0,
+        reset_at: getNextResetTime(config),
+        sessions: [],
+        created_at: new Date().toISOString(),
+      };
+      saveBudget(budget);
+      console.log(`[token-budget-loader] Budget reset. Daily limit: ${config.daily_limit.toLocaleString()} tokens`);
+    }
+
+    // Calculate remaining budget
+    const remaining = budget.limit - budget.used;
+    const health = getBudgetHealth(budget, config);
+
+    // Log budget status
+    console.log(`[token-budget-loader] ${health.message}`);
+    console.log(`[token-budget-loader] Remaining: ${remaining.toLocaleString()} tokens`);
+    console.log(`[token-budget-loader] Resets at: ${budget.reset_at}`);
+
+    // Record this session start
+    budget.sessions.push({
+      started_at: new Date().toISOString(),
+      initial_remaining: remaining,
+    });
+
+    // Keep only last 10 sessions
+    if (budget.sessions.length > 10) {
+      budget.sessions = budget.sessions.slice(-10);
+    }
+
+    saveBudget(budget);
+
+    return approve();
+  } catch (error) {
+    console.error(`[token-budget-loader] Error: ${error.message}`);
+    return approve();
+  }
+};

package/templates/hooks/token-usage-monitor.template.js

@@ -0,0 +1,193 @@
+/**
+ * Token Usage Monitor Hook
+ *
+ * Tracks cumulative token usage across the session.
+ * Auto-respawn warning at 90% of context window.
+ * Provides real-time token consumption feedback.
+ *
+ * Event: PostToolUse
+ *
+ * Configuration: Reads from .claude/config/hooks-config.json
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// Default configuration
+const DEFAULT_CONFIG = {
+  context_limit: 200000,           // Estimated context window
+  warning_threshold: 0.75,         // Warn at 75%
+  critical_threshold: 0.90,        // Critical at 90%
+  auto_compact_suggestion: true,   // Suggest compaction at critical
+  session_timeout_ms: 300000,      // 5 minutes
+};
+
+// Paths
+const CONFIG_PATH = path.join(process.cwd(), '.claude', 'config', 'hooks-config.json');
+const STATE_PATH = path.join(process.cwd(), '.claude', 'config', 'token-usage-state.json');
+
+/**
+ * Load configuration
+ */
+function loadConfig() {
+  try {
+    if (fs.existsSync(CONFIG_PATH)) {
+      const config = JSON.parse(fs.readFileSync(CONFIG_PATH, 'utf8'));
+      return { ...DEFAULT_CONFIG, ...(config.token_usage || {}) };
+    }
+  } catch (e) {
+    // Use defaults
+  }
+  return DEFAULT_CONFIG;
+}
+
+/**
+ * Load state
+ */
+function loadState() {
+  try {
+    if (fs.existsSync(STATE_PATH)) {
+      return JSON.parse(fs.readFileSync(STATE_PATH, 'utf8'));
+    }
+  } catch (e) {
+    // Fresh state
+  }
+  return {
+    session_id: null,
+    session_start: null,
+    total_input_chars: 0,
+    total_output_chars: 0,
+    estimated_tokens: 0,
+    tool_calls: 0,
+    last_activity: null,
+    warnings_shown: 0,
+  };
+}
+
+/**
+ * Save state
+ */
+function saveState(state) {
+  try {
+    const dir = path.dirname(STATE_PATH);
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+    }
+    fs.writeFileSync(STATE_PATH, JSON.stringify(state, null, 2), 'utf8');
+  } catch (e) {
+    // Silent
+  }
+}
+
+/**
+ * Estimate tokens from text (rough approximation)
+ */
+function estimateTokens(text) {
+  if (!text) return 0;
+  // Average ~4 characters per token for English text
+  return Math.ceil(text.length / 4);
+}
+
+/**
+ * Generate session ID
+ */
+function generateSessionId() {
+  return Date.now().toString(36) + Math.random().toString(36).substr(2, 5);
+}
+
+/**
+ * Format number with commas
+ */
+function formatNumber(num) {
+  return num.toLocaleString();
+}
+
+/**
+ * Main hook handler
+ */
+module.exports = async function tokenUsageMonitor(context) {
+  const approve = () => ({ continue: true });
+
+  try {
+    const config = loadConfig();
+    let state = loadState();
+    const now = Date.now();
+
+    // Check for new session
+    if (!state.session_start || (now - state.last_activity) > config.session_timeout_ms) {
+      state = {
+        session_id: generateSessionId(),
+        session_start: now,
+        total_input_chars: 0,
+        total_output_chars: 0,
+        estimated_tokens: 0,
+        tool_calls: 0,
+        last_activity: now,
+        warnings_shown: 0,
+      };
+    }
+
+    // Parse hook input
+    let inputChars = 0;
+    let outputChars = 0;
+
+    try {
+      const input = JSON.parse(process.env.CLAUDE_HOOK_INPUT || '{}');
+
+      // Count input characters
+      if (input.tool_input) {
+        const inputStr = typeof input.tool_input === 'string'
+          ? input.tool_input
+          : JSON.stringify(input.tool_input);
+        inputChars = inputStr.length;
+      }
+
+      // Count output characters
+      if (input.tool_output) {
+        const outputStr = typeof input.tool_output === 'string'
+          ? input.tool_output
+          : JSON.stringify(input.tool_output);
+        outputChars = outputStr.length;
+      }
+    } catch (e) {
+      // Skip counting on error
+    }
+
+    // Update totals
+    state.total_input_chars += inputChars;
+    state.total_output_chars += outputChars;
+    state.tool_calls++;
+    state.last_activity = now;
+
+    // Estimate tokens
+    const totalChars = state.total_input_chars + state.total_output_chars;
+    state.estimated_tokens = estimateTokens(totalChars);
+
+    // Calculate usage percentage
+    const usagePercent = state.estimated_tokens / config.context_limit;
+
+    // Check thresholds
+    if (usagePercent >= config.critical_threshold) {
+      if (state.warnings_shown < 3) { // Don't spam
+        console.log(`[token-usage-monitor] CRITICAL: ${(usagePercent * 100).toFixed(1)}% of context used`);
+        console.log(`[token-usage-monitor] Estimated tokens: ${formatNumber(state.estimated_tokens)}`);
+        if (config.auto_compact_suggestion) {
+          console.log('[token-usage-monitor] Consider using /context-audit or starting a new session');
+        }
+        state.warnings_shown++;
+      }
+    } else if (usagePercent >= config.warning_threshold) {
+      if (state.warnings_shown < 2) {
+        console.log(`[token-usage-monitor] WARNING: ${(usagePercent * 100).toFixed(1)}% of context used`);
+        state.warnings_shown++;
+      }
+    }
+
+    saveState(state);
+
+    return approve();
+  } catch (error) {
+    console.error(`[token-usage-monitor] Error: ${error.message}`);
+    return approve();
+  }
+};

package/templates/hooks/tool-output-cacher.template.js

@@ -0,0 +1,219 @@
+/**
+ * Tool Output Cacher Hook
+ *
+ * Caches large tool outputs (>2KB) to reduce context consumption.
+ * Monitors cumulative session output and warns at thresholds.
+ * Saves ~500 tokens per large output by storing in cache files.
+ *
+ * Event: PostToolUse
+ *
+ * Configuration: Reads from .claude/config/hooks-config.json
+ */
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+// Default configuration (can be overridden by hooks-config.json)
+const DEFAULT_CONFIG = {
+  threshold_chars: 2048,           // Cache outputs larger than this
+  warning_threshold: 100000,       // Warn when session total exceeds this
+  critical_threshold: 150000,      // Critical warning at this level
+  session_timeout_ms: 300000,      // 5 minutes - consider new session
+  cacheable_tools: ['Bash', 'Read', 'Glob', 'Grep'],
+  bypass_tools: ['Task', 'TaskOutput'],
+};
+
+// Paths
+const CONFIG_PATH = path.join(process.cwd(), '.claude', 'config', 'hooks-config.json');
+const CACHE_DIR = path.join(process.cwd(), '.claude', 'cache', 'tool-outputs');
+const STATE_FILE = path.join(process.cwd(), '.claude', 'config', 'tool-output-cacher-state.json');
+
+/**
+ * Load configuration with defaults
+ */
+function loadConfig() {
+  try {
+    if (fs.existsSync(CONFIG_PATH)) {
+      const config = JSON.parse(fs.readFileSync(CONFIG_PATH, 'utf8'));
+      return { ...DEFAULT_CONFIG, ...(config.output_caching || {}) };
+    }
+  } catch (e) {
+    // Use defaults on error
+  }
+  return DEFAULT_CONFIG;
+}
+
+/**
+ * Load session state
+ */
+function loadState() {
+  try {
+    if (fs.existsSync(STATE_FILE)) {
+      return JSON.parse(fs.readFileSync(STATE_FILE, 'utf8'));
+    }
+  } catch (e) {
+    // Return fresh state
+  }
+  return {
+    session_id: null,
+    session_start: null,
+    cumulative_chars: 0,
+    cached_count: 0,
+    last_activity: null,
+  };
+}
+
+/**
+ * Save session state
+ */
+function saveState(state) {
+  try {
+    const dir = path.dirname(STATE_FILE);
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+    }
+    fs.writeFileSync(STATE_FILE, JSON.stringify(state, null, 2), 'utf8');
+  } catch (e) {
+    // Silent failure - don't block tool execution
+  }
+}
+
+/**
+ * Generate cache key for output
+ */
+function generateCacheKey(toolName, output) {
+  const hash = crypto.createHash('md5').update(output.slice(0, 500)).digest('hex').slice(0, 8);
+  return `${toolName.toLowerCase()}-${Date.now()}-${hash}`;
+}
+
+/**
+ * Cache output to file
+ */
+function cacheOutput(key, output, summary) {
+  try {
+    if (!fs.existsSync(CACHE_DIR)) {
+      fs.mkdirSync(CACHE_DIR, { recursive: true });
+    }
+
+    const cachePath = path.join(CACHE_DIR, `${key}.txt`);
+    fs.writeFileSync(cachePath, output, 'utf8');
+
+    return {
+      cached: true,
+      path: cachePath,
+      summary: summary,
+    };
+  } catch (e) {
+    return { cached: false, error: e.message };
+  }
+}
+
+/**
+ * Generate summary of large output
+ */
+function generateSummary(output, maxLines = 15) {
+  const lines = output.split('\n');
+  const totalLines = lines.length;
+  const totalChars = output.length;
+
+  // Take first N lines as preview
+  const preview = lines.slice(0, maxLines).join('\n');
+
+  return {
+    preview: preview,
+    total_lines: totalLines,
+    total_chars: totalChars,
+    truncated: totalLines > maxLines,
+  };
+}
+
+/**
+ * Check if tool output should be cached
+ */
+function shouldCache(toolName, output, config) {
+  // Skip bypass tools
+  if (config.bypass_tools.includes(toolName)) {
+    return false;
+  }
+
+  // Check if tool is cacheable
+  const isCacheable = config.cacheable_tools.some(t =>
+    toolName.startsWith(t) || toolName === t
+  );
+
+  if (!isCacheable) {
+    return false;
+  }
+
+  // Check size threshold
+  return output.length > config.threshold_chars;
+}
+
+/**
+ * Main hook handler
+ */
+module.exports = async function toolOutputCacher(context) {
+  // Always approve - this is a PostToolUse hook for monitoring only
+  const approve = () => ({ continue: true });
+
+  try {
+    // Parse hook input
+    const input = JSON.parse(process.env.CLAUDE_HOOK_INPUT || '{}');
+    const { tool_name, tool_input, tool_output } = input;
+
+    if (!tool_name || !tool_output) {
+      return approve();
+    }
+
+    const output = typeof tool_output === 'string' ? tool_output : JSON.stringify(tool_output);
+    const config = loadConfig();
+
+    // Load and update session state
+    let state = loadState();
+    const now = Date.now();
+
+    // Check if this is a new session
+    if (!state.session_start || (now - state.last_activity) > config.session_timeout_ms) {
+      state = {
+        session_id: crypto.randomBytes(4).toString('hex'),
+        session_start: now,
+        cumulative_chars: 0,
+        cached_count: 0,
+        last_activity: now,
+      };
+    }
+
+    // Update cumulative tracking
+    state.cumulative_chars += output.length;
+    state.last_activity = now;
+
+    // Check if we should cache this output
+    if (shouldCache(tool_name, output, config)) {
+      const summary = generateSummary(output);
+      const cacheKey = generateCacheKey(tool_name, output);
+      const cacheResult = cacheOutput(cacheKey, output, summary);
+
+      if (cacheResult.cached) {
+        state.cached_count++;
+        console.log(`[tool-output-cacher] Cached ${tool_name} output (${output.length} chars) -> ${cacheResult.path}`);
+      }
+    }
+
+    // Check thresholds and warn
+    if (state.cumulative_chars >= config.critical_threshold) {
+      console.log(`[tool-output-cacher] CRITICAL: Session at ${state.cumulative_chars} chars. Consider compaction.`);
+    } else if (state.cumulative_chars >= config.warning_threshold) {
+      console.log(`[tool-output-cacher] WARNING: Session at ${state.cumulative_chars} chars.`);
+    }
+
+    // Save state
+    saveState(state);
+
+    return approve();
+  } catch (error) {
+    // Always approve even on error
+    console.error(`[tool-output-cacher] Error: ${error.message}`);
+    return approve();
+  }
+};