claude-simple-status 1.2.0 → 1.3.0

package/README.md

@@ -11,7 +11,9 @@
 
 A simple, no-frills statusline for [Claude Code](https://docs.anthropic.com/en/docs/claude-code) that shows what matters: **project name, git branch, model, context usage, quota, and API costs**.
 
-![statusline screenshot](assets/statusline.png)
+![statusline subscription](assets/statusline-subscription.png)
+
+![statusline api](assets/statusline-api.png)
 
 ## Features
 
@@ -19,6 +21,8 @@ A simple, no-frills statusline for [Claude Code](https://docs.anthropic.com/en/d
 - **Cross-platform** — works on macOS, Linux, and Windows
 - **Non-blocking** — returns cached data instantly, refreshes quota in the background
 - **Color-coded** — green/orange/red percentages at a glance
+- **Context velocity** — estimates remaining turns until context compaction (`42% →~8t`), with directional arrows showing if burn rate is accelerating (↑), steady (→), or decelerating (↓)
+- **Quota pressure** — reset time changes color based on projected burn rate: green (safe), orange (cutting it close), red (will hit the limit before reset). The 7d percentage color is also overridden when the projection says danger
 - **Project name** — bold uppercase project directory name so you never mix up sessions
 - **Git-aware** — shows the current branch name in repos (cached 30s to reduce overhead)
 - **API cost tracking** — pay-as-you-go API users see cumulative session cost instead of quota
@@ -98,12 +102,12 @@ To uninstall, remove `~/.claude/statusline/` and the `"statusLine"` block from s
 1. Receives model/context/cost info from Claude Code via stdin (JSON)
 2. Reads cached quota data and returns immediately (never blocks the UI)
 3. If the cache is stale (>2 minutes), refreshes from Anthropic's OAuth API in the background
-4. Converts UTC reset time to your local timezone
+4. Tracks context usage and quota utilization over time to compute velocity/burn rate predictions
 5. Outputs a formatted statusline with ANSI colors
 
 **Subscription users** see quota percentages and reset times. **API (pay-as-you-go) users** see cumulative session cost (e.g. `$4.72`) — calculated by Claude Code from actual token usage, no external pricing lookups needed.
 
-Quota data is cached to the system temp directory and refreshed every 2 minutes. Since Claude Code calls the statusline on every message update, this avoids excessive API calls while keeping the data fresh.
+Quota data is cached to the system temp directory and refreshed every 2 minutes. Context and quota history are tracked across invocations to power the predictive features — both reset automatically when a new window or compaction is detected.
 
 ## Troubleshooting
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-simple-status",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "A simple statusline for Claude Code — project name, git branch, model, context usage, quota, and API costs at a glance",
   "type": "module",
   "bin": {

package/statusline.mjs

@@ -45,6 +45,11 @@ const CACHE_MAX_AGE = 120; // seconds - when to fetch
 const CACHE_STALE_AGE = 300; // seconds - when to show "--" instead of old values
 const GIT_BRANCH_CACHE = join(tmpdir(), 'claude-statusline-branches.json');
 const GIT_BRANCH_MAX_AGE = 30; // seconds
+const CONTEXT_HISTORY_FILE = join(tmpdir(), 'claude-statusline-context.json');
+const CONTEXT_COMPACT_THRESHOLD = 95; // % at which compaction typically fires
+const CONTEXT_MAX_SAMPLES = 20; // rolling window of turn deltas
+const QUOTA_HISTORY_FILE = join(tmpdir(), 'claude-statusline-quota-history.json');
+const QUOTA_MAX_READINGS = 30; // ~1h of data at 120s refresh intervals
 
 // Color a percentage value based on thresholds
 function colorPct(val) {
@@ -188,6 +193,130 @@ function getGitBranch() {
     }
 }
 
+// Track context % over time and estimate remaining turns until compaction
+// Returns { arrow, turnsLeft } or null if not enough data
+function getContextVelocity(projectDir, contextUsed) {
+    if (!projectDir || typeof contextUsed !== 'number') return null;
+
+    const now = Date.now();
+    const history = readJsonFile(CONTEXT_HISTORY_FILE) || {};
+    const entry = history[projectDir] || { readings: [], deltas: [] };
+
+    // Append current reading
+    const last = entry.readings[entry.readings.length - 1];
+    entry.readings.push({ pct: contextUsed, ts: now });
+
+    // Detect a new "turn": context jumped since last reading
+    // (statusline is polled every ~2s, but context only changes between turns)
+    if (last && contextUsed > last.pct) {
+        const delta = contextUsed - last.pct;
+        // Ignore tiny noise (<0.1%) and impossibly large jumps (>30% = probably a new session)
+        if (delta >= 0.1 && delta <= 30) {
+            entry.deltas.push(delta);
+            if (entry.deltas.length > CONTEXT_MAX_SAMPLES) {
+                entry.deltas = entry.deltas.slice(-CONTEXT_MAX_SAMPLES);
+            }
+        }
+    }
+
+    // Context went down = compaction happened or new session, reset tracking
+    if (last && contextUsed < last.pct - 1) {
+        entry.readings = [{ pct: contextUsed, ts: now }];
+        entry.deltas = [];
+    }
+
+    // Keep only last 2 readings (we just need prev + current to detect jumps)
+    if (entry.readings.length > 2) {
+        entry.readings = entry.readings.slice(-2);
+    }
+
+    history[projectDir] = entry;
+    try { writeFileSync(CONTEXT_HISTORY_FILE, JSON.stringify(history)); } catch {}
+
+    // Need at least 2 turn deltas to estimate
+    if (entry.deltas.length < 2) return null;
+
+    // Weighted average: recent deltas matter more
+    let weightSum = 0;
+    let deltaSum = 0;
+    for (let i = 0; i < entry.deltas.length; i++) {
+        const weight = i + 1; // linear: older=1, newest=N
+        deltaSum += entry.deltas[i] * weight;
+        weightSum += weight;
+    }
+    const avgDelta = deltaSum / weightSum;
+
+    const remaining = CONTEXT_COMPACT_THRESHOLD - contextUsed;
+    if (remaining <= 0 || avgDelta <= 0) return { arrow: '\u2191', turnsLeft: 0 };
+
+    const turnsLeft = Math.round(remaining / avgDelta);
+
+    // Arrow based on trend (last 3 deltas vs overall average)
+    const recentSlice = entry.deltas.slice(-3);
+    const recentAvg = recentSlice.reduce((a, b) => a + b, 0) / recentSlice.length;
+    let arrow;
+    if (recentAvg > avgDelta * 1.3) arrow = '\u2191'; // accelerating ↑
+    else if (recentAvg < avgDelta * 0.7) arrow = '\u2193'; // decelerating ↓
+    else arrow = '\u2192'; // steady →
+
+    return { arrow, turnsLeft };
+}
+
+// Predict whether quota will be exhausted before the reset window
+// windowKey: '5h' or '7d' — used to track readings separately
+// Returns 'safe' | 'tight' | 'danger' | null
+function getQuotaPressure(windowKey, utilization, resetsAtIso) {
+    if (typeof utilization !== 'number' || !resetsAtIso) return null;
+
+    const now = Date.now();
+    const resetsAt = new Date(resetsAtIso).getTime();
+    const msUntilReset = resetsAt - now;
+    if (msUntilReset <= 0) return null; // reset imminent, no point predicting
+
+    const allHistory = readJsonFile(QUOTA_HISTORY_FILE) || {};
+    const history = allHistory[windowKey] || { readings: [] };
+
+    // Record new reading if quota changed (API refreshes every ~120s)
+    const last = history.readings[history.readings.length - 1];
+    if (!last || last.pct !== utilization) {
+        history.readings.push({ pct: utilization, ts: now });
+        if (history.readings.length > QUOTA_MAX_READINGS) {
+            history.readings = history.readings.slice(-QUOTA_MAX_READINGS);
+        }
+    }
+
+    // Quota dropped = new window started, reset history
+    if (last && utilization < last.pct - 5) {
+        history.readings = [{ pct: utilization, ts: now }];
+    }
+
+    allHistory[windowKey] = history;
+    try { writeFileSync(QUOTA_HISTORY_FILE, JSON.stringify(allHistory)); } catch {}
+
+    // Need at least 2 distinct readings to compute rate
+    if (history.readings.length < 2) return null;
+
+    const oldest = history.readings[0];
+    const elapsedMs = now - oldest.ts;
+    if (elapsedMs < 60_000) return null; // need at least 1 min of data
+
+    const pctGained = utilization - oldest.pct;
+    if (pctGained <= 0) return 'safe'; // not growing
+
+    // % per millisecond → extrapolate time to 100%
+    const rate = pctGained / elapsedMs;
+    const pctRemaining = 100 - utilization;
+    const msTo100 = pctRemaining / rate;
+
+    // Compare projected exhaustion time to reset time
+    const exhaustsAt = now + msTo100;
+    const bufferMs = 30 * 60_000; // 30 min buffer for "tight"
+
+    if (exhaustsAt < resetsAt) return 'danger';          // will hit limit before reset
+    if (exhaustsAt < resetsAt + bufferMs) return 'tight'; // cutting it close
+    return 'safe';
+}
+
 // Main
 async function main() {
     // Read stdin
@@ -201,6 +330,7 @@ async function main() {
     let contextUsed = 0;
     let totalCostUsd = null;
     let projectName = null;
+    let projectDir = null;
     try {
         const data = JSON.parse(input);
         model = data.model?.display_name || 'Unknown';
@@ -209,7 +339,8 @@ async function main() {
             totalCostUsd = data.cost.total_cost_usd;
         }
         if (data.workspace?.project_dir) {
-            projectName = basename(data.workspace.project_dir).toUpperCase();
+            projectDir = data.workspace.project_dir;
+            projectName = basename(projectDir).toUpperCase();
         }
     } catch {}
 
@@ -238,6 +369,8 @@ async function main() {
     let fiveHourPct = '?';
     let sevenDayPct = '?';
     let resetLocal = '--:--';
+    let fiveHourResetsAt = null;
+    let sevenDayResetsAt = null;
     const cacheIsStale = !quotaData || getFileAge(CACHE_FILE) > CACHE_STALE_AGE;
 
     if (cacheIsStale) {
@@ -253,7 +386,9 @@ async function main() {
         } else {
             fiveHourPct = quotaData.five_hour?.utilization ?? '?';
             sevenDayPct = quotaData.seven_day?.utilization ?? '?';
-            resetLocal = toLocalTime(quotaData.five_hour?.resets_at);
+            fiveHourResetsAt = quotaData.five_hour?.resets_at;
+            sevenDayResetsAt = quotaData.seven_day?.resets_at;
+            resetLocal = toLocalTime(fiveHourResetsAt);
         }
     }
 
@@ -264,11 +399,14 @@ async function main() {
         hasError = errContent.length > 0;
     } catch {}
 
-    // Get rig profile (claude-rig sets CLAUDE_CONFIG_DIR to ~/.claude-rig/profiles/<name>)
+    // Get context velocity estimate
+    const velocity = getContextVelocity(projectDir, contextUsed);
+
+    // Get rig name (claude-rig sets CLAUDE_CONFIG_DIR to ~/.claude-rig/rigs/<name>)
     const rigProfile = (() => {
         const configDir = process.env.CLAUDE_CONFIG_DIR;
         if (!configDir) return null;
-        const match = configDir.match(/\.claude-rig\/profiles\/([^/]+)\/?$/);
+        const match = configDir.match(/\.claude-rig\/rigs\/([^/]+)\/?$/);
         return match ? match[1] : null;
     })();
 
@@ -279,9 +417,30 @@ async function main() {
     const projectSegment = projectName
         ? `${WHITE_BOLD}${projectName}${branch ? ` ${YELLOW_BOLD}[${branch}]` : ''}${RESET}`
         : (branch ? `${YELLOW_BOLD}${branch}${RESET}` : '');
-    let output = `${projectSegment ? `${projectSegment} | ` : ''}${rigProfile ? `${MAGENTA_BOLD}${rigProfile}${RESET} | ` : ''}${CYAN}${model}${RESET} | ${colorPct(contextUsed)}`;
+    // Format velocity: "42% →~8t" or just "42%" if not enough data yet
+    let contextDisplay = colorPct(contextUsed);
+    if (velocity) {
+        const turnsStr = velocity.turnsLeft === 0 ? '!' : `~${velocity.turnsLeft}t`;
+        const turnsColor = velocity.turnsLeft <= 5 ? RED : velocity.turnsLeft <= 15 ? ORANGE : GREEN;
+        contextDisplay += ` ${turnsColor}${velocity.arrow}${turnsStr}${RESET}`;
+    }
+
+    // Color the reset time based on 5h quota burn rate projection
+    const fiveHourPressure = getQuotaPressure('5h', fiveHourPct, fiveHourResetsAt);
+    let resetDisplay = resetLocal;
+    if (fiveHourPressure === 'danger') resetDisplay = `${RED}${resetLocal}${RESET}`;
+    else if (fiveHourPressure === 'tight') resetDisplay = `${ORANGE}${resetLocal}${RESET}`;
+    else if (fiveHourPressure === 'safe') resetDisplay = `${GREEN}${resetLocal}${RESET}`;
+
+    // Override 7d percentage color when burn rate projects exhaustion before reset
+    const sevenDayPressure = getQuotaPressure('7d', sevenDayPct, sevenDayResetsAt);
+    let sevenDayDisplay = colorPct(sevenDayPct);
+    if (sevenDayPressure === 'danger') sevenDayDisplay = `${RED}${sevenDayPct}%${RESET}`;
+    else if (sevenDayPressure === 'tight') sevenDayDisplay = `${ORANGE}${sevenDayPct}%${RESET}`;
+
+    let output = `${projectSegment ? `${projectSegment} | ` : ''}${rigProfile ? `${MAGENTA_BOLD}${rigProfile}${RESET} | ` : ''}${CYAN}${model}${RESET} | ${contextDisplay}`;
     if (token) {
-        output += ` | ${resetLocal} | 5h:${colorPct(fiveHourPct)} | 7d:${colorPct(sevenDayPct)}`;
+        output += ` | ${resetDisplay} | 5h:${colorPct(fiveHourPct)} | 7d:${sevenDayDisplay}`;
         if (hasError) {
             output += ` | ${RED}ERR${RESET}`;
         }