cc-context-stats 1.3.0

package/src/claude_statusline/cli/context_stats.py

@@ -0,0 +1,379 @@
+#!/usr/bin/env python3
+"""Context Stats Visualizer for Claude Code.
+
+Displays ASCII graphs of token consumption over time.
+
+Usage:
+    context-stats [session_id] [options]
+
+Options:
+    --type <cumulative|delta|io|both|all>  Graph type to display (default: both)
+    --watch, -w [interval]                  Real-time monitoring mode (default: 2s)
+    --no-color                              Disable color output
+    --help                                  Show this help
+"""
+
+from __future__ import annotations
+
+import argparse
+import signal
+import sys
+import time
+from pathlib import Path
+
+from claude_statusline import __version__
+from claude_statusline.core.colors import ColorManager
+from claude_statusline.core.config import Config
+from claude_statusline.core.state import StateFile
+from claude_statusline.graphs.renderer import GraphDimensions, GraphRenderer
+from claude_statusline.graphs.statistics import calculate_deltas
+
+# Cursor control sequences
+CURSOR_HOME = "\033[H"
+CLEAR_SCREEN = "\033[2J"
+HIDE_CURSOR = "\033[?25l"
+SHOW_CURSOR = "\033[?25h"
+CLEAR_TO_END = "\033[J"
+
+
+def show_help() -> None:
+    """Show help message."""
+    print(
+        """Context Stats Visualizer for Claude Code
+
+USAGE:
+    context-stats [session_id] [options]
+
+ARGUMENTS:
+    session_id    Optional session ID. If not provided, uses the latest session.
+
+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
+                   - both: Show cumulative and delta graphs
+                   - all: Show all graphs including I/O
+    -w [interval]  Set refresh interval in seconds (default: 2)
+    --no-watch     Show graphs once and exit (disable live monitoring)
+    --no-color     Disable color output
+    --help         Show this help message
+
+NOTE:
+    By default, context-stats runs in live monitoring mode, refreshing every 2 seconds.
+    Press Ctrl+C to exit. Use --no-watch to display graphs once and exit.
+
+EXAMPLES:
+    # Live monitoring (default, refreshes every 2s)
+    context-stats
+
+    # Live monitoring with custom interval
+    context-stats -w 5
+
+    # Show graphs once and exit
+    context-stats --no-watch
+
+    # Show graphs for specific session
+    context-stats abc123def
+
+    # Show only cumulative graph
+    context-stats --type cumulative
+
+    # Combine options
+    context-stats abc123 --type cumulative -w 3
+
+    # Output to file (no colors, single run)
+    context-stats --no-watch --no-color > output.txt
+
+DATA SOURCE:
+    Reads token history from ~/.claude/statusline/statusline.<session_id>.state
+"""
+    )
+
+
+def parse_args() -> argparse.Namespace:
+    """Parse command-line arguments."""
+    parser = argparse.ArgumentParser(
+        description="Context Stats Visualizer for Claude Code",
+        add_help=False,
+    )
+    parser.add_argument("session_id", nargs="?", default=None, help="Session ID")
+    parser.add_argument(
+        "--type",
+        choices=["cumulative", "delta", "io", "both", "all"],
+        default="delta",
+        help="Graph type to display (default: delta)",
+    )
+    parser.add_argument(
+        "--watch",
+        "-w",
+        nargs="?",
+        const=2,
+        type=int,
+        default=2,
+        help="Watch mode interval in seconds (default: 2, use --no-watch to disable)",
+    )
+    parser.add_argument(
+        "--no-watch",
+        action="store_true",
+        help="Disable watch mode (show graphs once and exit)",
+    )
+    parser.add_argument(
+        "--no-color",
+        action="store_true",
+        help="Disable color output",
+    )
+    parser.add_argument(
+        "--help",
+        "-h",
+        action="store_true",
+        help="Show help message",
+    )
+
+    args = parser.parse_args()
+
+    if args.help:
+        show_help()
+        sys.exit(0)
+
+    return args
+
+
+def render_once(
+    state_file: StateFile,
+    graph_type: str,
+    renderer: GraphRenderer,
+    colors: ColorManager,
+    watch_mode: bool = False,
+) -> bool:
+    """Render graphs once.
+
+    Args:
+        state_file: StateFile instance
+        graph_type: Type of graphs to render
+        renderer: GraphRenderer instance
+        colors: ColorManager instance
+        watch_mode: Whether running in watch mode
+
+    Returns:
+        True if rendering was successful, False if not enough data
+    """
+    entries = state_file.read_history()
+
+    if len(entries) < 2:
+        print(f"\n{colors.yellow}Need at least 2 data points to generate graphs.{colors.reset}")
+        print(
+            f"{colors.dim}Found: {len(entries)} entry. Use Claude Code to accumulate more data.{colors.reset}"
+        )
+        return False
+
+    # Extract data for graphs
+    timestamps = [e.timestamp for e in entries]
+    # Current context window usage (what's actually in the context)
+    # This is: cache_read + cache_creation + current_input_tokens
+    context_used = [e.current_used_tokens for e in entries]
+    # Per-request I/O tokens from current_usage
+    current_input = [e.current_input_tokens for e in entries]
+    current_output = [e.current_output_tokens for e in entries]
+    deltas = calculate_deltas(context_used)
+    delta_times = timestamps[1:]  # Deltas start from second entry
+
+    # Get session name and project from entries
+    file_path = state_file.find_latest_state_file()
+    session_name = file_path.stem.replace("statusline.", "") if file_path else "unknown"
+
+    # Get project name from the last entry (most recent)
+    last_entry = entries[-1]
+    project_name = ""
+    if last_entry.workspace_project_dir:
+        # Extract just the project folder name from the path
+        project_name = Path(last_entry.workspace_project_dir).name
+
+    # Header
+    if not watch_mode:
+        print()
+    if project_name:
+        print(
+            f"{colors.bold}{colors.magenta}Context Stats{colors.reset} "
+            f"{colors.dim}({colors.cyan}{project_name}{colors.dim} • {session_name}){colors.reset}"
+        )
+    else:
+        print(
+            f"{colors.bold}{colors.magenta}Context Stats{colors.reset} "
+            f"{colors.dim}(Session: {session_name}){colors.reset}"
+        )
+
+    # Render requested graphs
+    if graph_type in ("cumulative", "both", "all"):
+        renderer.render_timeseries(
+            context_used, timestamps, "Context Usage Over Time", colors.green
+        )
+
+    if graph_type in ("delta", "both", "all"):
+        renderer.render_timeseries(
+            deltas, delta_times, "Context Growth Per Interaction", colors.cyan
+        )
+
+    if graph_type in ("io", "all"):
+        renderer.render_timeseries(
+            current_input, timestamps, "Input Tokens (per request)", colors.blue
+        )
+        renderer.render_timeseries(
+            current_output, timestamps, "Output Tokens (per request)", colors.magenta
+        )
+
+    # Summary and footer
+    renderer.render_summary(entries, deltas)
+    renderer.render_footer(__version__)
+
+    return True
+
+
+def run_watch_mode(
+    state_file: StateFile,
+    graph_type: str,
+    interval: int,
+    renderer: GraphRenderer,
+    colors: ColorManager,
+) -> None:
+    """Run in watch mode with continuous refresh.
+
+    Args:
+        state_file: StateFile instance
+        graph_type: Type of graphs to render
+        interval: Refresh interval in seconds
+        renderer: GraphRenderer instance
+        colors: ColorManager instance
+    """
+
+    # Signal handler for clean exit
+    def handle_signal(_signum: int, _frame: object) -> None:
+        sys.stdout.write(SHOW_CURSOR)
+        sys.stdout.flush()
+        print(f"\n{colors.dim}Watch mode stopped.{colors.reset}")
+        sys.exit(0)
+
+    signal.signal(signal.SIGINT, handle_signal)
+    signal.signal(signal.SIGTERM, handle_signal)
+
+    # Hide cursor and initial clear in one write
+    sys.stdout.write(f"{HIDE_CURSOR}{CLEAR_SCREEN}{CURSOR_HOME}")
+    sys.stdout.flush()
+
+    try:
+        while True:
+            # Move cursor to home
+            sys.stdout.write(CURSOR_HOME)
+            sys.stdout.flush()
+
+            # Update dimensions in case of terminal resize
+            renderer.dimensions = GraphDimensions.detect()
+
+            # Watch mode indicator
+            current_time = time.strftime("%H:%M:%S")
+            print(
+                f"{colors.dim}[LIVE {current_time}] Refresh: {interval}s | Ctrl+C to exit{colors.reset}"
+            )
+
+            # Check if state file exists now (may have been created since start)
+            file_path = state_file.find_latest_state_file()
+            if not file_path or not file_path.exists():
+                # Show waiting message for new session
+                show_waiting_message(
+                    colors,
+                    state_file.session_id,
+                    "Waiting for session data...",
+                )
+            else:
+                # Render graphs
+                render_once(state_file, graph_type, renderer, colors, watch_mode=True)
+
+            # Clear any remaining content
+            sys.stdout.write(CLEAR_TO_END)
+            sys.stdout.flush()
+
+            time.sleep(interval)
+    finally:
+        sys.stdout.write(SHOW_CURSOR)
+        sys.stdout.flush()
+
+
+def show_waiting_message(
+    colors: ColorManager,
+    session_id: str | None,
+    message: str = "Waiting for session data...",
+) -> None:
+    """Show a friendly waiting message for new sessions.
+
+    Args:
+        colors: ColorManager instance
+        session_id: Session ID if specified
+        message: Message to display
+    """
+    print()
+    if session_id:
+        print(
+            f"{colors.bold}{colors.magenta}Context Stats{colors.reset} "
+            f"{colors.dim}(Session: {session_id}){colors.reset}"
+        )
+    else:
+        print(f"{colors.bold}{colors.magenta}Context Stats{colors.reset}")
+
+    print()
+    print(f"  {colors.cyan}⏳ {message}{colors.reset}")
+    print()
+    print(
+        f"  {colors.dim}The session has just started and no data has been recorded yet.{colors.reset}"
+    )
+    print(f"  {colors.dim}Data will appear after the first Claude interaction.{colors.reset}")
+    print()
+
+
+def main() -> None:
+    """Main entry point for context-stats CLI."""
+    args = parse_args()
+
+    # Load config for token_detail setting
+    config = Config.load()
+
+    # Setup colors
+    color_enabled = not args.no_color and sys.stdout.isatty()
+    colors = ColorManager(enabled=color_enabled)
+
+    # Setup state file
+    state_file = StateFile(args.session_id)
+
+    # Find state file
+    file_path = state_file.find_latest_state_file()
+
+    # Handle case where no state file exists yet
+    if not file_path or not file_path.exists():
+        if args.no_watch:
+            # Single run mode - show friendly message and exit
+            if args.session_id:
+                show_waiting_message(colors, args.session_id)
+            else:
+                print(f"{colors.yellow}No session data found.{colors.reset}")
+                print(f"{colors.dim}Run Claude Code to generate token usage data.{colors.reset}")
+            sys.exit(0)
+        else:
+            # Watch mode - continue and wait for data
+            pass
+
+    # Setup renderer
+    renderer = GraphRenderer(
+        colors=colors,
+        token_detail=config.token_detail,
+    )
+
+    # Run
+    if args.no_watch:
+        success = render_once(state_file, args.type, renderer, colors)
+        if not success:
+            sys.exit(1)
+    else:
+        run_watch_mode(state_file, args.type, args.watch, renderer, colors)
+
+
+if __name__ == "__main__":
+    main()

