cc-context-stats 1.6.2 → 1.8.0

package/docs/scripts.md

@@ -2,18 +2,26 @@
 
 ## Overview
 
-| Script                  | Platform     | Requirements | Features                          |
-| ----------------------- | ------------ | ------------ | --------------------------------- |
-| `statusline-full.sh`    | macOS, Linux | `jq`         | Full-featured with all indicators |
-| `statusline-git.sh`     | macOS, Linux | `jq`         | Git branch and changes            |
-| `statusline-minimal.sh` | macOS, Linux | `jq`         | Model + directory only            |
-| `statusline.py`         | All          | Python 3     | Cross-platform, full-featured     |
-| `statusline.js`         | All          | Node.js      | Cross-platform, full-featured     |
-| `context-stats.sh`      | macOS, Linux | None         | Token usage visualization         |
+| Script                  | Platform     | Requirements | State Writes | Features                          |
+| ----------------------- | ------------ | ------------ | ------------ | --------------------------------- |
+| `statusline-full.sh`    | macOS, Linux | `jq`         | No           | Full-featured with all indicators |
+| `statusline-git.sh`     | macOS, Linux | `jq`         | No           | Git branch and changes            |
+| `statusline-minimal.sh` | macOS, Linux | `jq`         | No           | Model + directory only            |
+| `statusline.py`         | All          | Python 3     | Yes          | Cross-platform, full-featured     |
+| `statusline.js`         | All          | Node.js 18+  | Yes          | Cross-platform, full-featured     |
+| `context-stats.sh`      | macOS, Linux | Bash         | No           | Token usage visualization (CLI)   |
+
+## Installation Methods
+
+| Method | Statusline Command | Context Stats Command |
+| ------ | ------------------ | --------------------- |
+| `pip install cc-context-stats` | `claude-statusline` | `context-stats` |
+| `npm install -g cc-context-stats` | `claude-statusline` | `context-stats` |
+| Shell installer (`install.sh`) | `~/.claude/statusline.sh` | `~/.local/bin/context-stats` |
 
 ## Bash Scripts
 
-### statusline-full.sh (Recommended)
+### statusline-full.sh (Recommended for bash users)
 
 Complete status line with all features:
 
@@ -25,6 +33,8 @@ Complete status line with all features:
 - Autocompact indicator
 - Session ID
 
+> **Note:** Does not write state files. For context-stats CLI support, use the Python or Node.js script instead.
+
 ### statusline-git.sh
 
 Lighter version with git info:
@@ -46,15 +56,27 @@ Minimal footprint:
 
 Python implementation matching `statusline-full.sh` functionality. Works on Windows, macOS, and Linux without additional dependencies beyond Python 3.
 
+Features beyond bash scripts:
+- Writes state files for context-stats CLI
+- Duplicate-entry deduplication
+- State file rotation (10k/5k threshold)
+- 5-second git command timeout
+
 ### statusline.js
 
-Node.js implementation matching `statusline-full.sh` functionality. Works on all platforms with Node.js installed.
+Node.js implementation matching `statusline-full.sh` functionality. Works on all platforms with Node.js 18+ installed.
+
+Features beyond bash scripts:
+- Writes state files for context-stats CLI
+- Duplicate-entry deduplication
+- State file rotation (10k/5k threshold)
+- 5-second git command timeout
 
 ## Utility Scripts
 
 ### context-stats.sh
 
-Standalone CLI tool for visualizing token consumption. See [Context Stats](context-stats.md) for details.
+Standalone bash CLI tool for visualizing token consumption. Reads state files written by the Python or Node.js statusline scripts. See [Context Stats](context-stats.md) for details.
 
 ## Output Format
 
@@ -102,15 +124,17 @@ Scripts receive JSON via stdin from Claude Code:
 
 ## Color Codes
 
