cc-context-stats 1.6.2 → 1.8.0

package/scripts/statusline.py

@@ -38,6 +38,53 @@ import tempfile
 ROTATION_THRESHOLD = 10_000
 ROTATION_KEEP = 5_000
 
+# Model Intelligence constants (hardcoded, not configurable)
+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
+
+
+def compute_mi(used_tokens, context_window_size, cache_read, total_context,
+               delta_lines, delta_output, beta=1.5):
+    """Compute Model Intelligence score. Returns (mi, cps, es, ps)."""
+    # Guard clause
+    if context_window_size == 0:
+        return (1.0, 1.0, 1.0, 0.5)
+
+    # CPS
+    u = used_tokens / context_window_size
+    cps = max(0.0, 1.0 - u ** beta) if u > 0 else 1.0
+
+    # ES
+    if total_context == 0:
+        es = 1.0
+    else:
+        cache_hit_ratio = cache_read / total_context
+        es = 0.3 + 0.7 * cache_hit_ratio
+
+    # PS
+    if delta_output is None or delta_output <= 0:
+        ps = 0.5
+    else:
+        ratio = delta_lines / delta_output
+        normalized = min(1.0, ratio / MI_PRODUCTIVITY_TARGET)
+        ps = 0.2 + 0.8 * normalized
+
+    mi = MI_WEIGHT_CPS * cps + MI_WEIGHT_ES * es + MI_WEIGHT_PS * ps
+    return (mi, cps, es, ps)
+
+
+def get_mi_color(mi):
+    """Return ANSI color code for MI score."""
+    if mi > MI_GREEN_THRESHOLD:
+        return GREEN
+    if mi > MI_YELLOW_THRESHOLD:
+        return YELLOW
+    return RED
+
 
 def maybe_rotate_state_file(state_file):
     """Rotate a state file if it exceeds ROTATION_THRESHOLD lines.
@@ -52,9 +99,7 @@ def maybe_rotate_state_file(state_file):
         if len(lines) <= ROTATION_THRESHOLD:
             return
         keep = lines[-ROTATION_KEEP:]
-        fd, tmp_path = tempfile.mkstemp(
-            dir=os.path.dirname(state_file), suffix=".tmp"
-        )
+        fd, tmp_path = tempfile.mkstemp(dir=os.path.dirname(state_file), suffix=".tmp")
         try:
             with os.fdopen(fd, "w") as tmp_f:
                 tmp_f.writelines(keep)
@@ -66,11 +111,10 @@ def maybe_rotate_state_file(state_file):
                 pass
             raise
     except OSError as e:
-        sys.stderr.write(
-            f"[statusline] warning: failed to rotate state file: {e}\n"
-        )
+        sys.stderr.write(f"[statusline] warning: failed to rotate state file: {e}\n")
+
 
-# ANSI Colors
+# ANSI Colors (defaults, overridable via config)
 BLUE = "\033[0;34m"
 MAGENTA = "\033[0;35m"
 CYAN = "\033[0;36m"
@@ -80,6 +124,48 @@ RED = "\033[0;31m"
 DIM = "\033[2m"
 RESET = "\033[0m"
 
+# Named colors for config parsing
+_COLOR_NAMES = {
+    "black": "\033[0;30m",
+    "red": "\033[0;31m",
+    "green": "\033[0;32m",
+    "yellow": "\033[0;33m",
+    "blue": "\033[0;34m",
+    "magenta": "\033[0;35m",
+    "cyan": "\033[0;36m",
+    "white": "\033[0;37m",
+    "bright_black": "\033[0;90m",
+    "bright_red": "\033[0;91m",
+    "bright_green": "\033[0;92m",
+    "bright_yellow": "\033[0;93m",
+    "bright_blue": "\033[0;94m",
+    "bright_magenta": "\033[0;95m",
+    "bright_cyan": "\033[0;96m",
+    "bright_white": "\033[0;97m",
+}
+
+
+def _parse_color(value):
+    """Parse a color name or #rrggbb hex into an ANSI escape code."""
+    value = value.strip().lower()
+    if value in _COLOR_NAMES:
+        return _COLOR_NAMES[value]
+    if re.match(r"^#[0-9a-f]{6}$", value):
+        r, g, b = int(value[1:3], 16), int(value[3:5], 16), int(value[5:7], 16)
+        return f"\033[38;2;{r};{g};{b}m"
+    return None
+
+
+# Color config keys and which color slot they map to
+_COLOR_KEYS = {
+    "color_green": "green",
+    "color_yellow": "yellow",
+    "color_red": "red",
+    "color_blue": "blue",
+    "color_magenta": "magenta",
+    "color_cyan": "cyan",
+}
+
 # Pattern to strip ANSI escape sequences
 _ANSI_RE = re.compile(r"\033\[[0-9;]*m")
 