package/src/claude_statusline/cli/statusline.py

@@ -0,0 +1,172 @@
+#!/usr/bin/env python3
+"""CLI entry point for claude-statusline command.
+
+Usage: Copy to ~/.claude/statusline.py and make executable, or install via pip.
+
+Configuration:
+Create/edit ~/.claude/statusline.conf and set:
+
+  autocompact=true   (when autocompact is enabled in Claude Code - default)
+  autocompact=false  (when you disable autocompact via /config in Claude Code)
+
+  token_detail=true  (show exact token count like 64,000 - default)
+  token_detail=false (show abbreviated tokens like 64.0k)
+
+  show_delta=true    (show token delta since last refresh like [+2,500] - default)
+  show_delta=false   (disable delta display - saves file I/O on every refresh)
+
+  show_session=true  (show session_id in status line - default)
+  show_session=false (hide session_id from status line)
+
+When AC is enabled, 22.5% of context window is reserved for autocompact buffer.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+
+from claude_statusline.core.colors import (
+    BLUE,
+    DIM,
+    GREEN,
+    RED,
+    RESET,
+    YELLOW,
+)
+from claude_statusline.core.config import Config
+from claude_statusline.core.git import get_git_info
+from claude_statusline.core.state import StateEntry, StateFile
+from claude_statusline.formatters.time import get_current_timestamp
+from claude_statusline.formatters.tokens import calculate_context_usage, format_tokens
+
+
+def main() -> None:
+    """Main entry point for claude-statusline CLI."""
+    try:
+        data = json.load(sys.stdin)
+    except json.JSONDecodeError:
+        print("[Claude] ~")
+        return
+
+    # Extract data
+    cwd = data.get("workspace", {}).get("current_dir", "~")
+    project_dir = data.get("workspace", {}).get("project_dir", cwd)
+    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()
+
+    # Extract session_id once for reuse
+    session_id = data.get("session_id")
+
+    # Context window calculation
+    context_info = ""
+    ac_info = ""
+    delta_info = ""
+    session_info = ""
+
+    total_size = data.get("context_window", {}).get("context_window_size", 0)
+    current_usage = data.get("context_window", {}).get("current_usage")
+    total_input_tokens = data.get("context_window", {}).get("total_input_tokens", 0)
+    total_output_tokens = data.get("context_window", {}).get("total_output_tokens", 0)
+    cost_usd = data.get("cost", {}).get("total_cost_usd", 0)
+    lines_added = data.get("cost", {}).get("total_lines_added", 0)
+    lines_removed = data.get("cost", {}).get("total_lines_removed", 0)
+    model_id = data.get("model", {}).get("id", "")
+    workspace_project_dir = data.get("workspace", {}).get("project_dir", "")
+
+    if total_size > 0 and current_usage:
+        # Get tokens from current_usage (includes cache)
+        input_tokens = current_usage.get("input_tokens", 0)
+        cache_creation = current_usage.get("cache_creation_input_tokens", 0)
+        cache_read = current_usage.get("cache_read_input_tokens", 0)
+
+        # Total used from current request
+        used_tokens = input_tokens + cache_creation + cache_read
+
+        # Calculate context usage
+        free_tokens, free_pct, autocompact_buffer = calculate_context_usage(
+            used_tokens,
+            total_size,
+            config.autocompact,
+        )
+
+        if config.autocompact:
+            buffer_k = autocompact_buffer // 1000
+            ac_info = f" {DIM}[AC:{buffer_k}k]{RESET}"
+        else:
+            ac_info = f" {DIM}[AC:off]{RESET}"
+
+        # Format tokens based on token_detail setting
+        free_display = format_tokens(free_tokens, config.token_detail)
+
+        # Color based on free percentage
+        free_pct_int = int(free_pct)
+        if free_pct_int > 50:
+            ctx_color = GREEN
+        elif free_pct_int > 25:
+            ctx_color = YELLOW
+        else:
+            ctx_color = RED
+
+        context_info = f" | {ctx_color}{free_display} free ({free_pct:.1f}%){RESET}"
+
+        # Calculate and display token delta if enabled
+        if config.show_delta:
+            state_file = StateFile(session_id)
+            prev_entry = state_file.read_last_entry()
+
+            prev_tokens = prev_entry.current_used_tokens if prev_entry else 0
+            has_prev = prev_entry is not None
+
+            # Calculate delta
+            delta = used_tokens - prev_tokens
+
+            # 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}"
+
+            # Build current entry
+            cur_input_tokens = current_usage.get("input_tokens", 0)
+            cur_output_tokens = current_usage.get("output_tokens", 0)
+
+            entry = StateEntry(
+                timestamp=get_current_timestamp(),
+                total_input_tokens=total_input_tokens,
+                total_output_tokens=total_output_tokens,
+                current_input_tokens=cur_input_tokens,
+                current_output_tokens=cur_output_tokens,
+                cache_creation=cache_creation,
+                cache_read=cache_read,
+                cost_usd=cost_usd,
+                lines_added=lines_added,
+                lines_removed=lines_removed,
+                session_id=session_id or "",
+                model_id=model_id,
+                workspace_project_dir=workspace_project_dir,
+                context_window_size=total_size,
+            )
+
+            # Only append if context usage changed (avoid duplicates from multiple refreshes)
+            if not has_prev or used_tokens != prev_tokens:
+                state_file.append_entry(entry)
+
+    # Display session_id if enabled
+    if config.show_session and session_id:
+        session_info = f" {DIM}{session_id}{RESET}"
+
+    # Output: [Model] directory | branch [changes] | XXk free (XX%) [+delta] [AC] [session_id]
+    print(
+        f"{DIM}[{model}]{RESET} {BLUE}{dir_name}{RESET}"
+        f"{git_info}{context_info}{delta_info}{ac_info}{session_info}"
+    )
+
+
+if __name__ == "__main__":
+    main()

package/src/claude_statusline/core/__init__.py

@@ -0,0 +1 @@
+"""Core functionality for claude-statusline."""

package/src/claude_statusline/core/colors.py

@@ -0,0 +1,55 @@
+"""ANSI color constants and utilities."""
+
+# ANSI color codes
+BLUE = "\033[0;34m"
+MAGENTA = "\033[0;35m"
+CYAN = "\033[0;36m"
+GREEN = "\033[0;32m"
+YELLOW = "\033[0;33m"
+RED = "\033[0;31m"
+BOLD = "\033[1m"
+DIM = "\033[2m"
+RESET = "\033[0m"
+
+
+class ColorManager:
+    """Manage color output based on terminal capabilities."""
+
+    def __init__(self, enabled: bool = True) -> None:
+        self.enabled = enabled
+
+    @property
+    def blue(self) -> str:
+        return BLUE if self.enabled else ""
+
+    @property
+    def magenta(self) -> str:
+        return MAGENTA if self.enabled else ""
+
+    @property
+    def cyan(self) -> str:
+        return CYAN if self.enabled else ""
+
+    @property
+    def green(self) -> str:
+        return GREEN if self.enabled else ""
+
+    @property
+    def yellow(self) -> str:
+        return YELLOW if self.enabled else ""
+
+    @property
+    def red(self) -> str:
+        return RED if self.enabled else ""
+
+    @property
+    def bold(self) -> str:
+        return BOLD if self.enabled else ""
+
+    @property
+    def dim(self) -> str:
+        return DIM if self.enabled else ""
+
+    @property
+    def reset(self) -> str:
+        return RESET if self.enabled else ""

package/src/claude_statusline/core/config.py

@@ -0,0 +1,98 @@
+"""Configuration management for statusline."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+
+@dataclass
+class Config:
+    """Configuration settings for the statusline."""
+
+    autocompact: bool = True
+    token_detail: bool = True
+    show_delta: bool = True
+    show_session: bool = True
+    show_io_tokens: bool = True
+
+    _config_path: Path = field(default_factory=lambda: Path.home() / ".claude" / "statusline.conf")
+
+    @classmethod
+    def load(cls, config_path: str | Path | None = None) -> Config:
+        """Load configuration from file.
+
+        Args:
+            config_path: Path to config file. Defaults to ~/.claude/statusline.conf
+
+        Returns:
+            Config instance with loaded settings
+        """
+        config = cls()
+        if config_path:
+            config._config_path = Path(config_path).expanduser()
+
+        if not config._config_path.exists():
+            config._create_default()
+            return config
+
+        config._read_config()
+        return config
+
+    def _create_default(self) -> None:
+        """Create default config file if it doesn't exist."""
+        try:
+            self._config_path.parent.mkdir(parents=True, exist_ok=True)
+            self._config_path.write_text(
+                """# Autocompact setting - sync with Claude Code's /config
+autocompact=true
+
+# Token display format
+token_detail=true
+
+# Show token delta since last refresh (adds file I/O on every refresh)
+# Disable if you don't need it to reduce overhead
+show_delta=true
+
+# Show session_id in status line
+show_session=true
+"""
+            )
+        except OSError:
+            pass  # Ignore errors creating config
+
+    def _read_config(self) -> None:
+        """Read settings from config file."""
+        try:
+            content = self._config_path.read_text()
+            for line in content.splitlines():
+                line = line.strip()
+                if line.startswith("#") or "=" not in line:
+                    continue
+                key, value = line.split("=", 1)
+                key = key.strip()
+                value = value.strip().lower()
+
+                if key == "autocompact":
+                    self.autocompact = value != "false"
+                elif key == "token_detail":
+                    self.token_detail = value != "false"
+                elif key == "show_delta":
+                    self.show_delta = value != "false"
+                elif key == "show_session":
+                    self.show_session = value != "false"
+                elif key == "show_io_tokens":
+                    self.show_io_tokens = value != "false"
+        except OSError:
+            pass  # Use defaults on read error
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert config to dictionary."""
+        return {
+            "autocompact": self.autocompact,
+            "token_detail": self.token_detail,
+            "show_delta": self.show_delta,
+            "show_session": self.show_session,
+            "show_io_tokens": self.show_io_tokens,
+        }