-All scripts use consistent ANSI colors:
-
-| Color   | Code         | Usage                      |
-| ------- | ------------ | -------------------------- |
-| Blue    | `\033[0;34m` | Directory                  |
-| Magenta | `\033[0;35m` | Git branch                 |
-| Cyan    | `\033[0;36m` | Changes count              |
-| Green   | `\033[0;32m` | High availability (>50%)   |
-| Yellow  | `\033[0;33m` | Medium availability (>25%) |
-| Red     | `\033[0;31m` | Low availability (<=25%)   |
-| Dim     | `\033[2m`    | Model, AC indicator        |
-| Reset   | `\033[0m`    | Reset formatting           |
+All scripts use consistent ANSI colors (defaults, overridable via `~/.claude/statusline.conf`):
+
+| Color   | Code         | Usage                      | Config Key      |
+| ------- | ------------ | -------------------------- | --------------- |
+| Blue    | `\033[0;34m` | Directory                  | `color_blue`    |
+| Magenta | `\033[0;35m` | Git branch                 | `color_magenta` |
+| Cyan    | `\033[0;36m` | Changes count              | `color_cyan`    |
+| Green   | `\033[0;32m` | High availability (>50%)   | `color_green`   |
+| Yellow  | `\033[0;33m` | Medium availability (>25%) | `color_yellow`  |
+| Red     | `\033[0;31m` | Low availability (<=25%)   | `color_red`     |
+| Dim     | `\033[2m`    | Model, AC indicator        | —               |
+| Reset   | `\033[0m`    | Reset formatting           | —               |
+
+See [Configuration](configuration.md#custom-colors) for details on overriding colors with named colors or hex codes.

package/docs/troubleshooting.md

@@ -24,6 +24,22 @@
    cat ~/.claude/settings.json
    ```
 
+**pip/npm install:**
+
+1. Verify the command is available:
+
+   ```bash
+   which claude-statusline
+   ```
+
+2. Test it:
+
+   ```bash
+   echo '{"model":{"display_name":"Test"}}' | claude-statusline
+   ```
+
+3. Ensure your settings.json uses `"command": "claude-statusline"` (not a file path).
+
 **Windows (Python):**
 
 ```powershell
@@ -32,7 +48,7 @@ echo {"model":{"display_name":"Test"}} | python %USERPROFILE%\.claude\statusline
 
 ### jq not found
 
-The bash scripts require `jq` for JSON parsing.
+The bash scripts require `jq` for JSON parsing. Python and Node.js scripts do **not** need `jq`.
 
 **macOS:**
 
@@ -56,6 +72,22 @@ Alternatively, use the Python or Node.js version which don't require `jq`.
 
 ### context-stats command not found
 
+**If installed via pip or npm:**
+
+1. Verify installation:
+
+   ```bash
+   which context-stats
+   ```
+
+2. Reinstall if missing:
+
+   ```bash
+   pip install cc-context-stats   # or: npm install -g cc-context-stats
+   ```
+
+**If installed via shell installer:**
+
 1. Verify installation:
 
    ```bash
@@ -80,13 +112,58 @@ Alternatively, use the Python or Node.js version which don't require `jq`.
    source ~/.bashrc
    ```
 
+### pip install fails
+
+1. Ensure Python 3.9+:
+
+   ```bash
+   python3 --version
+   ```
+
+2. Try with `--user` flag:
+
+   ```bash
+   pip install --user cc-context-stats
+   ```
+
+3. Or use `uv`:
+
+   ```bash
+   uv pip install cc-context-stats
+   ```
+
+### npm install fails
+
+1. Ensure Node.js 18+:
+
+   ```bash
+   node --version
+   ```
+
+2. Try with sudo (Linux/macOS):
+
+   ```bash
+   sudo npm install -g cc-context-stats
+   ```
+
+3. Or fix npm permissions:
+
+   ```bash
+   mkdir -p ~/.npm-global
+   npm config set prefix '~/.npm-global'
+   echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.zshrc
+   source ~/.zshrc
+   npm install -g cc-context-stats
+   ```
+
 ### No token graph data
 
 Token history requires:
 
-1. `show_delta=true` in `~/.claude/statusline.conf` (default)
-2. Active Claude Code session generating state files
-3. State files at `~/.claude/statusline/statusline.<session_id>.state`
+1. Python or Node.js statusline script (bash scripts do **not** write state files)
+2. `show_delta=true` in `~/.claude/statusline.conf` (default)
+3. Active Claude Code session generating state files
+4. State files at `~/.claude/statusline/statusline.<session_id>.state`
 
 Check for state files:
 
@@ -108,6 +185,8 @@ ls -la ~/.claude/statusline/statusline.*.state
    which git
    ```
 
+3. Git commands have a 5-second timeout. If your repo is very large, git operations may time out silently.
+
 ### Wrong token colors
 
 Token colors depend on availability percentage:
@@ -124,6 +203,12 @@ If colors look wrong, check terminal color support.
 
 Token delta requires multiple statusline refreshes. The first refresh establishes a baseline; subsequent refreshes show the delta.
 
+If delta is always zero after multiple refreshes, check that the state file is being written:
+
+```bash
+wc -l ~/.claude/statusline/statusline.*.state
+```
+
 ### Configuration not taking effect
 
 1. Check config file location:
@@ -167,6 +252,9 @@ EOF
 cat /tmp/test-input.json | ~/.claude/statusline.sh
 cat /tmp/test-input.json | python3 ~/.claude/statusline.py
 cat /tmp/test-input.json | node ~/.claude/statusline.js
+
+# Test pip/npm installed version
+cat /tmp/test-input.json | claude-statusline
 ```
 
 ### Check state files
@@ -185,5 +273,6 @@ watch -n 1 'tail -5 ~/.claude/statusline/statusline.*.state'
 - Open a new issue with:
   - Operating system
   - Shell type (bash/zsh)
+  - Installation method (pip, npm, shell installer, manual)
   - Script version being used
   - Error messages or unexpected behavior

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cc-context-stats",
-  "version": "1.6.2",
+  "version": "1.8.0",
   "description": "Monitor your Claude Code session context in real-time - track token usage and never run out of context",
   "main": "scripts/statusline.js",
   "scripts": {

package/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "cc-context-stats"
-version = "1.6.2"
+version = "1.8.0"
 description = "Monitor your Claude Code session context in real-time - track token usage and never run out of context"
 readme = "README.md"
 license = { text = "MIT" }

package/scripts/statusline-full.sh

@@ -22,7 +22,7 @@
 # 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
 
-# Colors
+# Colors (defaults, overridable via config)
 BLUE='\033[0;34m'
 MAGENTA='\033[0;35m'
 CYAN='\033[0;36m'
@@ -32,6 +32,92 @@ RED='\033[0;31m'
 DIM='\033[2m'
 RESET='\033[0m'
 
+# Named colors for config parsing
+declare -A 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'
+)
+
+# Color config key to slot mapping
+declare -A COLOR_KEYS=(
+    [color_green]=GREEN [color_yellow]=YELLOW [color_red]=RED
+    [color_blue]=BLUE [color_magenta]=MAGENTA [color_cyan]=CYAN
+)
+
+# Parse a color name or #rrggbb hex into an ANSI escape code
+parse_color() {
+    local value
+    value=$(echo "$1" | tr '[:upper:]' '[:lower:]' | xargs)
+    if [[ -n "${COLOR_NAMES[$value]+x}" ]]; then
+        echo "${COLOR_NAMES[$value]}"
+        return
+    fi
+    if [[ "$value" =~ ^#[0-9a-f]{6}$ ]]; then
+        local r=$((16#${value:1:2}))
+        local g=$((16#${value:3:2}))
+        local b=$((16#${value:5:2}))
+        echo "\033[38;2;${r};${g};${b}m"
+        return
+    fi
+}
+
+# State file rotation constants
+ROTATION_THRESHOLD=10000
+ROTATION_KEEP=5000
+
+# Rotate state file if it exceeds threshold
+maybe_rotate_state_file() {
+    local state_file="$1"
+    [[ -f "$state_file" ]] || return
+    local line_count
+    line_count=$(wc -l < "$state_file" | tr -d ' ')
+    if [[ "$line_count" -gt "$ROTATION_THRESHOLD" ]]; then
+        local tmp_file="${state_file}.tmp.$$"
+        tail -n "$ROTATION_KEEP" "$state_file" > "$tmp_file" && mv "$tmp_file" "$state_file" || rm -f "$tmp_file"
+    fi
+}
+
+# Model Intelligence computation (uses awk for float math)
+compute_mi() {
+    local used_tokens=$1 context_window=$2 cache_read_val=$3 total_context=$4
+    local delta_lines=$5 delta_output=$6 beta=$7
+    awk -v used="$used_tokens" -v cw="$context_window" -v cr="$cache_read_val" \
+        -v tc="$total_context" -v dl="$delta_lines" -v do_val="$delta_output" -v b="$beta" '
+    BEGIN {
+        if (cw == 0) { printf "1.00 1.000 1.000 0.500"; exit }
+        # CPS
+        u = used / cw
+        if (u <= 0) cps = 1.0
+        else { cps = 1.0 - (u ^ b); if (cps < 0) cps = 0.0 }
+        # ES
+        if (tc == 0) es = 1.0
+        else es = 0.3 + 0.7 * (cr / tc)
+        # PS
+        if (do_val == "" || do_val + 0 <= 0) ps = 0.5
+        else {
+            ratio = dl / do_val
+            normalized = ratio / 0.2
+            if (normalized > 1.0) normalized = 1.0
+            ps = 0.2 + 0.8 * normalized
+        }
+        mi = 0.60 * cps + 0.25 * es + 0.15 * ps
+        printf "%.2f %.3f %.3f %.3f", mi, cps, es, ps
+    }'
+}
+
+get_mi_color() {
+    local mi_val="$1"
+    awk -v mi="$mi_val" 'BEGIN {
+        if (mi + 0 > 0.65) print "green"
+        else if (mi + 0 > 0.35) print "yellow"
+        else print "red"
+    }'
+}
+
 # Read JSON input from stdin
 input=$(cat)
 
@@ -63,12 +149,11 @@ autocompact_enabled=true
 token_detail_enabled=true
 show_delta_enabled=true
 show_session_enabled=true
-autocompact=""    # Will be set by sourced config
-token_detail=""   # Will be set by sourced config
-show_delta=""     # Will be set by sourced config
-show_session=""   # Will be set by sourced config
+show_mi_enabled=true
+mi_curve_beta=1.5
 ac_info=""
 delta_info=""
+mi_info=""
 session_info=""
 
 # Create config file with defaults if it doesn't exist
@@ -87,24 +172,44 @@ show_delta=true
 
 # Show session_id in status line
 show_session=true
+
+# Model Intelligence (MI) score display
+show_mi=true
+
+# MI degradation curve shape (higher = steeper initial drop)
+# mi_curve_beta=1.5
 EOF
 fi
 
 if [[ -f ~/.claude/statusline.conf ]]; then
-    # shellcheck source=/dev/null
-    source ~/.claude/statusline.conf
-    if [[ "$autocompact" == "false" ]]; then
-        autocompact_enabled=false
-    fi
-    if [[ "$token_detail" == "false" ]]; then
-        token_detail_enabled=false
-    fi
-    if [[ "$show_delta" == "false" ]]; then
-        show_delta_enabled=false
-    fi
-    if [[ "$show_session" == "false" ]]; then
-        show_session_enabled=false
-    fi
+    while IFS= read -r line; do
+        line=$(echo "$line" | xargs)
+        [[ -z "$line" || "$line" == \#* ]] && continue
+        [[ "$line" != *=* ]] && continue
+        key="${line%%=*}"
+        key=$(echo "$key" | xargs)
+        raw_value="${line#*=}"
+        raw_value=$(echo "$raw_value" | xargs)
+        value_lower=$(echo "$raw_value" | tr '[:upper:]' '[:lower:]')
+        case "$key" in
+            autocompact)    [[ "$value_lower" == "false" ]] && autocompact_enabled=false ;;
+            token_detail)   [[ "$value_lower" == "false" ]] && token_detail_enabled=false ;;
+            show_delta)     [[ "$value_lower" == "false" ]] && show_delta_enabled=false ;;
+            show_session)   [[ "$value_lower" == "false" ]] && show_session_enabled=false ;;
+            show_mi)        [[ "$value_lower" == "false" ]] && show_mi_enabled=false ;;
+            mi_curve_beta)  mi_curve_beta="$raw_value" ;;
+            color_*)
+                if [[ -n "${COLOR_KEYS[$key]+x}" ]]; then
+                    local slot="${COLOR_KEYS[$key]}"
+                    local ansi
+                    ansi=$(parse_color "$raw_value")
+                    if [[ -n "$ansi" ]]; then
+                        eval "$slot='$ansi'"
+                    fi
+                fi
+                ;;
+        esac
+    done < ~/.claude/statusline.conf
 fi
 
 # Width-fitting helpers
@@ -229,10 +334,10 @@ if [[ "$total_size" -gt 0 && "$current_usage" != "null" ]]; then
         ctx_color="$RED"
     fi
 
-    context_info=" | ${ctx_color}${free_display} free (${free_pct}%)${RESET}"
+    context_info=" | ${ctx_color}${free_display} (${free_pct}%)${RESET}"
 
-    # Calculate and display token delta if enabled
-    if [[ "$show_delta_enabled" == "true" ]]; then
+    # Read previous entry if needed for delta OR MI
+    if [[ "$show_delta_enabled" == "true" || "$show_mi_enabled" == "true" ]]; then
         # Use session_id for per-session state (avoids conflicts with parallel sessions)
         state_dir=~/.claude/statusline
         mkdir -p "$state_dir"
@@ -245,7 +350,6 @@ if [[ "$total_size" -gt 0 && "$current_usage" != "null" ]]; then
                 if [[ ! -f "$new_file" ]]; then
                     mv "$old_file" "$new_file" 2>/dev/null || true
                 else
-                    # New file exists, just remove old one
                     rm -f "$old_file" 2>/dev/null || true
                 fi
             fi
@@ -258,37 +362,67 @@ if [[ "$total_size" -gt 0 && "$current_usage" != "null" ]]; then
         fi
         has_prev=false
         prev_tokens=0
+        prev_output_tokens=0
+        prev_lines_added=0
+        prev_lines_removed=0
         if [[ -f "$state_file" ]]; then
             has_prev=true
-            # Read last line and calculate previous context usage
-            # CSV: ts[0],in[1],out[2],cur_in[3],cur_out[4],cache_create[5],cache_read[6]
+            # Read last line and calculate previous state
+            # CSV: ts[0],in[1],out[2],cur_in[3],cur_out[4],cache_create[5],cache_read[6],
+            #      cost[7],+lines[8],-lines[9],session[10],model[11],dir[12],size[13]
             last_line=$(tail -1 "$state_file" 2>/dev/null)
             if [[ -n "$last_line" ]]; then
                 prev_cur_in=$(echo "$last_line" | cut -d',' -f4)
                 prev_cache_create=$(echo "$last_line" | cut -d',' -f6)
                 prev_cache_read=$(echo "$last_line" | cut -d',' -f7)
                 prev_tokens=$(( ${prev_cur_in:-0} + ${prev_cache_create:-0} + ${prev_cache_read:-0} ))
+                prev_output_tokens=$(echo "$last_line" | cut -d',' -f3)
+                prev_lines_added=$(echo "$last_line" | cut -d',' -f9)
+                prev_lines_removed=$(echo "$last_line" | cut -d',' -f10)
             fi
         fi
-        # Calculate delta
-        delta=$((used_tokens - prev_tokens))
-        # delta calculated for display
-        # Only show positive delta (and skip first run when no previous state)
-        if [[ "$has_prev" == "true" && "$delta" -gt 0 ]]; then
-            if [[ "$token_detail_enabled" == "true" ]]; then
-                delta_display=$(awk -v n="$delta" 'BEGIN { printf "%\047d", n }')
+
+        # Calculate and display token delta if enabled
+        if [[ "$show_delta_enabled" == "true" ]]; then
+            delta=$((used_tokens - prev_tokens))
+            if [[ "$has_prev" == "true" && "$delta" -gt 0 ]]; then
+                if [[ "$token_detail_enabled" == "true" ]]; then
+                    delta_display=$(awk -v n="$delta" 'BEGIN { printf "%\047d", n }')
+                else
+                    delta_display=$(awk "BEGIN {printf \"%.1fk\", $delta / 1000}")
+                fi
+                delta_info=" ${DIM}[+${delta_display}]${RESET}"
+            fi
+        fi
+
+        # Calculate and display MI score if enabled
+        if [[ "$show_mi_enabled" == "true" ]]; then
+            if [[ "$has_prev" == "true" ]]; then
+                delta_la=$(( ${lines_added:-0} - ${prev_lines_added:-0} ))
+                delta_lr=$(( ${lines_removed:-0} - ${prev_lines_removed:-0} ))
+                mi_delta_lines=$(( delta_la + delta_lr ))
+                mi_delta_output=$(( ${total_output_tokens:-0} - ${prev_output_tokens:-0} ))
             else
-                delta_display=$(awk "BEGIN {printf \"%.1fk\", $delta / 1000}")
+                mi_delta_lines=0
+                mi_delta_output=""
             fi
-            delta_info=" ${DIM}[+${delta_display}]${RESET}"
+            mi_result=$(compute_mi "$used_tokens" "$total_size" "$cache_read" "$used_tokens" "$mi_delta_lines" "$mi_delta_output" "$mi_curve_beta")
+            mi_val=$(echo "$mi_result" | cut -d' ' -f1)
+            mi_color_name=$(get_mi_color "$mi_val")
+            case "$mi_color_name" in
+                green)  mi_color="$GREEN" ;;
+                yellow) mi_color="$YELLOW" ;;
+                red)    mi_color="$RED" ;;
+            esac
+            mi_info=" ${mi_color}MI:${mi_val}${RESET}"
         fi
