cc-context-stats 1.6.1 → 1.7.0

package/scripts/statusline.py

@@ -21,7 +21,10 @@ Create/edit ~/.claude/statusline.conf and set:
 When AC is enabled, 22.5% of context window is reserved for autocompact buffer.
 
 State file format (CSV):
-  timestamp,total_input_tokens,total_output_tokens,current_usage_input_tokens,current_usage_output_tokens,current_usage_cache_creation,current_usage_cache_read,total_cost_usd,total_lines_added,total_lines_removed,session_id,model_id,workspace_project_dir
+  timestamp,total_input_tokens,total_output_tokens,current_usage_input_tokens,
+  current_usage_output_tokens,current_usage_cache_creation,current_usage_cache_read,
+  total_cost_usd,total_lines_added,total_lines_removed,session_id,model_id,
+  workspace_project_dir,context_window_size
 """
 
 import json
@@ -30,8 +33,41 @@ import re
 import shutil
 import subprocess
 import sys
+import tempfile
 
-# ANSI Colors
+ROTATION_THRESHOLD = 10_000
+ROTATION_KEEP = 5_000
+
+
+def maybe_rotate_state_file(state_file):
+    """Rotate a state file if it exceeds ROTATION_THRESHOLD lines.
+
+    Keeps the most recent ROTATION_KEEP lines via atomic temp-file + rename.
+    """
+    try:
+        if not os.path.exists(state_file):
+            return
+        with open(state_file) as f:
+            lines = f.readlines()
+        if len(lines) <= ROTATION_THRESHOLD:
+            return
+        keep = lines[-ROTATION_KEEP:]
+        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)
+            os.replace(tmp_path, state_file)
+        except BaseException:
+            try:
+                os.unlink(tmp_path)
+            except OSError:
+                pass
+            raise
+    except OSError as e:
+        sys.stderr.write(f"[statusline] warning: failed to rotate state file: {e}\n")
+
+
+# ANSI Colors (defaults, overridable via config)
 BLUE = "\033[0;34m"
 MAGENTA = "\033[0;35m"
 CYAN = "\033[0;36m"
@@ -41,6 +77,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")
 
@@ -93,8 +171,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 ""
@@ -106,6 +188,7 @@ def get_git_info(project_dir):
             cwd=project_dir,
             capture_output=True,
             text=True,
+            timeout=5,
         )
         branch = result.stdout.strip()
 
@@ -118,13 +201,14 @@ def get_git_info(project_dir):
             cwd=project_dir,
             capture_output=True,
             text=True,
+            timeout=5,
         )
         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}"
-    except Exception:
+            return f" | {magenta}{branch}{RESET} {cyan}[{changes}]{RESET}"
+        return f" | {magenta}{branch}{RESET}"
+    except (subprocess.TimeoutExpired, OSError):
         return ""
 
 
@@ -136,6 +220,7 @@ def read_config():
         "show_delta": True,
         "show_session": True,
         "show_io_tokens": True,
+        "colors": {},
     }
     config_path = os.path.expanduser("~/.claude/statusline.conf")
 
@@ -157,6 +242,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:
@@ -171,17 +262,22 @@ 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 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
@@ -200,9 +296,6 @@ 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"]
@@ -211,6 +304,18 @@ def main():
     show_session = config["show_session"]
     # 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")
 
@@ -267,11 +372,11 @@ 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}"
 
@@ -302,19 +407,27 @@ def main():
             try:
                 if os.path.exists(state_file):
                     has_prev = True
-                    # Read last line to get previous token count
+                    # Read last line to get previous context usage
                     with open(state_file) as f:
                         lines = f.readlines()
                         if lines:
                             last_line = lines[-1].strip()
                             if "," in last_line:
-                                prev_tokens = int(last_line.split(",")[1])
+                                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_tokens = prev_cur_input + prev_cache_creation + prev_cache_read
                             else:
+                                # Old format - single value
                                 prev_tokens = int(last_line or 0)
-            except Exception as e:
+            except (OSError, ValueError) as e:
                 sys.stderr.write(f"[statusline] warning: failed to read state file: {e}\n")
                 prev_tokens = 0
-            # Calculate delta
+            # 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:
@@ -323,41 +436,46 @@ def main():
                 else:
                     delta_display = f"{delta / 1000:.1f}k"
                 delta_info = f" {DIM}[+{delta_display}]{RESET}"
-            # Append current usage with comprehensive format
-            # Format: timestamp,total_input_tokens,total_output_tokens,current_usage_input_tokens,current_usage_output_tokens,current_usage_cache_creation,current_usage_cache_read,total_cost_usd,total_lines_added,total_lines_removed,session_id,model_id,workspace_project_dir
-            try:
-                cur_input_tokens = current_usage.get("input_tokens", 0)
-                cur_output_tokens = current_usage.get("output_tokens", 0)
-                state_data = ",".join(
-                    str(x)
-                    for x in [
-                        int(time.time()),
-                        total_input_tokens,
-                        total_output_tokens,
-                        cur_input_tokens,
-                        cur_output_tokens,
-                        cache_creation,
-                        cache_read,
-                        cost_usd,
-                        lines_added,
-                        lines_removed,
-                        session_id or "",
-                        model_id,
-                        workspace_project_dir.replace(",", "_"),
-                        total_size,
-                    ]
-                )
-                with open(state_file, "a") as f:
-                    f.write(f"{state_data}\n")
-            except Exception as e:
-                sys.stderr.write(f"[statusline] warning: failed to write state file: {e}\n")
+            # 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)
+                    state_data = ",".join(
+                        str(x)
+                        for x in [
+                            int(time.time()),
+                            total_input_tokens,
+                            total_output_tokens,
+                            cur_input_tokens,
+                            cur_output_tokens,
+                            cache_creation,
+                            cache_read,
+                            cost_usd,
+                            lines_added,
+                            lines_removed,
+                            session_id or "",
+                            model_id,
+                            workspace_project_dir.replace(",", "_"),
+                            total_size,
+                        ]
+                    )
+                    with open(state_file, "a") as f:
+                        f.write(f"{state_data}\n")
+                    maybe_rotate_state_file(state_file)
+                except OSError as e:
+                    sys.stderr.write(f"[statusline] warning: failed to write state file: {e}\n")
 
     # Display session_id if enabled
     if show_session and session_id:
         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]
     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.1"
+__version__ = "1.7.0"
 
 from claude_statusline.core.config import Config
 from claude_statusline.core.state import StateFile

package/src/claude_statusline/cli/context_stats.py

@@ -46,10 +46,14 @@ 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)
@@ -89,6 +93,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
 """
@@ -345,16 +352,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 +414,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 +436,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)