cc-context-stats 1.6.2 → 1.8.0

package/src/claude_statusline/graphs/intelligence.py

@@ -0,0 +1,162 @@
+"""Model Intelligence (MI) score computation.
+
+Estimates answer quality based on context utilization, cache efficiency,
+and output productivity. Inspired by the Michelangelo paper
+(arXiv:2409.12640, Google DeepMind, Sep 2024).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from claude_statusline.core.state import StateEntry
+
+# Hardcoded constants — not configurable, to minimize cross-implementation sync burden
+MI_WEIGHT_CPS = 0.60
+MI_WEIGHT_ES = 0.25
+MI_WEIGHT_PS = 0.15
+MI_GREEN_THRESHOLD = 0.65
+MI_YELLOW_THRESHOLD = 0.35
+MI_PRODUCTIVITY_TARGET = 0.2
+
+
+@dataclass
+class IntelligenceConfig:
+    """Configuration for MI computation."""
+
+    beta: float = 1.5
+
+
+@dataclass
+class IntelligenceScore:
+    """MI score with sub-components."""
+
+    cps: float
+    es: float
+    ps: float
+    mi: float
+    utilization: float
+
+
+def calculate_context_pressure(utilization: float, beta: float = 1.5) -> float:
+    """Calculate Context Pressure Score (CPS).
+
+    CPS = max(0, 1 - u^beta) where u is utilization ratio [0, 1+].
+
+    Args:
+        utilization: Context utilization ratio (current_used / context_window_size)
+        beta: Curve shape parameter (default 1.5)
+
+    Returns:
+        CPS value in [0, 1]
+    """
+    if utilization <= 0:
+        return 1.0
+    return max(0.0, 1.0 - utilization**beta)
+
+
+def calculate_efficiency(entry: StateEntry) -> float:
+    """Calculate Efficiency Score (ES).
+
+    ES = 0.3 + 0.7 * cache_hit_ratio, where cache_hit_ratio = cache_read / total_context.
+
+    Args:
+        entry: Current state entry
+
+    Returns:
+        ES value in [0.3, 1.0]
+    """
+    total_context = entry.current_used_tokens
+    if total_context == 0:
+        return 1.0
+    cache_hit_ratio = entry.cache_read / total_context
+    return 0.3 + 0.7 * cache_hit_ratio
+
+
+def calculate_productivity(
+    current: StateEntry, previous: StateEntry | None
+) -> float:
+    """Calculate Productivity Score (PS).
+
+    Uses consecutive entry diffs for delta_lines and delta_output_tokens.
+
+    Args:
+        current: Current state entry
+        previous: Previous state entry, or None
+
+    Returns:
+        PS value in [0.2, 1.0], or 0.5 if no previous entry
+    """
+    if previous is None:
+        return 0.5
+
+    delta_lines_added = current.lines_added - previous.lines_added
+    delta_lines_removed = current.lines_removed - previous.lines_removed
+    delta_output_tokens = current.total_output_tokens - previous.total_output_tokens
+
+    if delta_output_tokens <= 0:
+        return 0.5
+
+    delta_lines = delta_lines_added + delta_lines_removed
+    ratio = delta_lines / delta_output_tokens
+    normalized = min(1.0, ratio / MI_PRODUCTIVITY_TARGET)
+    return 0.2 + 0.8 * normalized
+
+
+def calculate_intelligence(
+    current: StateEntry,
+    previous: StateEntry | None,
+    context_window_size: int,
+    beta: float = 1.5,
+) -> IntelligenceScore:
+    """Calculate composite Model Intelligence score.
+
+    Args:
+        current: Current state entry
+        previous: Previous state entry (for productivity delta)
+        context_window_size: Total context window size in tokens
+        beta: CPS curve shape parameter
+
+    Returns:
+        IntelligenceScore with all sub-scores and composite MI
+    """
+    # Guard clause: unknown context window
+    if context_window_size == 0:
+        return IntelligenceScore(cps=1.0, es=1.0, ps=0.5, mi=1.0, utilization=0.0)
+
+    utilization = current.current_used_tokens / context_window_size
+    cps = calculate_context_pressure(utilization, beta)
+    es = calculate_efficiency(current)
+    ps = calculate_productivity(current, previous)
+
+    mi = MI_WEIGHT_CPS * cps + MI_WEIGHT_ES * es + MI_WEIGHT_PS * ps
+
+    return IntelligenceScore(cps=cps, es=es, ps=ps, mi=mi, utilization=utilization)
+
+
+def get_mi_color(mi: float) -> str:
+    """Get color name for MI score.
+
+    Args:
+        mi: MI score value
+
+    Returns:
+        Color name: "green", "yellow", or "red"
+    """
+    if mi > MI_GREEN_THRESHOLD:
+        return "green"
+    if mi > MI_YELLOW_THRESHOLD:
+        return "yellow"
+    return "red"
+
+
+def format_mi_score(mi: float) -> str:
+    """Format MI score for display.
+
+    Args:
+        mi: MI score value
+
+    Returns:
+        Formatted string like "0.82"
+    """
+    return f"{mi:.2f}"

package/src/claude_statusline/graphs/renderer.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import shutil
+from collections.abc import Callable
 from dataclasses import dataclass
 
 from claude_statusline.core.colors import ColorManager
@@ -94,6 +95,7 @@ class GraphRenderer:
         timestamps: list[int],
         title: str,
         color: str,
+        label_fn: Callable[[int], str] | None = None,
     ) -> None:
         """Render a timeseries ASCII graph.
 
