feat: add CacheTimer widget for prompt cache TTL countdown

package.json

@@ -1,6 +1,6 @@
 {
   "name": "ccstatusline",
-  "version": "2.2.8",
+  "version": "2.2.9",
   "description": "A customizable status line formatter for Claude Code CLI",
   "module": "src/ccstatusline.ts",
   "type": "module",

src/utils/widget-manifest.ts

@@ -75,7 +75,8 @@ export const WIDGET_MANIFEST: WidgetManifestEntry[] = [
     { type: 'worktree-mode', create: () => new widgets.GitWorktreeModeWidget() },
     { type: 'worktree-name', create: () => new widgets.GitWorktreeNameWidget() },
     { type: 'worktree-branch', create: () => new widgets.GitWorktreeBranchWidget() },
-    { type: 'worktree-original-branch', create: () => new widgets.GitWorktreeOriginalBranchWidget() }
+    { type: 'worktree-original-branch', create: () => new widgets.GitWorktreeOriginalBranchWidget() },
+    { type: 'cache-timer', create: () => new widgets.CacheTimerWidget() }
 ];
 
 export const LAYOUT_WIDGET_MANIFEST: LayoutWidgetManifestEntry[] = [

src/widgets/CacheTimer.ts

@@ -0,0 +1,141 @@
+import * as fs from 'fs';
+
+import type { RenderContext } from '../types/RenderContext';
+import type { Settings } from '../types/Settings';
+import type {
+    Widget,
+    WidgetEditorDisplay,
+    WidgetItem
+} from '../types/Widget';
+
+import { formatRawOrLabeledValue } from './shared/raw-or-labeled';
+
+const TTL_SECONDS = 300;
+const SAFETY_MARGIN = 5; // display as COLD 5s before actual expiry
+
+interface TranscriptEntry {
+    type?: string;
+    timestamp?: string;
+}
+
+/**
+ * Read the last N bytes of a file and return as string.
+ * Avoids loading large transcript files entirely.
+ */
+function readFileTail(filePath: string, bytes = 32768): string {
+    try {
+        const fd = fs.openSync(filePath, 'r');
+        const stat = fs.fstatSync(fd);
+        const size = stat.size;
+        const readSize = Math.min(bytes, size);
+        const offset = size - readSize;
+        const buf = Buffer.alloc(readSize);
+        fs.readSync(fd, buf, 0, readSize, offset);
+        fs.closeSync(fd);
+        return buf.toString('utf-8');
+    } catch {
+        return '';
+    }
+}
+
+/**
+ * Find the last user/assistant entry in the transcript.
+ * Returns { isWorking: true } when the last entry is a user message (Claude is processing).
+ * Returns { isWorking: false, lastAssistant: Date } when the last entry is an assistant message.
+ */
+function getTranscriptState(transcriptPath: string): { isWorking: true } | { isWorking: false; lastAssistant: Date | null } {
+    const tail = readFileTail(transcriptPath);
+    if (!tail) {
+        return { isWorking: false, lastAssistant: null };
+    }
+
+    const lines = tail.split('\n').reverse();
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed) {
+            continue;
+        }
+        try {
+            const entry = JSON.parse(trimmed) as TranscriptEntry;
+            if (entry.type === 'user') {
+                return { isWorking: true };
+            }
+            if (entry.type === 'assistant' && entry.timestamp) {
+                return { isWorking: false, lastAssistant: new Date(entry.timestamp) };
+            }
+        } catch {
+            continue;
+        }
+    }
+    return { isWorking: false, lastAssistant: null };
+}
+
+function getRemainingSeconds(lastAssistant: Date): number {
+    const elapsedSeconds = (Date.now() - lastAssistant.getTime()) / 1000;
+    return TTL_SECONDS - SAFETY_MARGIN - elapsedSeconds;
+}
+
+function formatCountdown(remaining: number): string {
+    if (remaining <= 0) {
+        return 'COLD';
+    }
+    const m = Math.floor(remaining / 60);
+    const s = Math.floor(remaining % 60);
+    return `${m}:${s.toString().padStart(2, '0')}`;
+}
+
+function getIcon(remaining: number): string {
+    if (remaining <= 0) {
+        return '❄️';
+    }
+    const pct = remaining / (TTL_SECONDS - SAFETY_MARGIN);
+    if (pct > 0.5) {
+        return '🟢';
+    }
+    if (pct > 0.2) {
+        return '🟡';
+    }
+    return '🔴';
+}
+
+export class CacheTimerWidget implements Widget {
+    getDefaultColor(): string { return 'brightCyan'; }
+    getDescription(): string { return 'Shows time remaining on the 5-minute prompt cache TTL'; }
+    getDisplayName(): string { return 'Cache Timer'; }
+    getCategory(): string { return 'Session'; }
+
+    getEditorDisplay(_item: WidgetItem): WidgetEditorDisplay {
+        return { displayText: this.getDisplayName() };
+    }
+
+    render(item: WidgetItem, context: RenderContext, _settings: Settings): string | null {
+        if (context.isPreview) {
+            return formatRawOrLabeledValue(item, 'Cache: ', '🟢 4:52');
+        }
+
+        const transcriptPath = context.data?.transcript_path;
+        if (!transcriptPath) {
+            return null;
+        }
+
+        const state = getTranscriptState(transcriptPath);
+
+        if (state.isWorking) {
+            return formatRawOrLabeledValue(item, 'Cache: ', '🔥 HOT');
+        }
+
+        const { lastAssistant } = state;
+        if (!lastAssistant) {
+            return null;
+        }
+
+        const remaining = getRemainingSeconds(lastAssistant);
+        const icon = getIcon(remaining);
+        const countdown = formatCountdown(remaining);
+
+        return formatRawOrLabeledValue(item, 'Cache: ', `${icon} ${countdown}`);
+    }
+
+    supportsRawValue(): boolean { return true; }
+    supportsColors(_item: WidgetItem): boolean { return true; }
+}

src/widgets/index.ts

@@ -56,4 +56,5 @@ export { VimModeWidget } from './VimMode';
 export { GitWorktreeModeWidget } from './GitWorktreeMode';
 export { GitWorktreeNameWidget } from './GitWorktreeName';
 export { GitWorktreeBranchWidget } from './GitWorktreeBranch';
-export { GitWorktreeOriginalBranchWidget } from './GitWorktreeOriginalBranch';
+export { GitWorktreeOriginalBranchWidget } from './GitWorktreeOriginalBranch';
+export { CacheTimerWidget } from './CacheTimer';