@@ -132,8 +218,12 @@ def fit_to_width(parts, max_width):
     return result
 
 
-def get_git_info(project_dir):
+def get_git_info(project_dir, magenta=None, cyan=None):
     """Get git branch and change count"""
+    if magenta is None:
+        magenta = MAGENTA
+    if cyan is None:
+        cyan = CYAN
     git_dir = os.path.join(project_dir, ".git")
     if not os.path.isdir(git_dir):
         return ""
@@ -163,8 +253,8 @@ def get_git_info(project_dir):
         changes = len([line for line in result.stdout.split("\n") if line.strip()])
 
         if changes > 0:
-            return f" | {MAGENTA}{branch}{RESET} {CYAN}[{changes}]{RESET}"
-        return f" | {MAGENTA}{branch}{RESET}"
+            return f" | {magenta}{branch}{RESET} {cyan}[{changes}]{RESET}"
+        return f" | {magenta}{branch}{RESET}"
     except (subprocess.TimeoutExpired, OSError):
         return ""
 
@@ -177,6 +267,10 @@ def read_config():
         "show_delta": True,
         "show_session": True,
         "show_io_tokens": True,
+        "reduced_motion": False,
+        "show_mi": True,
+        "mi_curve_beta": 1.5,
+        "colors": {},
     }
     config_path = os.path.expanduser("~/.claude/statusline.conf")
 
@@ -198,6 +292,12 @@ show_delta=true
 
 # Show session_id in status line
 show_session=true