@@ -102,6 +104,7 @@ class GraphRenderer:
             timestamps: Corresponding timestamps for x-axis labels
             title: Graph title
             color: ANSI color code for the graph
+            label_fn: Optional function to format Y-axis labels. If None, uses format_tokens().
         """
         n = len(data)
         if n == 0:
@@ -119,12 +122,14 @@ class GraphRenderer:
         width = self.dimensions.graph_width
         height = self.dimensions.graph_height
 
+        fmt = label_fn if label_fn else lambda v: format_tokens(v, self.token_detail)
+
         # Print title and stats
         self._emit()
         self._emit(f"{self.colors.bold}{title}{self.colors.reset}")
         self._emit(
-            f"{self.colors.dim}Max: {format_tokens(max_val, self.token_detail)}  "
-            f"Min: {format_tokens(min_val, self.token_detail)}  "
+            f"{self.colors.dim}Max: {fmt(max_val)}  "
+            f"Min: {fmt(min_val)}  "
             f"Points: {n}{self.colors.reset}"
         )
         self._emit()
@@ -138,7 +143,7 @@ class GraphRenderer:
 
             # Show labels at top, middle, and bottom
             if r == 0 or r == height // 2 or r == height - 1:
-                label = format_tokens(val, self.token_detail)
+                label = fmt(val)
             else:
                 label = ""
 
@@ -259,12 +264,14 @@ class GraphRenderer:
         self,
         entries: list,  # list[StateEntry]
         deltas: list[int],
+        mi_score: object | None = None,  # IntelligenceScore
     ) -> None:
         """Render summary statistics.
 
         Args:
             entries: List of StateEntry objects
             deltas: List of token deltas
