cc-context-stats 1.6.1 → 1.7.0

package/src/claude_statusline/cli/explain.py

@@ -0,0 +1,228 @@
+"""Diagnostic command that dumps the raw JSON context from Claude Code.
+
+Usage:
+    echo '{"model":...}' | context-stats explain
+    echo '{"model":...}' | context-stats explain --no-color
+
+Reads the same JSON that Claude Code pipes to the statusline script,
+pretty-prints every field with labels, and shows how cc-context-stats
+interprets them. Useful for debugging blank or missing modules.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+
+from claude_statusline.core.colors import ColorManager
+from claude_statusline.core.config import Config
+from claude_statusline.formatters.tokens import format_tokens
+
+
+def _pct_color(colors: ColorManager, pct: float) -> str:
+    """Return ANSI color based on free-space percentage."""
+    if pct > 50:
+        return colors.green
+    if pct > 25:
+        return colors.yellow
+    return colors.red
+
+
+def _fv(colors: ColorManager, value: object) -> str:
+    """Format a value for display, handling None gracefully."""
+    if value is None:
+        return f"{colors.dim}(absent){colors.reset}"
+    if isinstance(value, float):
+        return f"{value:.4f}"
+    return str(value)
+
+
+def _render_model(data: dict, colors: ColorManager) -> None:
+    model = data.get("model", {})
+    print(f"{colors.bold}Model{colors.reset}")
+    print(f"  display_name:  {_fv(colors, model.get('display_name'))}")
+    print(f"  id:            {_fv(colors, model.get('id'))}")
+    print(f"  api_name:      {_fv(colors, model.get('api_name'))}")
+    print()
+
+
+def _render_workspace(data: dict, colors: ColorManager) -> None:
+    workspace = data.get("workspace", {})
+    print(f"{colors.bold}Workspace{colors.reset}")
+    print(f"  current_dir:   {_fv(colors, workspace.get('current_dir'))}")
+    print(f"  project_dir:   {_fv(colors, workspace.get('project_dir'))}")
+    print()
+
+
+def _render_context_window(data: dict, colors: ColorManager, config: Config) -> None:
+    cw = data.get("context_window", {})
+    print(f"{colors.bold}Context Window{colors.reset}")
+    total_size = cw.get("context_window_size", 0)
+    print(
+        f"  window_size:   "
+        f"{format_tokens(total_size, config.token_detail) if total_size else _fv(colors, None)}"
+    )
+
+    total_in = cw.get("total_input_tokens")
+    total_out = cw.get("total_output_tokens")
+    print(
+        f"  total_input:   "
+        f"{format_tokens(total_in, config.token_detail) if total_in else _fv(colors, total_in)}"
+    )
+    print(
+        f"  total_output:  "
+        f"{format_tokens(total_out, config.token_detail) if total_out else _fv(colors, total_out)}"
+    )
+
+    used_pct = cw.get("used_percentage")
+    remaining_pct = cw.get("remaining_percentage")
+    print(f"  used_pct:      {_fv(colors, used_pct)}")
+    print(f"  remaining_pct: {_fv(colors, remaining_pct)}")
+
+    cu = cw.get("current_usage")
+    if cu:
+        _render_current_usage(cu, total_size, colors, config)
+    else:
+        print(f"  current_usage: {colors.dim}(absent — no API call yet this session){colors.reset}")
+    print()
+
+
+def _render_current_usage(cu: dict, total_size: int, colors: ColorManager, config: Config) -> None:
+    input_tok = cu.get("input_tokens", 0)
+    output_tok = cu.get("output_tokens", 0)
+    cache_create = cu.get("cache_creation_input_tokens", 0)
+    cache_read = cu.get("cache_read_input_tokens", 0)
+    used_tokens = input_tok + cache_create + cache_read
+
+    print(f"\n  {colors.bold}Current Usage{colors.reset}")
+    print(f"    input_tokens:            {format_tokens(input_tok, config.token_detail)}")
+    print(f"    output_tokens:           {format_tokens(output_tok, config.token_detail)}")
+    print(f"    cache_creation_tokens:   {format_tokens(cache_create, config.token_detail)}")
+    print(f"    cache_read_tokens:       {format_tokens(cache_read, config.token_detail)}")
+
+    print(f"\n  {colors.bold}Derived Values{colors.reset}")
+    print(
+        f"    context_used (in+cache): "
+        f"{colors.cyan}{format_tokens(used_tokens, config.token_detail)}{colors.reset}"
+    )
+
+    if total_size > 0:
+        free = total_size - used_tokens
+        free_pct = (free * 100.0) / total_size
+        color = _pct_color(colors, free_pct)
+        print(
+            f"    free_tokens:             "
+            f"{color}{format_tokens(max(0, free), config.token_detail)} ({free_pct:.1f}%){colors.reset}"
+        )
+
+        if config.autocompact:
+            ac_buffer = int(total_size * 0.225)
+            effective_free = max(0, free - ac_buffer)
+            eff_pct = (effective_free * 100.0) / total_size
+            eff_color = _pct_color(colors, eff_pct)
+            print(
+                f"    autocompact_buffer:      "
+                f"{colors.dim}{format_tokens(ac_buffer, config.token_detail)}{colors.reset}"
+            )
+            print(
+                f"    effective_free (w/ AC):   "
+                f"{eff_color}{format_tokens(effective_free, config.token_detail)}"
+                f" ({eff_pct:.1f}%){colors.reset}"
+            )
+        else:
+            print(f"    autocompact:             {colors.dim}disabled{colors.reset}")
+
+
+def _render_cost(data: dict, colors: ColorManager) -> None:
+    cost = data.get("cost", {})
+    if not cost:
+        return
+    print(f"{colors.bold}Cost{colors.reset}")
+    cost_usd = cost.get("total_cost_usd")
+    print(
+        f"  total_cost_usd:    {f'${cost_usd:.4f}' if cost_usd is not None else _fv(colors, None)}"
+    )
+    print(f"  total_duration_ms: {_fv(colors, cost.get('total_duration_ms'))}")
+    print(f"  lines_added:       {_fv(colors, cost.get('total_lines_added'))}")
+    print(f"  lines_removed:     {_fv(colors, cost.get('total_lines_removed'))}")
+    print()
+
+
+def _render_session(data: dict, colors: ColorManager) -> None:
+    print(f"{colors.bold}Session{colors.reset}")
+    print(f"  session_id:        {_fv(colors, data.get('session_id'))}")
+    print(f"  version:           {_fv(colors, data.get('version'))}")
+    print(f"  transcript_path:   {_fv(colors, data.get('transcript_path'))}")
+    print(f"  exceeds_200k:      {_fv(colors, data.get('exceeds_200k_tokens'))}")
+    print()
+
+
+def _render_extensions(data: dict, colors: ColorManager) -> None:
+    vim = data.get("vim")
+    agent = data.get("agent")
+    output_style = data.get("output_style")
+    if vim is None and agent is None and output_style is None:
+        return
+    print(f"{colors.bold}Extensions{colors.reset}")
+    if vim is not None:
+        vim_mode = vim.get("mode") if isinstance(vim, dict) else vim
+        print(f"  vim_mode:          {_fv(colors, vim_mode)}")
+    if agent is not None:
+        agent_name = agent.get("name") if isinstance(agent, dict) else agent
+        print(f"  agent:             {_fv(colors, agent_name)}")
+    if output_style is not None:
+        style_name = output_style.get("name") if isinstance(output_style, dict) else output_style
+        print(f"  output_style:      {_fv(colors, style_name)}")
+    print()
+
+
+def _render_config(config: Config, colors: ColorManager) -> None:
+    print(
+        f"{colors.bold}Active Config{colors.reset}  "
+        f"{colors.dim}(~/.claude/statusline.conf){colors.reset}"
+    )
+    for k, v in config.to_dict().items():
+        if k == "color_overrides":
+            if v:
+                print(f"  {k}:")
+                for slot, ansi_code in v.items():
+                    print(f"    {slot}: {ansi_code}████{colors.reset}")
+            continue
+        print(f"  {k}: {v}")
+    print()
+
+
+def _render_raw_json(data: dict, colors: ColorManager) -> None:
+    print(f"{colors.bold}Raw JSON{colors.reset}")
+    print(f"{colors.dim}{json.dumps(data, indent=2)}{colors.reset}")
+    print()
+
+
+def run_explain(data: dict, no_color: bool = False) -> None:
+    """Print a diagnostic dump of the Claude Code session JSON.
+
+    Args:
+        data: Parsed JSON dict from stdin.
+        no_color: If True, suppress ANSI color codes.
+    """
+    config = Config.load()
+
+    # Respect --no-color flag and non-TTY output
+    color_enabled = not no_color and sys.stdout.isatty()
+    colors = ColorManager(enabled=color_enabled, overrides=config.color_overrides)
+
+    print(f"\n{colors.bold}cc-context-stats explain{colors.reset}")
+    print(f"{colors.dim}{'─' * 60}{colors.reset}")
+    print(
+        f"{colors.dim}Shows how cc-context-stats interprets Claude Code's JSON context."
+        f"{colors.reset}\n"
+    )
+
+    _render_model(data, colors)
+    _render_workspace(data, colors)
+    _render_context_window(data, colors, config)
+    _render_cost(data, colors)
+    _render_session(data, colors)
+    _render_extensions(data, colors)
+    _render_config(config, colors)
+    _render_raw_json(data, colors)

package/src/claude_statusline/cli/statusline.py

@@ -26,14 +26,7 @@ from __future__ import annotations
 import json
 import sys
 
-from claude_statusline.core.colors import (
-    BLUE,
-    DIM,
-    GREEN,
-    RED,
-    RESET,
-    YELLOW,
-)
+from claude_statusline.core.colors import ColorManager
 from claude_statusline.core.config import Config
 from claude_statusline.core.git import get_git_info
 from claude_statusline.core.state import StateEntry, StateFile
@@ -56,12 +49,15 @@ def main() -> None:
     model = data.get("model", {}).get("display_name", "Claude")
     dir_name = cwd.rsplit("/", 1)[-1] if "/" in cwd else cwd or "~"
 
-    # Git info
-    git_info = get_git_info(project_dir)
-
     # Read settings from config file
     config = Config.load()
 
+    # Build color manager with any user overrides
+    colors = ColorManager(enabled=True, overrides=config.color_overrides)
+
+    # Git info (pass color manager for configurable branch/change colors)
+    git_info = get_git_info(project_dir, color_manager=colors)
+
     # Extract session_id once for reuse
     session_id = data.get("session_id")
 
@@ -99,9 +95,9 @@ def main() -> None:
 
         if config.autocompact:
             buffer_k = autocompact_buffer // 1000
-            ac_info = f" {DIM}[AC:{buffer_k}k]{RESET}"
+            ac_info = f" {colors.dim}[AC:{buffer_k}k]{colors.reset}"
         else:
-            ac_info = f" {DIM}[AC:off]{RESET}"
+            ac_info = f" {colors.dim}[AC:off]{colors.reset}"
 
         # Format tokens based on token_detail setting
         free_display = format_tokens(free_tokens, config.token_detail)
@@ -109,13 +105,13 @@ def main() -> None:
         # Color based on free percentage
         free_pct_int = int(free_pct)
         if free_pct_int > 50:
-            ctx_color = GREEN
+            ctx_color = colors.green
         elif free_pct_int > 25:
-            ctx_color = YELLOW
+            ctx_color = colors.yellow
         else:
-            ctx_color = RED
+            ctx_color = colors.red
 
-        context_info = f" | {ctx_color}{free_display} free ({free_pct:.1f}%){RESET}"
+        context_info = f" | {ctx_color}{free_display} free ({free_pct:.1f}%){colors.reset}"
 
         # Calculate and display token delta if enabled
         if config.show_delta:
@@ -131,7 +127,7 @@ def main() -> None:
             # Only show positive delta (and skip first run when no previous state)
             if has_prev and delta > 0:
                 delta_display = format_tokens(delta, config.token_detail)
-                delta_info = f" {DIM}[+{delta_display}]{RESET}"
+                delta_info = f" {colors.dim}[+{delta_display}]{colors.reset}"
 
             # Build current entry
             cur_input_tokens = current_usage.get("input_tokens", 0)
@@ -160,10 +156,10 @@ def main() -> None:
 
     # Display session_id if enabled
     if config.show_session and session_id:
-        session_info = f" {DIM}{session_id}{RESET}"
+        session_info = f" {colors.dim}{session_id}{colors.reset}"
 
     # Output: [Model] directory | branch [changes] | XXk free (XX%) [+delta] [AC] [session_id]
-    base = f"{DIM}[{model}]{RESET} {BLUE}{dir_name}{RESET}"
+    base = f"{colors.dim}[{model}]{colors.reset} {colors.blue}{dir_name}{colors.reset}"
     max_width = get_terminal_width()
     parts = [base, git_info, context_info, delta_info, ac_info, session_info]
     print(fit_to_width(parts, max_width))

package/src/claude_statusline/core/colors.py

@@ -1,6 +1,10 @@
 """ANSI color constants and utilities."""
 
-# ANSI color codes
+from __future__ import annotations
+
+import re
+
+# ANSI color codes (defaults)
 BLUE = "\033[0;34m"
 MAGENTA = "\033[0;35m"
 CYAN = "\033[0;36m"
@@ -11,36 +15,101 @@ BOLD = "\033[1m"
 DIM = "\033[2m"
 RESET = "\033[0m"
 
+# Mapping from color names to ANSI codes
+COLOR_NAMES: dict[str, str] = {
+    "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",
+}
+
+_HEX_RE = re.compile(r"^#([0-9a-fA-F]{6})$")
+
+
+def parse_color(value: str) -> str | None:
+    """Parse a color value into an ANSI escape code.
+
+    Accepts:
+      - Named colors: "red", "green", "bright_cyan", etc.
+      - Hex colors: "#ff5733" (converted to 24-bit ANSI)
+
+    Returns:
+        ANSI escape code string, or None if the value is not recognized.
+    """
+    value = value.strip().lower()
+    if not value:
+        return None
+
+    # Named color
+    if value in COLOR_NAMES:
+        return COLOR_NAMES[value]
+
+    # Hex color (#rrggbb)
+    m = _HEX_RE.match(value)
+    if m:
+        hex_str = m.group(1)
+        r = int(hex_str[0:2], 16)
+        g = int(hex_str[2:4], 16)
+        b = int(hex_str[4:6], 16)
+        return f"\033[38;2;{r};{g};{b}m"
+
+    return None
+
 
 class ColorManager:
-    """Manage color output based on terminal capabilities."""
+    """Manage color output based on terminal capabilities.
+
+    Supports custom color overrides via a dict of {slot_name: ansi_code}.
+    """
 
-    def __init__(self, enabled: bool = True) -> None:
+    def __init__(
+        self,
+        enabled: bool = True,
+        overrides: dict[str, str] | None = None,
+    ) -> None:
         self.enabled = enabled
+        self._overrides = overrides or {}
+
+    def _get(self, slot: str, default: str) -> str:
+        if not self.enabled:
+            return ""
+        return self._overrides.get(slot, default)
 
     @property
     def blue(self) -> str:
-        return BLUE if self.enabled else ""
+        return self._get("blue", BLUE)
 
     @property
     def magenta(self) -> str:
-        return MAGENTA if self.enabled else ""
+        return self._get("magenta", MAGENTA)
 
     @property
     def cyan(self) -> str:
-        return CYAN if self.enabled else ""
+        return self._get("cyan", CYAN)
 
     @property
     def green(self) -> str:
-        return GREEN if self.enabled else ""
+        return self._get("green", GREEN)
 
     @property
     def yellow(self) -> str:
-        return YELLOW if self.enabled else ""
+        return self._get("yellow", YELLOW)
 
     @property
     def red(self) -> str:
-        return RED if self.enabled else ""
+        return self._get("red", RED)
 
     @property
     def bold(self) -> str:

package/src/claude_statusline/core/config.py

@@ -7,6 +7,18 @@ from dataclasses import dataclass, field
 from pathlib import Path
 from typing import Any
 
+from claude_statusline.core.colors import parse_color
+
+# Color config keys and which ColorManager slot they map to
+_COLOR_KEYS: dict[str, str] = {
+    "color_green": "green",
+    "color_yellow": "yellow",
+    "color_red": "red",
+    "color_blue": "blue",
+    "color_magenta": "magenta",
+    "color_cyan": "cyan",
+}
+
 
 @dataclass
 class Config:
@@ -19,6 +31,9 @@ class Config:
     show_io_tokens: bool = True
     reduced_motion: bool = False
 
+    # Custom color overrides (slot_name -> ANSI code)
+    color_overrides: dict[str, str] = field(default_factory=dict)
+
     _config_path: Path = field(default_factory=lambda: Path.home() / ".claude" / "statusline.conf")
 
     @classmethod
@@ -62,10 +77,23 @@ show_session=true
 
 # Disable rotating text animations
 reduced_motion=false
+
+# Custom colors - use named colors or hex (#rrggbb)
+# Available color slots: color_green, color_yellow, color_red,
+#   color_blue, color_magenta, color_cyan
+# Named colors: black, red, green, yellow, blue, magenta, cyan, white,
+#   bright_black, bright_red, bright_green, bright_yellow,
+#   bright_blue, bright_magenta, bright_cyan, bright_white
+# Examples:
+#   color_green=#7dcfff
+#   color_yellow=bright_yellow
+#   color_red=#f7768e
 """
             )
         except OSError as e:
