cc-context-stats 1.3.0 → 1.5.1

package/src/claude_statusline/cli/context_stats.py

@@ -27,6 +27,8 @@ 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
+from claude_statusline.ui.icons import get_activity_tier, get_tier_label
+from claude_statusline.ui.waiting import get_waiting_text, is_active
 
 # Cursor control sequences
 CURSOR_HOME = "\033[H"
@@ -145,7 +147,9 @@ def render_once(
     renderer: GraphRenderer,
     colors: ColorManager,
     watch_mode: bool = False,
-) -> bool:
+    config: Config | None = None,
+    cycle_index: int = 0,
+) -> bool | str:
     """Render graphs once.
 
     Args:
@@ -154,19 +158,35 @@ def render_once(
         renderer: GraphRenderer instance
         colors: ColorManager instance
         watch_mode: Whether running in watch mode
+        config: Config instance for motion settings
+        cycle_index: Watch mode refresh counter for rotating text
 
     Returns:
-        True if rendering was successful, False if not enough data
+        True if rendering was successful (non-watch mode),
+        buffered string if watch_mode is True,
+        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(
+        msg = (
+            f"\n{colors.yellow}Need at least 2 data points to generate graphs.{colors.reset}\n"
             f"{colors.dim}Found: {len(entries)} entry. Use Claude Code to accumulate more data.{colors.reset}"
         )
+        if watch_mode:
+            return msg
+        print(msg)
         return False
 
+    # In watch mode, buffer all output
+    lines: list[str] = []
+
+    def emit(line: str = "") -> None:
+        if watch_mode:
+            lines.append(line)
+        else:
+            print(line)
+
     # Extract data for graphs
     timestamps = [e.timestamp for e in entries]
     # Current context window usage (what's actually in the context)
@@ -191,18 +211,34 @@ def render_once(
 
     # Header
     if not watch_mode:
-        print()
+        emit()
     if project_name:
-        print(
+        emit(
             f"{colors.bold}{colors.magenta}Context Stats{colors.reset} "
             f"{colors.dim}({colors.cyan}{project_name}{colors.dim} • {session_name}){colors.reset}"
         )
     else:
-        print(
+        emit(
             f"{colors.bold}{colors.magenta}Context Stats{colors.reset} "
             f"{colors.dim}(Session: {session_name}){colors.reset}"
         )
 
+    # Activity indicator (waiting text + label)
+    reduced_motion = config.reduced_motion if config else False
+    tier = get_activity_tier(entries, last_entry.context_window_size)
+    label = get_tier_label(tier)
+    active = is_active(entries)
+
+    if active:
+        text = get_waiting_text(cycle_index, reduced_motion)
+        emit(f"  {colors.dim}{text} [{label}]{colors.reset}")
+    else:
+        emit(f"  {colors.dim}{label}{colors.reset}")
+
+    # In watch mode, enable renderer buffering
+    if watch_mode:
+        renderer.begin_buffering()
+
     # Render requested graphs
     if graph_type in ("cumulative", "both", "all"):
         renderer.render_timeseries(
@@ -226,6 +262,12 @@ def render_once(
     renderer.render_summary(entries, deltas)
     renderer.render_footer(__version__)
 
+    if watch_mode:
+        # Collect renderer buffer and combine with header lines
+        renderer_output = renderer.get_buffer()
+        lines.append(renderer_output)
+        return "\n".join(lines)
+
     return True
 
 
@@ -235,6 +277,7 @@ def run_watch_mode(
     interval: int,
     renderer: GraphRenderer,
     colors: ColorManager,
+    config: Config | None = None,
 ) -> None:
     """Run in watch mode with continuous refresh.
 