+
+# Custom colors - use named colors or hex (#rrggbb)
+# Available: color_green, color_yellow, color_red, color_blue, color_magenta, color_cyan
+# Examples:
+#   color_green=#7dcfff
+#   color_red=#f7768e
 """
                 )
         except Exception as e:
@@ -212,17 +312,31 @@ show_session=true
                     continue
                 key, value = line.split("=", 1)
                 key = key.strip()
-                value = value.strip().lower()
+                raw_value = value.strip()
+                value_lower = raw_value.lower()
                 if key == "autocompact":
-                    config["autocompact"] = value != "false"
+                    config["autocompact"] = value_lower != "false"
                 elif key == "token_detail":
-                    config["token_detail"] = value != "false"
+                    config["token_detail"] = value_lower != "false"
                 elif key == "show_delta":
-                    config["show_delta"] = value != "false"
+                    config["show_delta"] = value_lower != "false"
                 elif key == "show_session":
-                    config["show_session"] = value != "false"
+                    config["show_session"] = value_lower != "false"
                 elif key == "show_io_tokens":
-                    config["show_io_tokens"] = value != "false"
+                    config["show_io_tokens"] = value_lower != "false"
+                elif key == "reduced_motion":
+                    config["reduced_motion"] = value_lower != "false"
+                elif key == "show_mi":
+                    config["show_mi"] = value_lower != "false"
+                elif key == "mi_curve_beta":
+                    try:
+                        config["mi_curve_beta"] = float(raw_value)
+                    except ValueError:
+                        pass
+                elif key in _COLOR_KEYS:
+                    ansi = _parse_color(raw_value)
+                    if ansi:
+                        config["colors"][_COLOR_KEYS[key]] = ansi
     except (OSError, UnicodeDecodeError) as e:
         sys.stderr.write(f"[statusline] warning: failed to read config: {e}\n")
     return config
@@ -241,17 +355,28 @@ def main():
     model = data.get("model", {}).get("display_name", "Claude")
     dir_name = os.path.basename(cwd) or "~"
 
-    # Git info
-    git_info = get_git_info(project_dir)
-
     # Read settings from config file
     config = read_config()
     autocompact_enabled = config["autocompact"]
     token_detail = config["token_detail"]
     show_delta = config["show_delta"]
     show_session = config["show_session"]
+    show_mi = config["show_mi"]
+    mi_curve_beta = config["mi_curve_beta"]
     # Note: show_io_tokens setting is read but not yet implemented
 
+    # Apply color overrides from config
+    c = config.get("colors", {})
+    c_green = c.get("green", GREEN)
+    c_yellow = c.get("yellow", YELLOW)
+    c_red = c.get("red", RED)
+    c_blue = c.get("blue", BLUE)
+    c_magenta = c.get("magenta", MAGENTA)
+    c_cyan = c.get("cyan", CYAN)
+
+    # Git info (pass configurable colors)
+    git_info = get_git_info(project_dir, magenta=c_magenta, cyan=c_cyan)
+
     # Extract session_id once for reuse
     session_id = data.get("session_id")
 
@@ -259,6 +384,7 @@ def main():
     context_info = ""
     ac_info = ""
     delta_info = ""
+    mi_info = ""
     session_info = ""
     total_size = data.get("context_window", {}).get("context_window_size", 0)
     current_usage = data.get("context_window", {}).get("current_usage")
@@ -308,16 +434,16 @@ def main():
 
         # Color based on free percentage
         if free_pct_int > 50:
-            ctx_color = GREEN
+            ctx_color = c_green
         elif free_pct_int > 25:
-            ctx_color = YELLOW
+            ctx_color = c_yellow
         else:
-            ctx_color = RED
+            ctx_color = c_red
 
-        context_info = f" | {ctx_color}{free_display} free ({free_pct:.1f}%){RESET}"
+        context_info = f" | {ctx_color}{free_display} ({free_pct:.1f}%){RESET}"
 
-        # Calculate and display token delta if enabled
-        if show_delta:
+        # Read previous entry if needed for delta OR MI
+        if show_delta or show_mi:
             import glob
             import shutil
             import time
@@ -340,44 +466,66 @@ def main():
                 state_file = os.path.join(state_dir, "statusline.state")
             has_prev = False
             prev_tokens = 0
+            prev_lines_added = 0
+            prev_lines_removed = 0
+            prev_output_tokens = 0
             try:
                 if os.path.exists(state_file):
                     has_prev = True
-                    # Read last line to get previous context usage
+                    # Read last line to get previous state
                     with open(state_file) as f:
-                        lines = f.readlines()
-                        if lines:
-                            last_line = lines[-1].strip()
+                        file_lines = f.readlines()
+                        if file_lines:
+                            last_line = file_lines[-1].strip()
                             if "," in last_line:
-                                parts = last_line.split(",")
+                                csv_parts = last_line.split(",")
                                 # Calculate previous context usage:
                                 # cur_input + cache_creation + cache_read
                                 # CSV indices: cur_in[3], cache_create[5], cache_read[6]
-                                prev_cur_input = int(parts[3]) if len(parts) > 3 else 0
-                                prev_cache_creation = int(parts[5]) if len(parts) > 5 else 0
-                                prev_cache_read = int(parts[6]) if len(parts) > 6 else 0
+                                prev_cur_input = int(csv_parts[3]) if len(csv_parts) > 3 else 0
+                                prev_cache_creation = int(csv_parts[5]) if len(csv_parts) > 5 else 0
+                                prev_cache_read = int(csv_parts[6]) if len(csv_parts) > 6 else 0
                                 prev_tokens = prev_cur_input + prev_cache_creation + prev_cache_read
+                                # For MI productivity score
+                                prev_output_tokens = int(csv_parts[2]) if len(csv_parts) > 2 else 0
+                                prev_lines_added = int(csv_parts[8]) if len(csv_parts) > 8 else 0
+                                prev_lines_removed = int(csv_parts[9]) if len(csv_parts) > 9 else 0
                             else:
                                 # Old format - single value
                                 prev_tokens = int(last_line or 0)
             except (OSError, ValueError) as e:
                 sys.stderr.write(f"[statusline] warning: failed to read state file: {e}\n")
                 prev_tokens = 0
-            # Calculate delta (difference in context window usage)
-            delta = used_tokens - prev_tokens
-            # Only show positive delta (and skip first run when no previous state)
-            if has_prev and delta > 0:
-                if token_detail:
-                    delta_display = f"{delta:,}"
+
+            # Calculate and display token delta if enabled
+            if show_delta:
+                delta = used_tokens - prev_tokens
+                if has_prev and delta > 0:
+                    if token_detail:
+                        delta_display = f"{delta:,}"
+                    else:
+                        delta_display = f"{delta / 1000:.1f}k"
+                    delta_info = f" {DIM}[+{delta_display}]{RESET}"
+
+            # Calculate and display MI score if enabled
+            if show_mi:
+                if has_prev:
+                    delta_la = lines_added - prev_lines_added
+                    delta_lr = lines_removed - prev_lines_removed
+                    delta_lines = delta_la + delta_lr
+                    delta_output = total_output_tokens - prev_output_tokens
                 else:
-                    delta_display = f"{delta / 1000:.1f}k"
-                delta_info = f" {DIM}[+{delta_display}]{RESET}"
+                    delta_lines = 0
+                    delta_output = None
+                mi_val, _, _, _ = compute_mi(
+                    used_tokens, total_size, cache_read, used_tokens,
+                    delta_lines, delta_output, mi_curve_beta,
+                )
+                mi_color = get_mi_color(mi_val)
+                mi_info = f" {mi_color}MI:{mi_val:.2f}{RESET}"
+
             # Only append if context usage changed (avoid duplicates from multiple refreshes)
             if not has_prev or used_tokens != prev_tokens:
-                # Append current usage with comprehensive format
-                # Format: ts,total_in,total_out,cur_in,cur_out,cache_create,cache_read,
-                #         cost_usd,lines_added,lines_removed,session_id,model_id,project_dir,
-                #         context_window_size
                 try:
                     cur_input_tokens = current_usage.get("input_tokens", 0)
                     cur_output_tokens = current_usage.get("output_tokens", 0)
@@ -411,9 +559,9 @@ def main():
         session_info = f" {DIM}{session_id}{RESET}"
 
     # Output: [Model] directory | branch [changes] | XXk free (XX%) [+delta] [AC] [S:session_id]
-    base = f"{DIM}[{model}]{RESET} {BLUE}{dir_name}{RESET}"
+    base = f"{DIM}[{model}]{RESET} {c_blue}{dir_name}{RESET}"
     max_width = get_terminal_width()
-    parts = [base, git_info, context_info, delta_info, ac_info, session_info]
+    parts = [base, git_info, context_info, delta_info, mi_info, ac_info, session_info]
     print(fit_to_width(parts, max_width))
 
 

package/src/claude_statusline/__init__.py

@@ -3,7 +3,7 @@
 Never run out of context unexpectedly - monitor your session context in real-time.
 """
 