+            mi_score: Optional IntelligenceScore for MI display
         """
         if not entries:
             return
@@ -316,6 +323,34 @@ class GraphRenderer:
                 f"  {status_color}{self.colors.bold}>>> {status_text.upper()} <<<{self.colors.reset} "
                 f"{self.colors.dim}({status_hint}){self.colors.reset}"
             )
+
+        # Model Intelligence score
+        if mi_score is not None:
+            from claude_statusline.graphs.intelligence import (
+                format_mi_score,
+                get_mi_color,
+            )
+
+            mi_color_name = get_mi_color(mi_score.mi)
+            mi_color = getattr(self.colors, mi_color_name)
+            if mi_score.mi > 0.65:
+                mi_hint = "Model is operating well"
+            elif mi_score.mi > 0.35:
+                mi_hint = "Context pressure is degrading answer quality"
+            else:
+                mi_hint = "Severely degraded, consider new session"
+            self._emit(
+                f"  {mi_color}{'Model Intelligence:':<20}{self.colors.reset} "
+                f"{format_mi_score(mi_score.mi)}  "
+                f"{self.colors.dim}({mi_hint}){self.colors.reset}"
+            )
+            self._emit(
+                f"  {self.colors.dim}  CPS: {mi_score.cps:.2f}  "
+                f"ES: {mi_score.es:.2f}  "
+                f"PS: {mi_score.ps:.2f}{self.colors.reset}"
+            )
+
+        if last.context_window_size > 0:
             self._emit()
 
         # Session details (ordered: Last Growth, I/O, Lines, Cost, Model, Duration)

package/tests/bash/test_statusline_full.bats

@@ -38,7 +38,7 @@ teardown() {
     result=$(cat "$FIXTURES/valid_full.json" | "$SCRIPT")
     [[ "$result" == *"Opus 4.5"* ]]
     [[ "$result" == *"my-project"* ]]
-    [[ "$result" == *"free"* ]]
+    [[ "$result" == *"%"* ]]
 }
 
 @test "shows AC indicator when autocompact enabled" {
@@ -58,8 +58,8 @@ teardown() {
     input='{"model":{"display_name":"Claude"},"workspace":{"current_dir":"/tmp","project_dir":"/tmp"},"context_window":{"context_window_size":200000,"current_usage":{"input_tokens":10000,"cache_creation_input_tokens":0,"cache_read_input_tokens":0}}}'
     result=$(echo "$input" | "$SCRIPT")
     # Should NOT show 'k' suffix by default, should show comma-formatted number
-    [[ "$result" != *"k free"* ]]
-    [[ "$result" == *"free"* ]]
+    [[ "$result" != *"k ("* ]]
+    [[ "$result" == *"%"* ]]
 }
 
 @test "shows abbreviated tokens when token_detail=false" {
@@ -67,7 +67,7 @@ teardown() {
     input='{"model":{"display_name":"Claude"},"workspace":{"current_dir":"/tmp","project_dir":"/tmp"},"context_window":{"context_window_size":200000,"current_usage":{"input_tokens":10000,"cache_creation_input_tokens":0,"cache_read_input_tokens":0}}}'
     result=$(echo "$input" | "$SCRIPT")
     # Should show 'k' suffix for abbreviated format
-    [[ "$result" == *"k free"* ]]
+    [[ "$result" == *"k ("* ]]
 }
 
 @test "handles missing context window gracefully" {
@@ -79,7 +79,7 @@ teardown() {
 @test "calculates free tokens percentage correctly" {
     # Low usage fixture: 30k tokens used out of 200k = 85% free
     result=$(cat "$FIXTURES/low_usage.json" | "$SCRIPT")
-    [[ "$result" == *"free"* ]]
+    [[ "$result" == *"%"* ]]
 }
 
 @test "uses fixture files correctly" {

package/tests/fixtures/mi_test_vectors.json

@@ -0,0 +1,140 @@
+[
+  {
+    "description": "Fresh session - low utilization, good cache, productive",
+    "input": {
+      "current_used": 20000,
+      "context_window": 200000,
+      "cache_read": 12000,
+      "current_input": 5000,
+      "cache_creation": 3000,
+      "prev_lines_added": 0,
+      "prev_lines_removed": 0,
+      "cur_lines_added": 150,
+      "cur_lines_removed": 10,
+      "prev_output": 0,
+      "cur_output": 1000,
+      "beta": 1.5
+    },
+    "expected": {
+      "cps": 0.968,
+      "es": 0.72,
+      "ps": 0.84,
+      "mi": 0.887
+    }
+  },
+  {
+    "description": "Mid-session - moderate utilization, some cache, moderate productivity",
+    "input": {
+      "current_used": 100000,
+      "context_window": 200000,
+      "cache_read": 40000,
+      "current_input": 35000,
+      "cache_creation": 25000,
+      "prev_lines_added": 50,
+      "prev_lines_removed": 10,
+      "cur_lines_added": 150,
+      "cur_lines_removed": 20,
+      "prev_output": 500,
+      "cur_output": 1500,
+      "beta": 1.5
+    },
+    "expected": {
+      "cps": 0.646,
+      "es": 0.58,
+      "ps": 0.64,
+      "mi": 0.629
+    }
+  },
+  {
+    "description": "Late session - high utilization, low cache, low productivity",
+    "input": {
+      "current_used": 170000,
+      "context_window": 200000,
+      "cache_read": 34000,
+      "current_input": 85000,
+      "cache_creation": 51000,
+      "prev_lines_added": 200,
+      "prev_lines_removed": 50,
+      "cur_lines_added": 250,
+      "cur_lines_removed": 55,
+      "prev_output": 2000,
+      "cur_output": 3000,
+      "beta": 1.5
+    },
+    "expected": {
+      "cps": 0.217,
+      "es": 0.44,
+      "ps": 0.42,
+      "mi": 0.303
+    }
+  },
+  {
+    "description": "No previous entry - PS defaults to 0.5",
+    "input": {
+      "current_used": 50000,
+      "context_window": 200000,
+      "cache_read": 30000,
+      "current_input": 10000,
+      "cache_creation": 10000,
+      "prev_lines_added": null,
+      "prev_lines_removed": null,
+      "cur_lines_added": 100,
+      "cur_lines_removed": 5,
+      "prev_output": null,
+      "cur_output": 800,
+      "beta": 1.5
+    },
+    "expected": {
+      "cps": 0.875,
+      "es": 0.72,
+      "ps": 0.5,
+      "mi": 0.780
+    }
+  },
+  {
+    "description": "Context window is zero - guard clause returns defaults",
+    "input": {
+      "current_used": 50000,
+      "context_window": 0,
+      "cache_read": 30000,
+      "current_input": 10000,
+      "cache_creation": 10000,
+      "prev_lines_added": 0,
+      "prev_lines_removed": 0,
+      "cur_lines_added": 100,
+      "cur_lines_removed": 5,
+      "prev_output": 0,
+      "cur_output": 800,
+      "beta": 1.5
+    },
+    "expected": {
+      "cps": 1.0,
+      "es": 1.0,
+      "ps": 0.5,
+      "mi": 1.0
+    }
+  },
+  {
+    "description": "No cache at all - ES at minimum floor",
+    "input": {
+      "current_used": 80000,
+      "context_window": 200000,
+      "cache_read": 0,
+      "current_input": 80000,
+      "cache_creation": 0,
+      "prev_lines_added": 0,
+      "prev_lines_removed": 0,
+      "cur_lines_added": 50,
+      "cur_lines_removed": 10,
+      "prev_output": 0,
+      "cur_output": 500,
+      "beta": 1.5
+    },
+    "expected": {
+      "cps": 0.747,
+      "es": 0.3,
+      "ps": 0.68,
+      "mi": 0.625
+    }
+  }
+]

package/tests/node/intelligence.test.js

@@ -0,0 +1,98 @@
+/**
+ * Tests for Model Intelligence (MI) score computation.
+ * Uses shared test vectors for cross-implementation parity.
+ */
+
+const path = require('path');
+const fs = require('fs');
+const { computeMI } = require('../../scripts/statusline');
+
+const VECTORS_PATH = path.join(__dirname, '..', 'fixtures', 'mi_test_vectors.json');
+const vectors = JSON.parse(fs.readFileSync(VECTORS_PATH, 'utf8'));
+
+describe('computeMI', () => {
+    test('guard clause: context_window=0 returns defaults', () => {
+        const result = computeMI(50000, 0, 30000, 50000, 0, null, 1.5);
+        expect(result.mi).toBe(1.0);
+        expect(result.cps).toBe(1.0);
+        expect(result.es).toBe(1.0);
+        expect(result.ps).toBe(0.5);
+    });
+
+    test('empty context returns CPS=1', () => {
+        const result = computeMI(0, 200000, 0, 0, 0, null, 1.5);
+        expect(result.cps).toBe(1.0);
+    });
+
+    test('full context returns CPS=0', () => {
+        const result = computeMI(200000, 200000, 0, 200000, 0, 100, 1.5);
+        expect(result.cps).toBe(0);
+    });
+
+    test('no cache returns ES=0.3', () => {
+        const result = computeMI(100000, 200000, 0, 100000, 0, null, 1.5);
+        expect(result.es).toBeCloseTo(0.3, 1);
+    });
+
+    test('all cache returns ES=1.0', () => {
+        const result = computeMI(100000, 200000, 100000, 100000, 0, null, 1.5);
+        expect(result.es).toBeCloseTo(1.0, 1);
+    });
+
+    test('no previous returns PS=0.5', () => {
+        const result = computeMI(100000, 200000, 50000, 100000, 0, null, 1.5);
+        expect(result.ps).toBe(0.5);
+    });
+
+    test('no output returns PS=0.5', () => {
+        const result = computeMI(100000, 200000, 50000, 100000, 100, 0, 1.5);
+        expect(result.ps).toBe(0.5);
+    });
+
+    test('MI is always between 0 and 1', () => {
+        const utilizations = [0, 0.1, 0.3, 0.5, 0.7, 0.9, 1.0];
+        for (const u of utilizations) {
+            const used = Math.floor(u * 200000);
+            const result = computeMI(used, 200000, used / 2, used, 50, 500, 1.5);
+            expect(result.mi).toBeGreaterThanOrEqual(0);
+            expect(result.mi).toBeLessThanOrEqual(1);
+        }
+    });
+});
+
+describe('shared test vectors', () => {
+    vectors.forEach((vec) => {
+        test(vec.description, () => {
+            const inp = vec.input;
+            const exp = vec.expected;
+
+            const hasPrev = inp.prev_output !== null;
+            let deltaLines, deltaOutput;
+
+            if (hasPrev) {
+                const deltaLA = inp.cur_lines_added - inp.prev_lines_added;
+                const deltaLR = inp.cur_lines_removed - inp.prev_lines_removed;
+                deltaLines = deltaLA + deltaLR;
+                deltaOutput = inp.cur_output - inp.prev_output;
+            } else {
+                deltaLines = 0;
+                deltaOutput = null;
+            }
+
+            const result = computeMI(
+                inp.current_used,
+                inp.context_window,
+                inp.cache_read,
+                inp.current_used,
+                deltaLines,
+                deltaOutput,
+                inp.beta
+            );
+
+            expect(result.cps).toBeCloseTo(exp.cps, 1);
+            expect(result.es).toBeCloseTo(exp.es, 1);
+            expect(result.ps).toBeCloseTo(exp.ps, 1);
+            expect(result.mi).toBeCloseTo(exp.mi, 1);
+        });
+    });
+});

package/tests/node/statusline.test.js

@@ -97,7 +97,7 @@ describe('statusline.js', () => {
 
         test('shows free tokens indicator', async () => {
             const result = await runScript(sampleInput);
-            expect(result.stdout).toContain('free');
+            expect(result.stdout).toContain('%');
         });
 
         test('shows AC indicator', async () => {
@@ -162,21 +162,21 @@ describe('statusline.js', () => {
             const input = loadFixture('low_usage');
             const result = await runScript(input);
             expect(result.code).toBe(0);
-            expect(result.stdout).toContain('free');
+            expect(result.stdout).toContain('%');
         });
 
         test('handles medium_usage fixture', async () => {
             const input = loadFixture('medium_usage');
             const result = await runScript(input);
             expect(result.code).toBe(0);
-            expect(result.stdout).toContain('free');
+            expect(result.stdout).toContain('%');
         });
 
         test('handles high_usage fixture', async () => {
             const input = loadFixture('high_usage');
             const result = await runScript(input);
             expect(result.code).toBe(0);
-            expect(result.stdout).toContain('free');
+            expect(result.stdout).toContain('%');
         });
 
         test('all JSON fixtures succeed', async () => {

package/tests/python/test_colors.py

@@ -0,0 +1,105 @@
+"""Tests for configurable colors."""
+
+from claude_statusline.core.colors import (
+    BLUE,
+    CYAN,
+    GREEN,
+    MAGENTA,
+    RED,
+    YELLOW,
+    ColorManager,
+    parse_color,
+)
+
+
+class TestParseColor:
+    """Tests for parse_color()."""
+
+    def test_named_color_red(self):
+        assert parse_color("red") == "\033[0;31m"
+
+    def test_named_color_green(self):
+        assert parse_color("green") == "\033[0;32m"
+
+    def test_named_color_bright_cyan(self):
+        assert parse_color("bright_cyan") == "\033[0;96m"
+
+    def test_named_color_case_insensitive(self):
+        assert parse_color("RED") == "\033[0;31m"
+        assert parse_color("Green") == "\033[0;32m"
+
+    def test_hex_color(self):
+        result = parse_color("#ff5733")
+        assert result == "\033[38;2;255;87;51m"
+
+    def test_hex_color_uppercase(self):
+        result = parse_color("#FF5733")
+        assert result == "\033[38;2;255;87;51m"
+
+    def test_hex_color_black(self):
+        result = parse_color("#000000")
+        assert result == "\033[38;2;0;0;0m"
+
+    def test_hex_color_white(self):
+        result = parse_color("#ffffff")
+        assert result == "\033[38;2;255;255;255m"
+
+    def test_invalid_color_returns_none(self):
+        assert parse_color("nonexistent") is None
+
+    def test_empty_string_returns_none(self):
+        assert parse_color("") is None
+
+    def test_invalid_hex_returns_none(self):
+        assert parse_color("#xyz") is None
+        assert parse_color("#12345") is None
+        assert parse_color("#1234567") is None
+
+    def test_strips_whitespace(self):
+        assert parse_color("  red  ") == "\033[0;31m"
+        assert parse_color("  #ff5733  ") == "\033[38;2;255;87;51m"
+
+
+class TestColorManager:
+    """Tests for ColorManager with overrides."""
+
+    def test_defaults_without_overrides(self):
+        cm = ColorManager(enabled=True)
+        assert cm.green == GREEN
+        assert cm.yellow == YELLOW
+        assert cm.red == RED
+        assert cm.blue == BLUE
+        assert cm.magenta == MAGENTA
+        assert cm.cyan == CYAN
+
+    def test_override_single_color(self):
+        custom = "\033[38;2;255;0;0m"
+        cm = ColorManager(enabled=True, overrides={"green": custom})
+        assert cm.green == custom
+        # Others unchanged
+        assert cm.yellow == YELLOW
+        assert cm.red == RED
+
+    def test_override_multiple_colors(self):
+        overrides = {
+            "green": "\033[38;2;0;255;0m",
+            "red": "\033[38;2;255;0;0m",
+        }
+        cm = ColorManager(enabled=True, overrides=overrides)
+        assert cm.green == overrides["green"]
+        assert cm.red == overrides["red"]
+        assert cm.yellow == YELLOW  # not overridden
+
+    def test_disabled_returns_empty(self):
+        overrides = {"green": "\033[38;2;0;255;0m"}
+        cm = ColorManager(enabled=False, overrides=overrides)
+        assert cm.green == ""
+        assert cm.yellow == ""
+        assert cm.bold == ""
+        assert cm.reset == ""
+
+    def test_bold_dim_reset_not_overridable(self):
+        """bold, dim, reset are always the standard ANSI codes."""
+        cm = ColorManager(enabled=True, overrides={"bold": "custom"})
+        # bold is not in the _get path, it uses the hardcoded value
+        assert cm.bold == "\033[1m"