@sooneocean/claude-hud 0.1.0

package/src/git.ts

@@ -0,0 +1,126 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { readCache, writeCache, getDefaultCacheDir } from './cache.js';
+
+const execFileAsync = promisify(execFile);
+
+export interface FileStats {
+  modified: number;
+  added: number;
+  deleted: number;
+  untracked: number;
+}
+
+export interface GitStatus {
+  branch: string;
+  isDirty: boolean;
+  ahead: number;
+  behind: number;
+  fileStats?: FileStats;
+}
+
+export async function getGitBranch(cwd?: string): Promise<string | null> {
+  if (!cwd) return null;
+
+  try {
+    const { stdout } = await execFileAsync(
+      'git',
+      ['rev-parse', '--abbrev-ref', 'HEAD'],
+      { cwd, timeout: 1000, encoding: 'utf8' }
+    );
+    return stdout.trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+export async function getGitStatus(cwd?: string): Promise<GitStatus | null> {
+  if (!cwd) return null;
+
+  const cacheDir = getDefaultCacheDir();
+  const cacheKey = `git-status:${cwd}`;
+  const cached = readCache<GitStatus>(cacheKey, 2000, cacheDir);
+  if (cached) return cached;
+
+  try {
+    // Get branch name
+    const { stdout: branchOut } = await execFileAsync(
+      'git',
+      ['rev-parse', '--abbrev-ref', 'HEAD'],
+      { cwd, timeout: 1000, encoding: 'utf8' }
+    );
+    const branch = branchOut.trim();
+    if (!branch) return null;
+
+    // Check for dirty state and parse file stats
+    let isDirty = false;
+    let fileStats: FileStats | undefined;
+    try {
+      const { stdout: statusOut } = await execFileAsync(
+        'git',
+        ['--no-optional-locks', 'status', '--porcelain'],
+        { cwd, timeout: 1000, encoding: 'utf8' }
+      );
+      const trimmed = statusOut.trim();
+      isDirty = trimmed.length > 0;
+      if (isDirty) {
+        fileStats = parseFileStats(trimmed);
+      }
+    } catch {
+      // Ignore errors, assume clean
+    }
+
+    // Get ahead/behind counts
+    let ahead = 0;
+    let behind = 0;
+    try {
+      const { stdout: revOut } = await execFileAsync(
+        'git',
+        ['rev-list', '--left-right', '--count', '@{upstream}...HEAD'],
+        { cwd, timeout: 1000, encoding: 'utf8' }
+      );
+      const parts = revOut.trim().split(/\s+/);
+      if (parts.length === 2) {
+        behind = parseInt(parts[0], 10) || 0;
+        ahead = parseInt(parts[1], 10) || 0;
+      }
+    } catch {
+      // No upstream or error, keep 0/0
+    }
+
+    const result: GitStatus = { branch, isDirty, ahead, behind, fileStats };
+    writeCache(cacheKey, result, cacheDir);
+    return result;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Parse git status --porcelain output and count file stats (Starship-compatible format)
+ * Status codes: M=modified, A=added, D=deleted, ??=untracked
+ */
+function parseFileStats(porcelainOutput: string): FileStats {
+  const stats: FileStats = { modified: 0, added: 0, deleted: 0, untracked: 0 };
+  const lines = porcelainOutput.split('\n').filter(Boolean);
+
+  for (const line of lines) {
+    if (line.length < 2) continue;
+
+    const index = line[0];    // staged status
+    const worktree = line[1]; // unstaged status
+
+    if (line.startsWith('??')) {
+      stats.untracked++;
+    } else if (index === 'A') {
+      stats.added++;
+    } else if (index === 'D' || worktree === 'D') {
+      stats.deleted++;
+    } else if (index === 'M' || worktree === 'M' || index === 'R' || index === 'C') {
+      // M=modified, R=renamed (counts as modified), C=copied (counts as modified)
+      stats.modified++;
+    }
+  }
+
+  return stats;
+}

package/src/health-check.ts

@@ -0,0 +1,50 @@
+import fs from 'node:fs';
+import { getConfigPath, loadConfig } from './config.js';
+import { getDefaultCacheDir } from './cache.js';
+
+export interface HealthStatus {
+  configExists: boolean;
+  configValid: boolean;
+  cacheDir: string;
+  cacheDirExists: boolean;
+  nodeVersion: string;
+  platform: string;
+  terminalWidth: number | null;
+}
+
+export async function runHealthCheck(): Promise<HealthStatus> {
+  const configPath = getConfigPath();
+  let configValid = false;
+  const configExists = fs.existsSync(configPath);
+
+  if (configExists) {
+    try {
+      await loadConfig();
+      configValid = true;
+    } catch {
+      configValid = false;
+    }
+  }
+
+  const cacheDir = getDefaultCacheDir();
+
+  return {
+    configExists,
+    configValid,
+    cacheDir,
+    cacheDirExists: fs.existsSync(cacheDir),
+    nodeVersion: process.version,
+    platform: process.platform,
+    terminalWidth: process.stdout?.columns ?? null,
+  };
+}
+
+export function formatHealthReport(status: HealthStatus): string {
+  const lines = [
+    `Platform: ${status.platform} | Node: ${status.nodeVersion}`,
+    `Terminal: ${status.terminalWidth ?? 'unknown'} cols`,
+    `Config: ${status.configExists ? (status.configValid ? '✓ valid' : '✘ invalid') : '○ not set (using defaults)'}`,
+    `Cache: ${status.cacheDirExists ? '✓ exists' : '○ will be created'}`,
+  ];
+  return lines.join('\n');
+}

package/src/index.ts

@@ -0,0 +1,234 @@
+import { readStdin, getContextPercent } from './stdin.js';
+import { parseTranscript } from './transcript.js';
+import { render } from './render/index.js';
+import { countConfigs } from './config-reader.js';
+import { getGitStatus } from './git.js';
+import { getUsage } from './usage-api.js';
+import { loadConfig } from './config.js';
+import { parseExtraCmdArg, runExtraCmd } from './extra-cmd.js';
+import type { RenderContext } from './types.js';
+import { fileURLToPath } from 'node:url';
+import { realpathSync } from 'node:fs';
+import { getDefaultCacheDir, readCache, writeCache, readLatency, writeLatency } from './cache.js';
+import { loadProviders, fetchAllProviders } from './providers/index.js';
+import { evaluateAlerts, shouldBell, sendNotification } from './alert.js';
+import { calculateBurnRate, recordTokenSnapshot } from './burn-rate.js';
+import { updateSessionStats, getSessionStats, getSparkline } from './session-stats.js';
+import { getTerminalWidth } from './utils/terminal.js';
+import { estimateCost } from './cost-tracker.js';
+import { saveCurrentSession, getLastSession, formatSessionSummary } from './session-history.js';
+import { formatResetTime } from './utils/format.js';
+
+export type MainDeps = {
+  readStdin: typeof readStdin;
+  parseTranscript: typeof parseTranscript;
+  countConfigs: typeof countConfigs;
+  getGitStatus: typeof getGitStatus;
+  getUsage: typeof getUsage;
+  loadConfig: typeof loadConfig;
+  parseExtraCmdArg: typeof parseExtraCmdArg;
+  runExtraCmd: typeof runExtraCmd;
+  render: typeof render;
+  now: () => number;
+  log: (...args: unknown[]) => void;
+};
+
+export async function main(overrides: Partial<MainDeps> = {}): Promise<void> {
+  const deps: MainDeps = {
+    readStdin,
+    parseTranscript,
+    countConfigs,
+    getGitStatus,
+    getUsage,
+    loadConfig,
+    parseExtraCmdArg,
+    runExtraCmd,
+    render,
+    now: () => Date.now(),
+    log: console.log,
+    ...overrides,
+  };
+
+  try {
+    const stdin = await deps.readStdin();
+
+    if (!stdin) {
+      // Running without stdin - this happens during setup verification
+      const isMacOS = process.platform === 'darwin';
+      deps.log('[claude-hud] Initializing...');
+      if (isMacOS) {
+        deps.log('[claude-hud] Note: On macOS, you may need to restart Claude Code for the HUD to appear.');
+      }
+      return;
+    }
+
+    const transcriptPath = stdin.transcript_path ?? '';
+    const transcript = await deps.parseTranscript(transcriptPath);
+
+    const { claudeMdCount, rulesCount, mcpCount, hooksCount } = await deps.countConfigs(stdin.cwd);
+
+    const config = await deps.loadConfig();
+    const gitStatus = config.gitStatus.enabled
+      ? await deps.getGitStatus(stdin.cwd)
+      : null;
+
+    const cacheDir = getDefaultCacheDir();
+
+    // Only fetch usage if enabled in config (replaces env var requirement)
+    const usageStart = Date.now();
+    const usageData = config.display.showUsage !== false
+      ? await deps.getUsage({
+          ttls: {
+            cacheTtlMs: config.usage.cacheTtlSeconds * 1000,
+            failureCacheTtlMs: config.usage.failureCacheTtlSeconds * 1000,
+          },
+        })
+      : null;
+    if (config.display.showUsage !== false && usageData !== null) {
+      writeLatency(Date.now() - usageStart, cacheDir);
+    }
+    const apiLatency = readLatency(cacheDir);
+
+    const extraCmd = deps.parseExtraCmdArg();
+    const extraLabel = extraCmd ? await deps.runExtraCmd(extraCmd) : null;
+
+    const sessionDuration = formatSessionDuration(transcript.sessionStart, deps.now);
+
+    // Framework providers
+    let frameworkStatus: RenderContext['frameworkStatus'] = [];
+    if (config.display.showFrameworks) {
+      const providers = loadProviders(config.frameworks, cacheDir);
+      frameworkStatus = await fetchAllProviders(providers);
+    }
+
+    // Burn rate
+    let burnRate: RenderContext['burnRate'] = null;
+    const inputTokens = stdin.context_window?.current_usage?.input_tokens;
+    const contextSize = stdin.context_window?.context_window_size;
+    if (config.display.showBurnRate && inputTokens != null && contextSize != null) {
+      recordTokenSnapshot(inputTokens, cacheDir);
+      burnRate = calculateBurnRate(inputTokens, contextSize, cacheDir);
+    }
+
+    // Context percent
+    const contextPercent = getContextPercent(stdin);
+
+    // Session stats
+    updateSessionStats(cacheDir, {
+      contextPercent,
+      toolCount: transcript.tools.length,
+      agentCount: transcript.agents.length,
+    });
+    const sessionStats = getSessionStats(cacheDir);
+    const sparkline = getSparkline(cacheDir);
+
+    // Alerts
+    let alerts: RenderContext['alerts'] = [];
+    if (config.display.showAlerts) {
+      alerts = evaluateAlerts({
+        contextPercent,
+        usage5hPercent: usageData?.fiveHour ?? 0,
+        usage7dPercent: usageData?.sevenDay ?? 0,
+        estimatedCallsRemaining: burnRate?.estimatedCallsRemaining ?? null,
+        usageResetTime: usageData?.fiveHourResetAt
+          ? formatResetTime(usageData.fiveHourResetAt)
+          : null,
+        alertConfig: config.alerts,
+        cacheDir,
+      });
+
+      if (shouldBell(alerts, cacheDir)) {
+        process.stderr.write('\x07');
+        if (config.display.showNotifications) {
+          const criticalAlert = alerts.find(a => a.type.includes('critical'));
+          if (criticalAlert) {
+            sendNotification('Claude HUD', criticalAlert.message);
+          }
+        }
+      }
+    }
+
+    const costEstimate = config.display.showCost ? estimateCost(stdin, cacheDir) : null;
+
+    // Session history — only save when stats have changed
+    const prevStatsHash = readCache<string>('prev-session-hash', 60000, cacheDir);
+    const currentHash = `${sessionStats.totalToolCalls}-${sessionStats.autocompactCount}-${sessionStats.peakContextPercent}`;
+    if (prevStatsHash !== currentHash) {
+      writeCache('prev-session-hash', currentHash, cacheDir);
+      saveCurrentSession({
+        startTime: transcript.sessionStart?.toISOString() || new Date().toISOString(),
+        duration: sessionDuration,
+        model: stdin.model?.display_name || 'unknown',
+        peakContextPercent: sessionStats.peakContextPercent,
+        autocompactCount: sessionStats.autocompactCount,
+        totalToolCalls: sessionStats.totalToolCalls,
+        totalAgentRuns: sessionStats.totalAgentRuns,
+      });
+    }
+
+    // Last session summary — show once at session start
+    const shownLastSession = readCache<boolean>('shown-last-session', 24 * 60 * 60 * 1000, cacheDir);
+    if (!shownLastSession && transcript.tools.length === 0) {
+      const lastSession = getLastSession();
+      if (lastSession) {
+        console.error(`[claude-hud] ${formatSessionSummary(lastSession)}`);
+        writeCache('shown-last-session', true, cacheDir);
+      }
+    }
+
+    const ctx: RenderContext = {
+      stdin,
+      transcript,
+      claudeMdCount,
+      rulesCount,
+      mcpCount,
+      hooksCount,
+      sessionDuration,
+      gitStatus,
+      usageData,
+      config,
+      extraLabel,
+      frameworkStatus,
+      alerts,
+      burnRate,
+      sessionStats,
+      sparkline,
+      terminalWidth: getTerminalWidth(),
+      costEstimate,
+      apiLatency,
+    };
+
+    deps.render(ctx);
+  } catch (error) {
+    deps.log('[claude-hud] Error:', error instanceof Error ? error.message : 'Unknown error');
+  }
+}
+
+export function formatSessionDuration(sessionStart?: Date, now: () => number = () => Date.now()): string {
+  if (!sessionStart) {
+    return '';
+  }
+
+  const ms = now() - sessionStart.getTime();
+  const mins = Math.floor(ms / 60000);
+
+  if (mins < 1) return '<1m';
+  if (mins < 60) return `${mins}m`;
+
+  const hours = Math.floor(mins / 60);
+  const remainingMins = mins % 60;
+  return `${hours}h ${remainingMins}m`;
+}
+
+const scriptPath = fileURLToPath(import.meta.url);
+const argvPath = process.argv[1];
+const isSamePath = (a: string, b: string): boolean => {
+  try {
+    return realpathSync(a) === realpathSync(b);
+  } catch {
+    return a === b;
+  }
+};
+if (argvPath && isSamePath(argvPath, scriptPath)) {
+  void main();
+}

package/src/providers/agent-teams-provider.ts

@@ -0,0 +1,56 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import type { FrameworkProvider, FrameworkStatus, FrameworkEntry } from '../types.js';
+import { readCache, writeCache } from '../cache.js';
+
+const DEBUG = process.env.DEBUG?.includes('claude-hud') || process.env.DEBUG === '*';
+
+const execFileAsync = promisify(execFile);
+const CACHE_KEY = 'agent-teams-status';
+const SUCCESS_TTL = 5000;
+
+export class AgentTeamsProvider implements FrameworkProvider {
+  name = 'agent-teams';
+  constructor(private cacheDir: string) {}
+
+  isAvailable(): boolean { return !!process.env.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS; }
+
+  async fetch(): Promise<FrameworkStatus | null> {
+    const cached = readCache<FrameworkStatus>(CACHE_KEY, SUCCESS_TTL, this.cacheDir);
+    if (cached) return cached;
+
+    try {
+      const { stdout } = await execFileAsync('git', ['worktree', 'list', '--porcelain'], { timeout: 1000 });
+      const worktrees = this.parseWorktrees(stdout);
+      if (worktrees.length <= 1) return null;
+
+      const entries: FrameworkEntry[] = worktrees.slice(1).map(wt => ({
+        label: wt.branch?.replace('refs/heads/', '') || 'detached',
+        status: 'running' as const,
+        detail: wt.path,
+      }));
+
+      const status: FrameworkStatus = { provider: 'Teams', entries };
+      writeCache(CACHE_KEY, status, this.cacheDir);
+      return status;
+    } catch (err) {
+      if (DEBUG) console.error('[claude-hud:agent-teams-provider] git worktree error:', err);
+      return null;
+    }
+  }
+
+  private parseWorktrees(output: string): Array<{ path: string; branch?: string }> {
+    const worktrees: Array<{ path: string; branch?: string }> = [];
+    let current: { path: string; branch?: string } | null = null;
+    for (const line of output.split('\n')) {
+      if (line.startsWith('worktree ')) {
+        if (current) worktrees.push(current);
+        current = { path: line.slice(9) };
+      } else if (line.startsWith('branch ') && current) {
+        current.branch = line.slice(7);
+      }
+    }
+    if (current) worktrees.push(current);
+    return worktrees;
+  }
+}

package/src/providers/agw-provider.ts

@@ -0,0 +1,47 @@
+import type { FrameworkProvider, FrameworkStatus, FrameworkEntry } from '../types.js';
+import { readCache, writeCache } from '../cache.js';
+
+const DEBUG = process.env.DEBUG?.includes('claude-hud') || process.env.DEBUG === '*';
+
+const CACHE_KEY = 'agw-status';
+const SUCCESS_TTL = 3000;
+const FAILURE_TTL = 10000;
+
+export class AgwProvider implements FrameworkProvider {
+  name = 'agw';
+  constructor(private endpoint: string, private cacheDir: string) {}
+
+  isAvailable(): boolean { return true; }
+
+  async fetch(): Promise<FrameworkStatus | null> {
+    const failCached = readCache<boolean>('agw-failure', FAILURE_TTL, this.cacheDir);
+    if (failCached === true) return null;
+
+    const cached = readCache<FrameworkStatus>(CACHE_KEY, SUCCESS_TTL, this.cacheDir);
+    if (cached) return cached;
+
+    try {
+      const controller = new AbortController();
+      const timeout = setTimeout(() => controller.abort(), 200);
+      const res = await fetch(`${this.endpoint}/combos`, { signal: controller.signal });
+      clearTimeout(timeout);
+
+      if (!res.ok) { writeCache('agw-failure', true, this.cacheDir); return null; }
+
+      const combos = await res.json() as Array<{ id: string; status: string; progress?: string }>;
+      const entries: FrameworkEntry[] = combos.map(c => ({
+        label: c.id,
+        status: c.status === 'running' ? 'running' : c.status === 'error' ? 'error' : 'completed',
+        progress: c.progress,
+      }));
+
+      const status: FrameworkStatus = { provider: 'AGW', entries };
+      writeCache(CACHE_KEY, status, this.cacheDir);
+      return status;
+    } catch (err) {
+      if (DEBUG) console.error('[claude-hud:agw-provider] connection error:', err);
+      writeCache('agw-failure', true, this.cacheDir);
+      return null;
+    }
+  }
+}

package/src/providers/index.ts

@@ -0,0 +1,27 @@
+import type { FrameworkProvider, FrameworkStatus } from '../types.js';
+import { AgwProvider } from './agw-provider.js';
+import { AgentTeamsProvider } from './agent-teams-provider.js';
+
+interface FrameworksConfig {
+  agw: { enabled: boolean; endpoint: string };
+  agentTeams: { enabled: boolean };
+}
+
+export function loadProviders(config: FrameworksConfig, cacheDir: string): FrameworkProvider[] {
+  const providers: FrameworkProvider[] = [];
+  if (config.agw.enabled) providers.push(new AgwProvider(config.agw.endpoint, cacheDir));
+  if (config.agentTeams.enabled) providers.push(new AgentTeamsProvider(cacheDir));
+  return providers;
+}
+
+export async function fetchAllProviders(providers: FrameworkProvider[]): Promise<FrameworkStatus[]> {
+  const results: FrameworkStatus[] = [];
+  for (const provider of providers) {
+    if (!provider.isAvailable()) continue;
+    try {
+      const status = await provider.fetch();
+      if (status && status.entries.length > 0) results.push(status);
+    } catch { /* Silent skip — error boundary */ }
+  }
+  return results;
+}

package/src/render/agents-line.ts

@@ -0,0 +1,51 @@
+import type { RenderContext, AgentEntry } from '../types.js';
+import { yellow, green, magenta, dim } from './colors.js';
+import { truncateString } from '../utils/format.js';
+
+export function renderAgentsLine(ctx: RenderContext): string | null {
+  const { agents } = ctx.transcript;
+
+  const runningAgents = agents.filter((a) => a.status === 'running');
+  const recentCompleted = agents
+    .filter((a) => a.status === 'completed')
+    .slice(-2);
+
+  const toShow = [...runningAgents, ...recentCompleted].slice(-3);
+
+  if (toShow.length === 0) {
+    return null;
+  }
+
+  const lines: string[] = [];
+
+  for (const agent of toShow) {
+    lines.push(formatAgent(agent));
+  }
+
+  return lines.join('\n');
+}
+
+function formatAgent(agent: AgentEntry): string {
+  const statusIcon = agent.status === 'running' ? yellow('◐') : green('✓');
+  const type = magenta(agent.type);
+  const model = agent.model ? dim(`[${agent.model}]`) : '';
+  const desc = agent.description ? dim(`: ${truncateString(agent.description, 40)}`) : '';
+  const elapsed = formatElapsed(agent);
+
+  return `${statusIcon} ${type}${model ? ` ${model}` : ''}${desc} ${dim(`(${elapsed})`)}`;
+}
+
+
+function formatElapsed(agent: AgentEntry): string {
+  const now = Date.now();
+  const start = agent.startTime.getTime();
+  const end = agent.endTime?.getTime() ?? now;
+  const ms = end - start;
+
+  if (ms < 1000) return '<1s';
+  if (ms < 60000) return `${Math.round(ms / 1000)}s`;
+
+  const mins = Math.floor(ms / 60000);
+  const secs = Math.round((ms % 60000) / 1000);
+  return `${mins}m ${secs}s`;
+}

package/src/render/alert-line.ts

@@ -0,0 +1,11 @@
+import type { Alert } from '../types.js';
+import { red, dim } from './colors.js';
+
+export function renderAlertLine(alerts: Alert[]): string | null {
+  if (alerts.length === 0) return null;
+  const parts = alerts.map(alert => {
+    const icon = alert.type.includes('critical') ? '⚠' : '⚡';
+    return red(`${icon} ${alert.message}`);
+  });
+  return parts.join(` ${dim('│')} `);
+}