-__version__ = "1.6.2"
+__version__ = "1.8.0"
 
 from claude_statusline.core.config import Config
 from claude_statusline.core.state import StateFile

package/src/claude_statusline/cli/context_stats.py

@@ -46,17 +46,22 @@ def show_help() -> None:
 
 USAGE:
     context-stats [session_id] [options]
+    context-stats explain
 
 ARGUMENTS:
     session_id    Optional session ID. If not provided, uses the latest session.
 
+COMMANDS:
+    explain       Diagnostic dump of Claude Code's JSON context (pipe JSON to stdin)
+
 OPTIONS:
     --type <type>  Graph type to display:
                    - delta: Context growth per interaction (default)
                    - cumulative: Total context usage over time
                    - io: Input/output tokens over time
+                   - mi: Model Intelligence score over time
                    - both: Show cumulative and delta graphs
-                   - all: Show all graphs including I/O
+                   - all: Show all graphs including I/O and MI
     -w [interval]  Set refresh interval in seconds (default: 2)
     --no-watch     Show graphs once and exit (disable live monitoring)
     --no-color     Disable color output
@@ -89,6 +94,9 @@ EXAMPLES:
     # Output to file (no colors, single run)
     context-stats --no-watch --no-color > output.txt
 
+    # Diagnostic dump (pipe Claude Code JSON context)
+    echo '{"model":{"display_name":"Opus"},...}' | context-stats explain
+
 DATA SOURCE:
     Reads token history from ~/.claude/statusline/statusline.<session_id>.state
 """
@@ -104,7 +112,7 @@ def parse_args() -> argparse.Namespace:
     parser.add_argument("session_id", nargs="?", default=None, help="Session ID")
     parser.add_argument(
         "--type",
-        choices=["cumulative", "delta", "io", "both", "all"],
+        choices=["cumulative", "delta", "io", "mi", "both", "all"],
         default="delta",
         help="Graph type to display (default: delta)",
     )
@@ -277,8 +285,37 @@ def render_once(
             current_output, timestamps, "Output Tokens (per request)", colors.magenta
         )
 
+    # Compute MI scores for graph and summary
+    mi_score = None
+    if graph_type in ("mi", "all") or True:  # Always compute for summary
+        from claude_statusline.graphs.intelligence import calculate_intelligence
+
+        mi_config = config if config else Config.load()
+        beta = mi_config.mi_curve_beta if config else 1.5
+
+        mi_scores = []
+        for i, entry in enumerate(entries):
+            prev = entries[i - 1] if i > 0 else None
+            ctx_window = entry.context_window_size
+            score = calculate_intelligence(entry, prev, ctx_window, beta)
+            mi_scores.append(score)
+
+        if mi_scores:
+            mi_score = mi_scores[-1]
+
+        if graph_type in ("mi", "all") and len(mi_scores) > 0:
+            # Scale MI scores to [0, 1000] for integer renderer
+            mi_data = [int(s.mi * 1000) for s in mi_scores]
+            renderer.render_timeseries(
+                mi_data,
+                timestamps,
+                "Model Intelligence Over Time",
+                colors.yellow,
+                label_fn=lambda v: f"{v / 1000:.2f}",
+            )
+
     # Summary and footer
-    renderer.render_summary(entries, deltas)
+    renderer.render_summary(entries, deltas, mi_score=mi_score)
     renderer.render_footer(__version__)
 
     if watch_mode:
@@ -345,16 +382,23 @@ def run_watch_mode(
                 # Show waiting message for new session
                 reduced_motion = config.reduced_motion if config else False
                 text = get_waiting_text(cycle_counter, reduced_motion)
-                buf_lines.append(_format_waiting_message(
-                    colors,
-                    state_file.session_id,
-                    text,
-                ))
+                buf_lines.append(
+                    _format_waiting_message(
+                        colors,
+                        state_file.session_id,
+                        text,
+                    )
+                )
             else:
                 # Render graphs (returns buffered string in watch mode)
                 result = render_once(
-                    state_file, graph_type, renderer, colors,
-                    watch_mode=True, config=config, cycle_index=cycle_counter,
+                    state_file,
+                    graph_type,
+                    renderer,
+                    colors,
+                    watch_mode=True,
+                    config=config,
+                    cycle_index=cycle_counter,
                 )
                 if isinstance(result, str):
                     buf_lines.append(result)
@@ -400,7 +444,9 @@ def _format_waiting_message(
     lines.append(
         f"  {colors.dim}The session has just started and no data has been recorded yet.{colors.reset}"
     )
-    lines.append(f"  {colors.dim}Data will appear after the first Claude interaction.{colors.reset}")
+    lines.append(
+        f"  {colors.dim}Data will appear after the first Claude interaction.{colors.reset}"
+    )
     lines.append("")
     return "\n".join(lines)
 
@@ -420,16 +466,42 @@ def show_waiting_message(
     print(_format_waiting_message(colors, session_id, message))
 
 
+def _ensure_utf8_stdout() -> None:
+    """Reconfigure stdout/stderr to UTF-8 on Windows where cp1252 is the default."""
+    if sys.stdout.encoding and sys.stdout.encoding.lower().replace("-", "") != "utf8":
+        sys.stdout.reconfigure(encoding="utf-8", errors="replace")  # type: ignore[union-attr]
+    if sys.stderr.encoding and sys.stderr.encoding.lower().replace("-", "") != "utf8":
+        sys.stderr.reconfigure(encoding="utf-8", errors="replace")  # type: ignore[union-attr]
+
+
 def main() -> None:
     """Main entry point for context-stats CLI."""
+    _ensure_utf8_stdout()
+
+    # Handle 'explain' subcommand before argparse (it expects stdin JSON, not flags)
+    if len(sys.argv) > 1 and sys.argv[1] == "explain":
+        import json
+
+        from claude_statusline.cli.explain import run_explain
+
+        no_color = "--no-color" in sys.argv
+        try:
+            data = json.load(sys.stdin)
+        except json.JSONDecodeError as e:
+            sys.stderr.write(f"Error: invalid JSON on stdin: {e}\n")
+            sys.stderr.write("Usage: echo '{...}' | context-stats explain\n")
+            sys.exit(1)
+        run_explain(data, no_color=no_color)
+        return
+
     args = parse_args()
 
     # Load config for token_detail setting
     config = Config.load()
 
-    # Setup colors
+    # Setup colors with any user overrides from config
     color_enabled = not args.no_color and sys.stdout.isatty()
-    colors = ColorManager(enabled=color_enabled)
+    colors = ColorManager(enabled=color_enabled, overrides=config.color_overrides)
 
     # Setup state file
     state_file = StateFile(args.session_id)