@link-assistant/hive-mind 0.44.0 → 0.45.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @link-assistant/hive-mind
 
+## 0.45.0
+
+### Minor Changes
+
+- 81f8da0: Add `--tokens-budget-stats` option for detailed token usage analysis. This experimental feature shows context window usage and output token usage in absolute values and ratios when using `--tool claude`. Disabled by default.
+
 ## 0.44.0
 
 ### Minor Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@link-assistant/hive-mind",
-  "version": "0.44.0",
+  "version": "0.45.0",
   "description": "AI-powered issue solver and hive mind for collaborative problem solving",
   "main": "src/hive.mjs",
   "type": "module",

package/src/claude.budget-stats.lib.mjs

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+// Token budget statistics display module
+// Extracted from claude.lib.mjs to maintain file line limits
+
+import { formatNumber } from './claude.lib.mjs';
+
+/**
+ * Display token budget statistics (context window usage and ratios)
+ * @param {Object} usage - Usage data for a model
+ * @param {Function} log - Logging function
+ */
+export const displayBudgetStats = async (usage, log) => {
+  const modelInfo = usage.modelInfo;
+  if (!modelInfo?.limit) {
+    await log('\n      ⚠️  Budget stats not available (no model limits found)');
+    return;
+  }
+
+  await log('\n      📊 Token Budget Statistics:');
+
+  // Context window usage
+  if (modelInfo.limit.context) {
+    const contextLimit = modelInfo.limit.context;
+    // Input tokens include regular input + cache creation + cache read
+    const totalInputUsed = usage.inputTokens + usage.cacheCreationTokens + usage.cacheReadTokens;
+    const contextUsageRatio = totalInputUsed / contextLimit;
+    const contextUsagePercent = (contextUsageRatio * 100).toFixed(2);
+
+    await log('        Context window:');
+    await log(`          Used: ${formatNumber(totalInputUsed)} tokens`);
+    await log(`          Limit: ${formatNumber(contextLimit)} tokens`);
+    await log(`          Ratio: ${contextUsageRatio.toFixed(4)} (${contextUsagePercent}%)`);
+  }
+
+  // Output tokens usage
+  if (modelInfo.limit.output) {
+    const outputLimit = modelInfo.limit.output;
+    const outputUsageRatio = usage.outputTokens / outputLimit;
+    const outputUsagePercent = (outputUsageRatio * 100).toFixed(2);
+
+    await log('        Output tokens:');
+    await log(`          Used: ${formatNumber(usage.outputTokens)} tokens`);
+    await log(`          Limit: ${formatNumber(outputLimit)} tokens`);
+    await log(`          Ratio: ${outputUsageRatio.toFixed(4)} (${outputUsagePercent}%)`);
+  }
+
+  // Total session tokens (input + cache_creation + output)
+  const totalSessionTokens = usage.inputTokens + usage.cacheCreationTokens + usage.outputTokens;
+  await log(`        Total session tokens: ${formatNumber(totalSessionTokens)}`);
+};

package/src/claude.lib.mjs

@@ -13,6 +13,7 @@ import { reportError } from './sentry.lib.mjs';
 import { timeouts, retryLimits } from './config.lib.mjs';
 import { detectUsageLimit, formatUsageLimitMessage } from './usage-limit.lib.mjs';
 import { createInteractiveHandler } from './interactive-mode.lib.mjs';
+import { displayBudgetStats } from './claude.budget-stats.lib.mjs';
 /**
  * Format numbers with spaces as thousands separator (no commas)
  * Per issue #667: Use spaces for thousands, . for decimals
@@ -1279,6 +1280,10 @@ export const executeClaudeCommand = async (params) => {
               const usage = tokenUsage.modelUsage[modelId];
               await log(`\n   📊 ${usage.modelName || modelId}:`);
               await displayModelUsage(usage, log);
+              // Display budget stats if flag is enabled
+              if (argv.tokensBudgetStats && usage.modelInfo?.limit) {
+                await displayBudgetStats(usage, log);
+              }
             }
             // Show totals if multiple models were used
             if (modelIds.length > 1) {

package/src/hive.config.lib.mjs

@@ -251,6 +251,11 @@ export const createYargsConfig = (yargsInstance) => {
       description: 'Prompt AI to use general-purpose sub agents for processing large tasks with multiple files/folders. Only supported for --tool claude.',
       default: false
     })
+    .option('tokens-budget-stats', {
+      type: 'boolean',
+      description: '[EXPERIMENTAL] Show detailed token budget statistics including context window usage and ratios. Only supported for --tool claude.',
+      default: false
+    })
     .option('prompt-issue-reporting', {
       type: 'boolean',
       description: 'Enable automatic issue creation for spotted bugs/errors not related to main task. Issues will include reproducible examples, workarounds, and fix suggestions. Works for both current and third-party repositories. Only supported for --tool claude.',

package/src/solve.config.lib.mjs

@@ -255,6 +255,11 @@ export const createYargsConfig = (yargsInstance) => {
       description: 'Prompt AI to use general-purpose sub agents for processing large tasks with multiple files/folders. Only supported for --tool claude.',
       default: false
     })
+    .option('tokens-budget-stats', {
+      type: 'boolean',
+      description: '[EXPERIMENTAL] Show detailed token budget statistics including context window usage and ratios. Only supported for --tool claude.',
+      default: false
+    })
     .option('prompt-issue-reporting', {
       type: 'boolean',
       description: 'Enable automatic issue creation for spotted bugs/errors not related to main task. Issues will include reproducible examples, workarounds, and fix suggestions. Works for both current and third-party repositories. Only supported for --tool claude.',