claude-cli-advanced-starter-pack 1.0.15 → 1.1.0

package/templates/hooks/happy-title-generator.template.js

@@ -0,0 +1,260 @@
+/**
+ * Happy Title Generator Hook
+ *
+ * Auto-generates session titles with format: "Issue #XX - Summary"
+ * Detects GitHub issue numbers from branch names.
+ * Notifies Happy daemon of title updates for mobile display.
+ *
+ * Event: UserPromptSubmit
+ *
+ * Configuration: Reads from .claude/config/hooks-config.json
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+
+// Default configuration (can be overridden by hooks-config.json)
+const DEFAULT_CONFIG = {
+  rate_limit_ms: 30000,           // Throttle title updates to once per 30 sec
+  max_summary_words: 4,           // Maximum words in title summary
+  issue_pattern: 'issue-(\\d+)',  // Regex to extract issue number from branch
+  common_prefixes: [              // Prefixes to remove from summaries
+    'implement', 'add', 'fix', 'update', 'create',
+    'refactor', 'build', 'remove', 'optimize', 'improve'
+  ],
+};
+
+// Paths
+const CONFIG_PATH = path.join(process.cwd(), '.claude', 'config', 'hooks-config.json');
+const STATE_PATH = path.join(process.cwd(), '.claude', 'config', 'title-generator-state.json');
+const HAPPY_STATE_PATH = path.join(process.env.HOME || process.env.USERPROFILE, '.happy', 'daemon.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.title_generator || {}) };
+    }
+  } catch (e) {
+    // Use defaults on error
+  }
+  return DEFAULT_CONFIG;
+}
+
+/**
+ * Load state
+ */
+function loadState() {
+  try {
+    if (fs.existsSync(STATE_PATH)) {
+      return JSON.parse(fs.readFileSync(STATE_PATH, 'utf8'));
+    }
+  } catch (e) {
+    // Return fresh state
+  }
+  return {
+    last_update: 0,
+    current_title: null,
+    issue_number: null,
+  };
+}
+
+/**
+ * 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 failure
+  }
+}
+
+/**
+ * Get current git branch
+ */
+function getCurrentBranch() {
+  try {
+    const branch = execSync('git rev-parse --abbrev-ref HEAD', {
+      encoding: 'utf8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+      timeout: 5000,
+    }).trim();
+    return branch;
+  } catch (e) {
+    return null;
+  }
+}
+
+/**
+ * Extract issue number from branch name
+ */
+function extractIssueNumber(branch, config) {
+  if (!branch) return null;
+
+  try {
+    const pattern = new RegExp(config.issue_pattern, 'i');
+    const match = branch.match(pattern);
+    if (match && match[1]) {
+      return parseInt(match[1], 10);
+    }
+  } catch (e) {
+    // Invalid regex pattern
+  }
+
+  // Try common patterns as fallback
+  const fallbackPatterns = [
+    /issue-(\d+)/i,
+    /(\d+)-/,
+    /#(\d+)/,
+  ];
+
+  for (const pattern of fallbackPatterns) {
+    const match = branch.match(pattern);
+    if (match && match[1]) {
+      return parseInt(match[1], 10);
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Generate summary from user prompt
+ */
+function generateSummary(prompt, config) {
+  if (!prompt) return 'New Session';
+
+  // Clean the prompt
+  let summary = prompt.trim();
+
+  // Remove common prefixes
+  const prefixPattern = new RegExp(`^(${config.common_prefixes.join('|')})\\s+`, 'i');
+  summary = summary.replace(prefixPattern, '');
+
+  // Take first N words
+  const words = summary.split(/\s+/).slice(0, config.max_summary_words);
+  summary = words.join(' ');
+
+  // Capitalize first letter
+  if (summary.length > 0) {
+    summary = summary.charAt(0).toUpperCase() + summary.slice(1);
+  }
+
+  // Truncate if too long
+  if (summary.length > 50) {
+    summary = summary.substring(0, 47) + '...';
+  }
+
+  return summary || 'New Session';
+}
+
+/**
+ * Format title with issue number
+ */
+function formatTitle(issueNumber, summary, branch) {
+  let title = '';
+
+  if (issueNumber) {
+    title = `Issue #${issueNumber} - ${summary}`;
+  } else {
+    title = summary;
+  }
+
+  // Add branch info if available
+  if (branch && branch !== 'main' && branch !== 'master') {
+    const shortBranch = branch.length > 20 ? branch.substring(0, 17) + '...' : branch;
+    title = `${title} | ${shortBranch}`;
+  }
+
+  return title;
+}
+
+/**
+ * Notify Happy daemon of title update
+ */
+function notifyHappyDaemon(title) {
+  try {
+    if (!fs.existsSync(HAPPY_STATE_PATH)) {
+      return false; // Happy daemon not running
+    }
+
+    const happyState = JSON.parse(fs.readFileSync(HAPPY_STATE_PATH, 'utf8'));
+
+    // Update session title in daemon state
+    happyState.current_session = happyState.current_session || {};
+    happyState.current_session.title = title;
+    happyState.current_session.updated_at = new Date().toISOString();
+
+    // Write atomically using temp file
+    const tempPath = HAPPY_STATE_PATH + '.tmp';
+    fs.writeFileSync(tempPath, JSON.stringify(happyState, null, 2), 'utf8');
+    fs.renameSync(tempPath, HAPPY_STATE_PATH);
+
+    return true;
+  } catch (e) {
+    return false; // Silent failure - daemon may not be running
+  }
+}
+
+/**
+ * Main hook handler
+ */
+module.exports = async function happyTitleGenerator(context) {
+  // Always continue - never block
+  const approve = () => ({ continue: true });
+
+  try {
+    const config = loadConfig();
+    const state = loadState();
+    const now = Date.now();
+
+    // Rate limiting - don't update too frequently
+    if (state.last_update && (now - state.last_update) < config.rate_limit_ms) {
+      return approve();
+    }
+
+    // Parse hook input for user prompt
+    let userPrompt = '';
+    try {
+      const input = JSON.parse(process.env.CLAUDE_HOOK_INPUT || '{}');
+      userPrompt = input.prompt || input.message || '';
+    } catch (e) {
+      // No prompt available
+    }
+
+    // Get git context
+    const branch = getCurrentBranch();
+    const issueNumber = extractIssueNumber(branch, config);
+
+    // Generate title components
+    const summary = generateSummary(userPrompt, config);
+    const title = formatTitle(issueNumber, summary, branch);
+
+    // Update state
+    state.last_update = now;
+    state.current_title = title;
+    state.issue_number = issueNumber;
+    saveState(state);
+
+    // Notify Happy daemon (if running)
+    const notified = notifyHappyDaemon(title);
+
+    if (notified) {
+      console.log(`[happy-title-generator] Title updated: ${title}`);
+    }
+
+    return approve();
+  } catch (error) {
+    console.error(`[happy-title-generator] Error: ${error.message}`);
+    return approve();
+  }
+};

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/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();
+  }
+};