@@ -244,6 +287,7 @@ def run_watch_mode(
         interval: Refresh interval in seconds
         renderer: GraphRenderer instance
         colors: ColorManager instance
+        config: Config instance for motion settings
     """
 
     # Signal handler for clean exit
@@ -260,18 +304,19 @@ def run_watch_mode(
     sys.stdout.write(f"{HIDE_CURSOR}{CLEAR_SCREEN}{CURSOR_HOME}")
     sys.stdout.flush()
 
+    cycle_counter = 0
+
     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()
 
+            # Build all output into a buffer
+            buf_lines: list[str] = []
+
             # Watch mode indicator
             current_time = time.strftime("%H:%M:%S")
-            print(
+            buf_lines.append(
                 f"{colors.dim}[LIVE {current_time}] Refresh: {interval}s | Ctrl+C to exit{colors.reset}"
             )
 
@@ -279,54 +324,81 @@ def run_watch_mode(
             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(
+                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,
-                    "Waiting for session data...",
-                )
+                    text,
+                ))
             else:
-                # Render graphs
-                render_once(state_file, graph_type, renderer, colors, watch_mode=True)
+                # 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,
+                )
+                if isinstance(result, str):
+                    buf_lines.append(result)
 
-            # Clear any remaining content
-            sys.stdout.write(CLEAR_TO_END)
+            # Atomic write: CURSOR_HOME + content + CLEAR_TO_END (clean up stale trailing lines)
+            buffered_content = "\n".join(buf_lines)
+            sys.stdout.write(f"{CURSOR_HOME}{buffered_content}\n{CLEAR_TO_END}")
             sys.stdout.flush()
 
+            cycle_counter += 1
             time.sleep(interval)
     finally:
         sys.stdout.write(SHOW_CURSOR)
         sys.stdout.flush()
 
 
-def show_waiting_message(
+def _format_waiting_message(
     colors: ColorManager,
     session_id: str | None,
     message: str = "Waiting for session data...",
-) -> None:
-    """Show a friendly waiting message for new sessions.
+) -> str:
+    """Format a waiting message as a string.
 
     Args:
         colors: ColorManager instance
         session_id: Session ID if specified
         message: Message to display
+
+    Returns:
+        Formatted waiting message string
     """
-    print()
+    lines = [""]
     if session_id:
-        print(
+        lines.append(
             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(
+        lines.append(f"{colors.bold}{colors.magenta}Context Stats{colors.reset}")
+    lines.append("")
+    lines.append(f"  {colors.cyan}⏳ {message}{colors.reset}")
+    lines.append("")
+    lines.append(
         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()
+    lines.append(f"  {colors.dim}Data will appear after the first Claude interaction.{colors.reset}")
+    lines.append("")
+    return "\n".join(lines)
+
+
+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(_format_waiting_message(colors, session_id, message))
 
 
 def main() -> None:
@@ -368,11 +440,11 @@ def main() -> None:
 
     # Run
     if args.no_watch:
-        success = render_once(state_file, args.type, renderer, colors)
+        success = render_once(state_file, args.type, renderer, colors, config=config)
         if not success:
             sys.exit(1)
     else:
-        run_watch_mode(state_file, args.type, args.watch, renderer, colors)
+        run_watch_mode(state_file, args.type, args.watch, renderer, colors, config=config)
 
 
 if __name__ == "__main__":

package/src/claude_statusline/cli/statusline.py

@@ -37,6 +37,7 @@ from claude_statusline.core.colors import (
 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.layout import fit_to_width, get_terminal_width
 from claude_statusline.formatters.time import get_current_timestamp
 from claude_statusline.formatters.tokens import calculate_context_usage, format_tokens
 
@@ -162,10 +163,10 @@ def main() -> None:
         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}"
-    )
+    base = f"{DIM}[{model}]{RESET} {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))
 
 
 if __name__ == "__main__":

package/src/claude_statusline/core/config.py

@@ -16,6 +16,7 @@ class Config:
     show_delta: bool = True
     show_session: bool = True
     show_io_tokens: bool = True
+    reduced_motion: bool = False
 
     _config_path: Path = field(default_factory=lambda: Path.home() / ".claude" / "statusline.conf")
 
@@ -57,6 +58,9 @@ show_delta=true
 
 # Show session_id in status line
 show_session=true
+
+# Disable rotating text animations
+reduced_motion=false
 """
             )
         except OSError:
@@ -84,6 +88,8 @@ show_session=true
                     self.show_session = value != "false"
                 elif key == "show_io_tokens":
                     self.show_io_tokens = value != "false"
+                elif key == "reduced_motion":
+                    self.reduced_motion = value != "false"
         except OSError:
             pass  # Use defaults on read error
 
@@ -95,4 +101,5 @@ show_session=true
             "show_delta": self.show_delta,
             "show_session": self.show_session,
             "show_io_tokens": self.show_io_tokens,
+            "reduced_motion": self.reduced_motion,
         }

package/src/claude_statusline/formatters/layout.py

@@ -0,0 +1,67 @@
+"""Layout utilities for fitting statusline output to terminal width."""
+
+from __future__ import annotations
+
+import re
+import shutil
+
+# Pattern to strip ANSI escape sequences
+_ANSI_RE = re.compile(r"\033\[[0-9;]*m")
+
+
+def visible_width(s: str) -> int:
+    """Return the visible width of a string after stripping ANSI escape sequences."""
+    return len(_ANSI_RE.sub("", s))
+
+
+def get_terminal_width() -> int:
+    """Return the terminal width in columns.
+
+    When running inside Claude Code's statusline subprocess, neither $COLUMNS
+    nor tput/shutil can detect the real terminal width (they always return 80).
+    If COLUMNS is not explicitly set and shutil falls back to 80, we use a
+    generous default of 200 so that no parts are unnecessarily dropped;
+    Claude Code's own UI handles any overflow/truncation.
+    """
+    import os
+
+    # If COLUMNS is explicitly set, trust it (real terminal or test override)
+    if os.environ.get("COLUMNS"):
+        return shutil.get_terminal_size().columns
+    # No COLUMNS env var — likely a Claude Code subprocess with no real TTY.
+    # shutil will fall back to 80, which is too narrow. Use 200 instead.
+    cols = shutil.get_terminal_size(fallback=(200, 24)).columns
+    return 200 if cols == 80 else cols
+
+
+def fit_to_width(parts: list[str], max_width: int) -> str:
+    """Assemble parts into a single line that fits within max_width.
+
+    Parts are added in priority order (first = highest priority).
+    The first part (base) is always included. Subsequent parts are
+    included only if adding them does not exceed max_width.
+    Empty parts are skipped.
+
+    Args:
+        parts: List of strings in priority order (highest first).
+        max_width: Maximum visible width allowed.
+
+    Returns:
+        Assembled string that fits within max_width.
+    """
+    if not parts:
+        return ""
+
+    # Base part is always included
+    result = parts[0]
+    current_width = visible_width(result)
+
+    for part in parts[1:]:
+        if not part:
+            continue
+        part_width = visible_width(part)
+        if current_width + part_width <= max_width:
+            result += part
+            current_width += part_width
+
+    return result

package/src/claude_statusline/graphs/renderer.py

@@ -8,7 +8,7 @@ from dataclasses import dataclass
 from claude_statusline.core.colors import ColorManager
 from claude_statusline.formatters.time import format_duration, format_timestamp
 from claude_statusline.formatters.tokens import format_tokens
-from claude_statusline.graphs.statistics import calculate_stats
+from claude_statusline.graphs.statistics import calculate_deltas, calculate_stats
 
 
 @dataclass
@@ -67,6 +67,26 @@ class GraphRenderer:
         self.colors = colors or ColorManager(enabled=True)
         self.dimensions = dimensions or GraphDimensions.detect()
         self.token_detail = token_detail
+        self._output_lines: list[str] | None = None
+
+    def begin_buffering(self) -> None:
+        """Start buffering output instead of printing directly."""
+        self._output_lines = []
+
+    def get_buffer(self) -> str:
+        """Return buffered output as a single string and stop buffering."""
+        if self._output_lines is None:
+            return ""
+        result = "\n".join(self._output_lines)
+        self._output_lines = None
+        return result
+
+    def _emit(self, line: str = "") -> None:
+        """Emit a line of output. Buffers if buffering is active, otherwise prints."""
+        if self._output_lines is not None:
+            self._output_lines.append(line)
+        else:
+            print(line)
 
     def render_timeseries(
         self,
@@ -100,14 +120,14 @@ class GraphRenderer:
         height = self.dimensions.graph_height
 
         # Print title and stats
-        print()
-        print(f"{self.colors.bold}{title}{self.colors.reset}")
-        print(
+        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"Points: {n}{self.colors.reset}"
         )
-        print()
+        self._emit()
 
         # Build the graph grid
         grid = self._build_grid(data, min_val, max_val, value_range, width, height)
@@ -123,13 +143,13 @@ class GraphRenderer:
                 label = ""
 
             row_data = grid[r] if r < len(grid) else " " * width
-            print(
+            self._emit(
                 f"{label:>10} {self.colors.dim}│{self.colors.reset}"
                 f"{color}{row_data}{self.colors.reset}"
             )
 
         # X-axis
-        print(f"{'':>10} {self.colors.dim}└{'─' * width}{self.colors.reset}")
+        self._emit(f"{'':>10} {self.colors.dim}└{'─' * width}{self.colors.reset}")
 
         # Time labels
         if timestamps:
@@ -139,7 +159,7 @@ class GraphRenderer:
             mid_time = format_timestamp(timestamps[mid_idx]) if n > 2 else ""
 
             spacing = width // 3
-            print(
+            self._emit(
                 f"{' ':>11}{self.colors.dim}"
                 f"{first_time:<{spacing}}{mid_time}{last_time:>{spacing}}"
                 f"{self.colors.reset}"
@@ -278,58 +298,58 @@ class GraphRenderer:
             status_text = "Wrap Up Zone"
             status_hint = "Better to wrap up and start a new session"
 
-        print()
-        print(f"{self.colors.bold}Session Summary{self.colors.reset}")
+        self._emit()
+        self._emit(f"{self.colors.bold}Session Summary{self.colors.reset}")
         line_width = self.dimensions.graph_width + 11
-        print(f"{self.colors.dim}{'-' * line_width}{self.colors.reset}")
+        self._emit(f"{self.colors.dim}{'-' * line_width}{self.colors.reset}")
 
         # Context remaining (before status)
         if last.context_window_size > 0:
-            print(
+            self._emit(
                 f"  {status_color}{'Context Remaining:':<20}{self.colors.reset} "
                 f"{format_tokens(remaining_context, self.token_detail)}/{format_tokens(last.context_window_size, self.token_detail)} ({remaining_percentage}%)"
             )
 
         # Status indicator - highlighted
         if last.context_window_size > 0:
-            print(
+            self._emit(
                 f"  {status_color}{self.colors.bold}>>> {status_text.upper()} <<<{self.colors.reset} "
                 f"{self.colors.dim}({status_hint}){self.colors.reset}"
             )
-            print()
+            self._emit()
 
         # Session details (ordered: Last Growth, I/O, Lines, Cost, Model, Duration)
         if deltas:
             current_growth = deltas[-1]
-            print(
+            self._emit(
                 f"  {self.colors.cyan}{'Last Growth:':<20}{self.colors.reset} "
                 f"+{format_tokens(current_growth, self.token_detail)}"
             )
-        print(
+        self._emit(
             f"  {self.colors.blue}{'Input Tokens:':<20}{self.colors.reset} "
             f"{format_tokens(last.current_input_tokens, self.token_detail)}"
         )
-        print(
+        self._emit(
             f"  {self.colors.magenta}{'Output Tokens:':<20}{self.colors.reset} "
             f"{format_tokens(last.current_output_tokens, self.token_detail)}"
         )
         if last.lines_added > 0 or last.lines_removed > 0:
-            print(
+            self._emit(
                 f"  {self.colors.dim}{'Lines Changed:':<20}{self.colors.reset} "
                 f"{self.colors.green}+{last.lines_added:,}{self.colors.reset} / "
                 f"{self.colors.red}-{last.lines_removed:,}{self.colors.reset}"
             )
         if last.cost_usd > 0:
-            print(
+            self._emit(
                 f"  {self.colors.yellow}{'Total Cost:':<20}{self.colors.reset} ${last.cost_usd:.4f}"
             )
         if last.model_id:
-            print(f"  {self.colors.dim}{'Model:':<20}{self.colors.reset} {last.model_id}")
-        print(
+            self._emit(f"  {self.colors.dim}{'Model:':<20}{self.colors.reset} {last.model_id}")
+        self._emit(
             f"  {self.colors.cyan}{'Session Duration:':<20}{self.colors.reset} "
             f"{format_duration(duration)}"
         )
-        print()
+        self._emit()
 
     def render_footer(self, version: str = "1.0.0", commit_hash: str = "dev") -> None:
         """Render the footer with version info.
@@ -338,9 +358,9 @@ class GraphRenderer:
             version: Package version
             commit_hash: Git commit hash
         """
-        print(
+        self._emit(
             f"{self.colors.dim}Powered by {self.colors.cyan}claude-statusline"
             f"{self.colors.dim} v{version}-{commit_hash} - "
             f"https://github.com/luongnv89/cc-context-stats{self.colors.reset}"
         )
-        print()
+        self._emit()

package/src/claude_statusline/graphs/statistics.py

@@ -37,6 +37,40 @@ def calculate_stats(data: list[int]) -> Stats:
     return Stats(min_val=min_val, max_val=max_val, avg_val=avg_val, total=total, count=count)
 
 
+def detect_spike(deltas: list[int], context_window_size: int, window: int = 5) -> bool:
+    """Check if the latest delta is a spike.
+
+    A spike is defined as:
+    - Latest delta > 15% of context window size, OR
+    - Latest delta > 3x the rolling average of the last `window` deltas
+
+    Args:
+        deltas: List of token deltas
+        context_window_size: Total context window size in tokens
+        window: Number of recent deltas for rolling average (default: 5)
+
+    Returns:
+        True if the latest delta qualifies as a spike
+    """
+    if not deltas:
+        return False
+
+    latest = deltas[-1]
+
+    # Check absolute threshold: > 15% of context window
+    if context_window_size > 0 and latest > context_window_size * 0.15:
+        return True
+
+    # Check relative threshold: > 3x rolling average of previous deltas
+    previous = deltas[-(window + 1):-1] if len(deltas) > window else deltas[:-1]
+    if previous:
+        avg = sum(previous) / len(previous)
+        if avg > 0 and latest > avg * 3:
+            return True
+
+    return False
+
+
 def calculate_deltas(values: list[int]) -> list[int]:
     """Calculate deltas between consecutive values.
 

package/src/claude_statusline/ui/__init__.py

@@ -0,0 +1 @@
+"""UI components for context-stats display."""

package/src/claude_statusline/ui/icons.py

@@ -0,0 +1,93 @@
+"""Activity tier detection for token usage visualization."""
+
+from __future__ import annotations
+
+from enum import Enum
+
+from claude_statusline.core.state import StateEntry
+from claude_statusline.graphs.statistics import calculate_deltas, detect_spike
+
+
+class ActivityTier(Enum):
+    """Token activity intensity tiers."""
+
+    IDLE = "idle"
+    LOW = "low"
+    MEDIUM = "medium"
+    HIGH = "high"
+    SPIKE = "spike"
+
+
+# Tier labels for accessibility (understandable without color)
+TIER_LABELS: dict[ActivityTier, str] = {
+    ActivityTier.IDLE: "Idle",
+    ActivityTier.LOW: "Low activity",
+    ActivityTier.MEDIUM: "Active",
+    ActivityTier.HIGH: "High activity",
+    ActivityTier.SPIKE: "Spike!",
+}
+
+
+def get_activity_tier(
+    entries: list[StateEntry],
+    context_window_size: int,
+) -> ActivityTier:
+    """Determine the current activity tier based on recent token deltas.
+
+    Args:
+        entries: List of StateEntry objects (chronological order)
+        context_window_size: Total context window size in tokens
+
+    Returns:
+        The current ActivityTier
+    """
+    if len(entries) < 2:
+        return ActivityTier.IDLE
+
+    # Check if session is idle (>30s since last entry)
+    import time
+
+    now = int(time.time())
+    last_timestamp = entries[-1].timestamp
+    if now - last_timestamp > 30:
+        return ActivityTier.IDLE
+
+    # Calculate deltas from context usage
+    context_used = [e.current_used_tokens for e in entries]
+    deltas = calculate_deltas(context_used)
+
+    if not deltas:
+        return ActivityTier.IDLE
+
+    latest_delta = deltas[-1]
+
+    if context_window_size <= 0:
+        return ActivityTier.LOW if latest_delta > 0 else ActivityTier.IDLE
+
+    # Check for spike first (highest priority)
+    if detect_spike(deltas, context_window_size):
+        return ActivityTier.SPIKE
+
+    # Calculate delta as percentage of context window
+    delta_pct = (latest_delta / context_window_size) * 100
+
+    if delta_pct > 5:
+        return ActivityTier.HIGH
+    elif delta_pct > 2:
+        return ActivityTier.MEDIUM
+    elif latest_delta > 0:
+        return ActivityTier.LOW
+    else:
+        return ActivityTier.IDLE
+
+
+def get_tier_label(tier: ActivityTier) -> str:
+    """Get an accessible text label for a tier.
+
+    Args:
+        tier: The activity tier
+
+    Returns:
+        Human-readable label string
+    """
+    return TIER_LABELS.get(tier, "")