feat: aggregate live mode for --day/--week/--month --live

Combines period flags with --live to show a live-updating aggregate
dashboard of all sessions in the period. Watches the active session
file and re-renders the full aggregate on each change. Completed
sessions are cached to keep refreshes fast.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: Dennis

src/formatter.ts

@@ -471,6 +471,134 @@ export function formatAggregate(analyses: SessionAnalysis[], label: string): str
   return lines.join('\n');
 }
 
+// ── Aggregate live mode ──
+
+export function formatAggregateLive(analyses: SessionAnalysis[], label: string): string {
+  const lines: string[] = [];
+
+  lines.push('');
+  lines.push(` ${chalk.bold('cctime')} \u00b7 ${chalk.bgRed.white.bold(' LIVE ')}${chalk.gray(' \u00b7 ' + label)}`);
+  lines.push(`  ${analyses.length} sessions`);
+
+  // Aggregate enhanced stats
+  const totalEnhanced: EnhancedStats = { humanWait: 0, humanAway: 0, claudeThink: 0, toolExec: 0, subagent: 0, planning: 0 };
+  let totalDuration = 0;
+  let totalTokensIn = 0, totalTokensOut = 0;
+  let totalCost = 0;
+  const allModels: Record<string, number> = {};
+  const allTools: Record<string, number> = {};
+  const allToolLatencies = new Map<string, { totalMs: number; count: number }>();
+
+  for (const a of analyses) {
+    totalDuration += a.durationMs;
+    for (const phase of activePhaseOrder) {
+      totalEnhanced[phase] += a.enhancedStats[phase];
+    }
+    totalEnhanced.humanAway += a.enhancedStats.humanAway;
+    totalTokensIn += a.tokens.input + a.tokens.cacheRead + a.tokens.cacheCreation;
+    totalTokensOut += a.tokens.output;
+    totalCost += a.estimatedCostUsd;
+    for (const [m, c] of Object.entries(a.models)) allModels[m] = (allModels[m] || 0) + c;
+    for (const [t, c] of Object.entries(a.tools)) allTools[t] = (allTools[t] || 0) + c;
+    for (const tl of a.toolLatencies) {
+      const existing = allToolLatencies.get(tl.name) || { totalMs: 0, count: 0 };
+      existing.totalMs += tl.totalMs;
+      existing.count += tl.count;
+      allToolLatencies.set(tl.name, existing);
+    }
+  }
+
+  const totalActive = Math.max(0, totalDuration - totalEnhanced.humanAway);
+
+  // Time breakdown
+  lines.push('');
+  lines.push(hr('Time Breakdown'));
+  const awayAgg = totalEnhanced.humanAway > 0 ? chalk.gray(` (${formatDuration(totalEnhanced.humanAway)} away)`) : '';
+  lines.push(`  ${chalk.bold(formatDuration(totalActive))} active${chalk.gray(' of ' + formatDuration(totalDuration))}${awayAgg}`);
+  lines.push('');
+
+  for (const phase of activePhaseOrder) {
+    const ms = totalEnhanced[phase];
+    if (ms === 0) continue;
+    const fraction = totalActive > 0 ? ms / totalActive : 0;
+    const pct = Math.round(fraction * 100);
+    const bar = renderBar(fraction, eColors[phase]);
+    const pLabel = eLabels[phase].padEnd(16);
+    lines.push(` ${pLabel}${bar} ${formatDuration(ms).padStart(5)}  (${String(pct).padStart(2)}%)`);
+  }
+
+  // Tokens & Cost
+  lines.push('');
+  lines.push(hr('Tokens & Cost'));
+
+  const aggTotalTok = totalTokensIn + totalTokensOut;
+  if (aggTotalTok > 0) {
+    const inFrac = totalTokensIn / aggTotalTok;
+    const inBar = Math.round(inFrac * BAR_WIDTH);
+    const outBar = BAR_WIDTH - inBar;
+    lines.push(` Tokens  ${chalk.cyan('\u2588'.repeat(inBar))}${chalk.green('\u2588'.repeat(outBar))}  ${chalk.cyan(formatTokens(totalTokensIn) + ' in')} ${chalk.green(formatTokens(totalTokensOut) + ' out')}`);
+  }
+  const avgCost = analyses.length > 0 ? totalCost / analyses.length : 0;
+  lines.push(` Cost    ~${formatCost(totalCost)}  (${analyses.length} sessions, avg ${formatCost(avgCost)}/session)`);
+
+  // Models
+  const modelEntries = Object.entries(allModels).sort((a, b) => b[1] - a[1]);
+  if (modelEntries.length > 0) {
+    lines.push('');
+    lines.push(hr('Models'));
+    const totalModelCalls = modelEntries.reduce((s, [, n]) => s + n, 0);
+    for (const [name, count] of modelEntries) {
+      const frac = count / totalModelCalls;
+      const pct = Math.round(frac * 100);
+      const bar = renderBar(frac, name === 'Opus' ? chalk.magenta : name === 'Haiku' ? chalk.green : chalk.blue);
+      lines.push(` ${name.padEnd(8)} ${bar} ${String(pct).padStart(3)}%  (${count} calls)`);
+    }
+  }
+
+  // Tools
+  const toolEntries = Object.entries(allTools).sort((a, b) => b[1] - a[1]).slice(0, 8);
+  if (toolEntries.length > 0) {
+    lines.push('');
+    lines.push(hr('Tools'));
+    const maxCalls = toolEntries[0][1];
+    for (const [name, count] of toolEntries) {
+      const frac = count / maxCalls;
+      const bar = renderBar(frac, chalk.yellow);
+      const latData = allToolLatencies.get(name);
+      const latStr = latData && latData.count > 0
+        ? chalk.gray(` avg ${formatLatency(latData.totalMs / latData.count)}`)
+        : '';
+      lines.push(` ${truncName(name)} ${bar} ${String(count).padStart(4)} calls${latStr}`);
+    }
+  }
+
+  // Activity heatmap
+  lines.push('');
+  lines.push(hr('Activity'));
+
+  const hourlyMs = new Array(24).fill(0);
+  for (const a of analyses) {
+    const startHour = new Date(a.startTime).getHours();
+    const aMs = Math.max(0, a.durationMs - a.enhancedStats.humanAway);
+    hourlyMs[startHour] += aMs;
+  }
+  const maxHourMs = Math.max(...hourlyMs, 1);
+  const sparkChars = '\u2581\u2582\u2583\u2584\u2585\u2586\u2587\u2588';
+  const heatmap = hourlyMs.map(ms => {
+    if (ms === 0) return chalk.gray('\u2581');
+    const idx = Math.round((ms / maxHourMs) * (sparkChars.length - 1));
+    return chalk.cyan(sparkChars[idx]);
+  }).join('');
+  lines.push(`  ${heatmap}`);
+  lines.push(chalk.gray('  12a  3a  6a  9a  12p  3p  6p  9p'));
+
+  // Footer
+  lines.push('');
+  lines.push(chalk.gray(' Ctrl+C to exit'));
+  lines.push('');
+  return lines.join('\n');
+}
+
 // ── Compact view (one line per session) ──
 
 export function formatCompact(analyses: SessionAnalysis[]): string {

src/index.ts

@@ -7,7 +7,7 @@ import { getLastSession, getTodaySessions, getWeekSessions, getMonthSessions, ge
 import { parseSession } from './parser.js';
 import { analyzeSession } from './analyzer.js';
 import { formatSession, formatAggregate, formatCompact, formatCsv, formatMarkdown, formatJsonAggregate } from './formatter.js';
-import { startLiveMode } from './live.js';
+import { startLiveMode, startAggregateLiveMode } from './live.js';
 import type { SessionIndexEntry, SessionAnalysis } from './types.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -146,8 +146,8 @@ program
     if (opts.color === true) process.env.FORCE_COLOR = '1';
 
     try {
-      // Live mode
-      if (opts.live) {
+      // Live mode — single session (no period flag)
+      if (opts.live && !opts.day && !opts.all && !opts.week && !opts.month && !opts.since) {
         await startLiveMode(opts.project);
         return;
       }
@@ -209,6 +209,24 @@ program
         return;
       }
 
+      // Aggregate live mode — live-updating view of the period
+      if (opts.live) {
+        let getEntries: () => Promise<SessionIndexEntry[]>;
+        if (opts.since) {
+          const sinceMs = parseDate(opts.since);
+          const untilMs = opts.until ? parseDate(opts.until) : undefined;
+          getEntries = () => getSessionsSince(sinceMs, opts.project, untilMs);
+        } else if (opts.month) {
+          getEntries = () => getMonthSessions(opts.project);
+        } else if (opts.week) {
+          getEntries = () => getWeekSessions(opts.project);
+        } else {
+          getEntries = () => getTodaySessions(opts.project);
+        }
+        await startAggregateLiveMode(getEntries, label, opts.project);
+        return;
+      }
+
       if (entries.length === 0) {
         console.error('No sessions found matching your filters.');
         console.error('Try running Claude Code first, or adjust --since/--project filters.');

src/live.ts

@@ -2,10 +2,10 @@ import { watch, type FSWatcher } from 'node:fs';
 import { readdir, stat } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
-import { parseSessionFrom } from './parser.js';
+import { parseSession, parseSessionFrom } from './parser.js';
 import { analyzeSession } from './analyzer.js';
-import { formatSessionLive } from './formatter.js';
-import type { SessionMessage } from './types.js';
+import { formatSessionLive, formatAggregateLive } from './formatter.js';
+import type { SessionMessage, SessionAnalysis, SessionIndexEntry } from './types.js';
 
 const ACTIVE_THRESHOLD_MS = 5 * 60 * 1000; // 5 minutes
 const DEBOUNCE_MS = 300;
@@ -150,3 +150,101 @@ export async function startLiveMode(projectFilter?: string): Promise<void> {
   process.on('SIGINT', cleanup);
   process.on('SIGTERM', cleanup);
 }
+
+export async function startAggregateLiveMode(
+  getEntries: () => Promise<SessionIndexEntry[]>,
+  label: string,
+  projectFilter?: string,
+): Promise<void> {
+  // Find the active session to watch for changes
+  const found = await findActiveSession(projectFilter);
+  if (!found) {
+    console.error('No active session found (modified within last 5 minutes).');
+    console.error('Start a Claude Code session, then run cctime --live in another terminal.');
+    process.exit(1);
+  }
+  const active = found;
+
+  let activeMessages: SessionMessage[] = [];
+  let byteOffset = 0;
+  let watcher: FSWatcher | null = null;
+  let debounceTimer: ReturnType<typeof setTimeout> | null = null;
+  let isRefreshing = false;
+
+  // Cache completed session analyses (keyed by sessionId)
+  const completedCache = new Map<string, SessionAnalysis>();
+
+  async function refresh() {
+    if (isRefreshing) return;
+    isRefreshing = true;
+    try {
+      // Re-fetch entry list (picks up new sessions started during the day)
+      const entries = await getEntries();
+
+      // Parse + analyze all non-active sessions (use cache for completed ones)
+      const analyses: SessionAnalysis[] = [];
+      for (const entry of entries) {
+        if (entry.sessionId === active.sessionId) continue;
+        const cached = completedCache.get(entry.sessionId);
+        if (cached) {
+          analyses.push(cached);
+        } else {
+          const messages = await parseSession(entry.fullPath);
+          const analysis = analyzeSession(entry.sessionId, messages);
+          if (analysis.summary === 'Untitled session' && entry.summary) {
+            analysis.summary = entry.summary;
+          }
+          completedCache.set(entry.sessionId, analysis);
+          analyses.push(analysis);
+        }
+      }
+
+      // Incrementally parse the active session
+      const { messages: newMessages, bytesRead } = await parseSessionFrom(active.fullPath, byteOffset);
+      if (newMessages.length > 0) {
+        activeMessages.push(...newMessages);
+      }
+      byteOffset = bytesRead;
+
+      const activeAnalysis = analyzeSession(active.sessionId, activeMessages);
+      analyses.push(activeAnalysis);
+
+      // Clear screen and redraw
+      process.stdout.write('\x1b[2J\x1b[H');
+      process.stdout.write(formatAggregateLive(analyses, label));
+    } catch {
+      // Skip on transient errors
+    } finally {
+      isRefreshing = false;
+    }
+  }
+
+  // Hide cursor
+  process.stdout.write('\x1b[?25l');
+
+  // Initial render
+  await refresh();
+
+  // Watch active session file for changes
+  watcher = watch(active.fullPath, () => {
+    if (debounceTimer) clearTimeout(debounceTimer);
+    debounceTimer = setTimeout(refresh, DEBOUNCE_MS);
+  });
+  watcher.on('error', () => {
+    // Ignore — periodic refresh will keep updating
+  });
+
+  // Periodic refresh (picks up new sessions, updates wall-clock timers)
+  const periodicTimer = setInterval(refresh, 5000);
+
+  function cleanup() {
+    if (watcher) { watcher.close(); watcher = null; }
+    if (debounceTimer) clearTimeout(debounceTimer);
+    clearInterval(periodicTimer);
+    process.stdout.write('\x1b[?25h');
+    process.exit(0);
+  }
+
+  process.on('SIGINT', cleanup);
+  process.on('SIGTERM', cleanup);
+}