-            sys.stderr.write(f"[statusline] warning: failed to create config {self._config_path}: {e}\n")
+            sys.stderr.write(
+                f"[statusline] warning: failed to create config {self._config_path}: {e}\n"
+            )
 
     def _read_config(self) -> None:
         """Read settings from config file."""
@@ -77,22 +105,35 @@ reduced_motion=false
                     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":
-                    self.autocompact = value != "false"
+                    self.autocompact = value_lower != "false"
                 elif key == "token_detail":
-                    self.token_detail = value != "false"
+                    self.token_detail = value_lower != "false"
                 elif key == "show_delta":
-                    self.show_delta = value != "false"
+                    self.show_delta = value_lower != "false"
                 elif key == "show_session":
-                    self.show_session = value != "false"
+                    self.show_session = value_lower != "false"
                 elif key == "show_io_tokens":
-                    self.show_io_tokens = value != "false"
+                    self.show_io_tokens = value_lower != "false"
                 elif key == "reduced_motion":
-                    self.reduced_motion = value != "false"
+                    self.reduced_motion = value_lower != "false"
+                elif key in _COLOR_KEYS:
+                    slot = _COLOR_KEYS[key]
+                    ansi = parse_color(raw_value)
+                    if ansi:
+                        self.color_overrides[slot] = ansi
+                    else:
+                        sys.stderr.write(
+                            f"[statusline] warning: unrecognized color value "
+                            f"'{raw_value}' for {key}\n"
+                        )
         except (OSError, UnicodeDecodeError) as e:
-            sys.stderr.write(f"[statusline] warning: failed to read config {self._config_path}: {e}\n")
+            sys.stderr.write(
+                f"[statusline] warning: failed to read config {self._config_path}: {e}\n"
+            )
 
     def to_dict(self) -> dict[str, Any]:
         """Convert config to dictionary."""
@@ -103,4 +144,5 @@ reduced_motion=false
             "show_session": self.show_session,
             "show_io_tokens": self.show_io_tokens,
             "reduced_motion": self.reduced_motion,
+            "color_overrides": dict(self.color_overrides),
         }

package/src/claude_statusline/core/git.py

@@ -5,15 +5,22 @@ from __future__ import annotations
 import subprocess
 from pathlib import Path
 
-from claude_statusline.core.colors import CYAN, MAGENTA, RESET
+from claude_statusline.core.colors import CYAN, MAGENTA, RESET, ColorManager
 
 
-def get_git_info(project_dir: str | Path, colors_enabled: bool = True) -> str:
+def get_git_info(
+    project_dir: str | Path,
+    colors_enabled: bool = True,
+    color_manager: ColorManager | None = None,
+) -> str:
     """Get git branch and change count for a directory.
 
     Args:
         project_dir: Path to the project directory
-        colors_enabled: Whether to include ANSI color codes
+        colors_enabled: Whether to include ANSI color codes. Deprecated —
+            prefer passing a ColorManager via color_manager instead.
+        color_manager: Optional ColorManager for custom colors. If provided,
+            colors_enabled is ignored (the manager handles that).
 
     Returns:
         Formatted string with branch and change count, or empty string if not a git repo
@@ -53,8 +60,12 @@ def get_git_info(project_dir: str | Path, colors_enabled: bool = True) -> str:
         else:
             changes = len([line for line in result.stdout.split("\n") if line.strip()])
 
-        # Format output
-        if colors_enabled:
+        # Format output — use ColorManager if provided, else fallback to constants
+        if color_manager is not None:
+            magenta = color_manager.magenta
+            cyan = color_manager.cyan
+            reset = color_manager.reset
+        elif colors_enabled:
             magenta, cyan, reset = MAGENTA, CYAN, RESET
         else:
             magenta = cyan = reset = ""