+
         # Only append if context usage changed (avoid duplicates from multiple refreshes)
         cur_input_tokens=$(echo "$current_usage" | jq -r '.input_tokens // 0')
         cur_output_tokens=$(echo "$current_usage" | jq -r '.output_tokens // 0')
         if [[ "$has_prev" != "true" || "$used_tokens" != "$prev_tokens" ]]; then
-            # Append current usage with comprehensive format
-            # Format: ts,in,out,cur_in,cur_out,cache_create,cache_read,cost,+lines,-lines,session,model,dir,size
             echo "$(date +%s),$total_input_tokens,$total_output_tokens,$cur_input_tokens,$cur_output_tokens,$cache_creation,$cache_read,$cost_usd,$lines_added,$lines_removed,$session_id,$model_id,$workspace_project_dir,$total_size" >>"$state_file"
+            maybe_rotate_state_file "$state_file"
         fi
     fi
 fi
@@ -301,4 +435,4 @@ fi
 # Output: [Model] directory | branch [changes] | XXk free (XX%) [+delta] [AC] [S:session_id]
 base="${DIM}[${model}]${RESET} ${BLUE}${dir_name}${RESET}"
 max_width=$(get_terminal_width)
-fit_to_width "$max_width" "$base" "$git_info" "$context_info" "$delta_info" "$ac_info" "$session_info"
+fit_to_width "$max_width" "$base" "$git_info" "$context_info" "$delta_info" "$mi_info" "$ac_info" "$session_info"