cc-context-stats 1.12.1 → 1.13.1

package/README.md

@@ -91,7 +91,7 @@ graph LR
 
 ## Customization
 
-Every element in the status line can be individually colored and toggled. Configuration lives in `~/.claude/statusline.conf` (created automatically on first run).
+Every element in the status line can be individually colored and toggled. Configuration lives in `~/.claude/statusline.conf` (created automatically on first run). See [`examples/statusline.conf`](examples/statusline.conf) for the canonical reference with all parameters documented.
 
 ### Status Line Anatomy
 
@@ -334,6 +334,16 @@ Add to `~/.claude/settings.json`:
 }
 ```
 
+**(Optional) Copy the example config for full customization:**
+
+A default config is created automatically on first run. To start from the fully-documented example instead, copy it before launching:
+
+```bash
+cp examples/statusline.conf ~/.claude/statusline.conf
+```
+
+See [`examples/statusline.conf`](examples/statusline.conf) for all available settings with detailed explanations.
+
 Restart Claude Code. MI score and context stats appear in your status bar immediately.
 
 ### Real-Time Dashboard

package/package.json

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

package/scripts/statusline.js

@@ -6,8 +6,8 @@
  * 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)
+ *   autocompact=false  (when autocompact is disabled in Claude Code - default)
+ *   autocompact=true   (when you enable 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)
@@ -114,35 +114,49 @@ function getMIColor(mi, utilization, greenColor, yellowColor, redColor) {
 /**
  * Determine context zone indicator (P/C/D/X/Z) based on token usage.
  * Returns { zone, colorName }.
+ * zoneConfig is an optional object of threshold overrides (0 = use default).
  */
-function getContextZone(usedTokens, contextWindowSize) {
+function getContextZone(usedTokens, contextWindowSize, zoneConfig) {
     if (contextWindowSize === 0) {
         return { zone: 'Plan', colorName: 'green' };
     }
 
-    const isLarge = contextWindowSize >= LARGE_MODEL_THRESHOLD;
+    const zc = zoneConfig || {};
+
+    const lmt = zc.large_model_threshold || LARGE_MODEL_THRESHOLD;
+    const isLarge = contextWindowSize >= lmt;
 
     if (isLarge) {
-        if (usedTokens < ZONE_1M_P_MAX) {
+        const pMax = zc.zone_1m_plan_max || ZONE_1M_P_MAX;
+        const cMax = zc.zone_1m_code_max || ZONE_1M_C_MAX;
+        const dMax = zc.zone_1m_dump_max || ZONE_1M_D_MAX;
+        const xMax = zc.zone_1m_xdump_max || ZONE_1M_X_MAX;
+
+        if (usedTokens < pMax) {
             return { zone: 'Plan', colorName: 'green' };
         }
-        if (usedTokens < ZONE_1M_C_MAX) {
+        if (usedTokens < cMax) {
             return { zone: 'Code', colorName: 'yellow' };
         }
-        if (usedTokens < ZONE_1M_D_MAX) {
+        if (usedTokens < dMax) {
             return { zone: 'Dump', colorName: 'orange' };
         }
-        if (usedTokens < ZONE_1M_X_MAX) {
+        if (usedTokens < xMax) {
             return { zone: 'ExDump', colorName: 'dark_red' };
         }
         return { zone: 'Dead', colorName: 'gray' };
     }
 
-    // Standard models (< 500k context)
-    const dumpZoneTokens = Math.floor(contextWindowSize * ZONE_STD_DUMP_ZONE);
-    const warnStart = Math.max(0, dumpZoneTokens - ZONE_STD_WARN_BUFFER);
-    const hardLimitTokens = Math.floor(contextWindowSize * ZONE_STD_HARD_LIMIT);
-    const deadZoneTokens = Math.floor(contextWindowSize * ZONE_STD_DEAD_ZONE);
+    // Standard models
+    const dumpRatio = zc.zone_std_dump_ratio || ZONE_STD_DUMP_ZONE;
+    const warnBuf = zc.zone_std_warn_buffer || ZONE_STD_WARN_BUFFER;
+    const hardLim = zc.zone_std_hard_limit || ZONE_STD_HARD_LIMIT;
+    const deadRat = zc.zone_std_dead_ratio || ZONE_STD_DEAD_ZONE;
+
+    const dumpZoneTokens = Math.floor(contextWindowSize * dumpRatio);
+    const warnStart = Math.max(0, dumpZoneTokens - warnBuf);
+    const hardLimitTokens = Math.floor(contextWindowSize * hardLim);
+    const deadZoneTokens = Math.floor(contextWindowSize * deadRat);
 
     if (usedTokens < warnStart) {
         return { zone: 'Plan', colorName: 'green' };
@@ -284,6 +298,23 @@ const COLOR_CONFIG_KEYS = {
     color_separator: 'separator',
 };
 
+// Zone threshold config keys (integer token counts)
+const ZONE_INT_KEYS = new Set([
+    'zone_1m_plan_max',
+    'zone_1m_code_max',
+    'zone_1m_dump_max',
+    'zone_1m_xdump_max',
+    'zone_std_warn_buffer',
+    'large_model_threshold',
+]);
+
+// Zone threshold config keys (float ratios 0-1)
+const ZONE_FLOAT_KEYS = new Set([
+    'zone_std_dump_ratio',
+    'zone_std_hard_limit',
+    'zone_std_dead_ratio',
+]);
+
 /**
  * Return the visible width of a string after stripping ANSI escape sequences.
  */
@@ -384,7 +415,7 @@ function getGitInfo(projectDir, magentaColor, cyanColor) {
 
 function readConfig() {
     const config = {
-        autocompact: true,
+        autocompact: false,
         tokenDetail: true,
         showDelta: true,
         showSession: true,
@@ -393,6 +424,7 @@ function readConfig() {
         showMI: false,
         miCurveBeta: 0,
         colors: {},
+        zoneConfig: {},
     };
     const configPath = path.join(os.homedir(), '.claude', 'statusline.conf');
 
@@ -403,29 +435,219 @@ function readConfig() {
             if (!fs.existsSync(configDir)) {
                 fs.mkdirSync(configDir, { recursive: true });
             }
-            const defaultConfig = `# Autocompact setting - sync with Claude Code's /config
-autocompact=true
-
-# Token display format
+            const defaultConfig = `\
+# ============================================================================
+# cc-context-stats — statusline configuration
+# ============================================================================
+#
+# Copy this file to:   ~/.claude/statusline.conf
+# Windows:             %USERPROFILE%\\.claude\\statusline.conf
+#
+# Full reference:
+#   https://github.com/luongnv89/cc-context-stats/blob/main/docs/configuration.md
+#
+# Format:
+#   - key=value (no spaces around '=')
+#   - Lines starting with '#' are comments
+#   - Unrecognized keys are silently ignored
+#   - Missing or invalid values fall back to built-in defaults
+#
+# ============================================================================
+
+
+# ─── Display Settings ───────────────────────────────────────────────────────
+#
+# These boolean flags control which elements appear in the statusline.
+# Any value other than "false" (case-insensitive) is treated as true.
+
+# Autocompact buffer display.
+# When true, 22.5% of the context window is reserved for Claude Code's
+# autocompact feature. This affects the "free tokens" calculation.
+# Must match your Claude Code setting — check with: /config
+#   true  -> shows [AC:45k] buffer in statusline
+#   false -> shows [AC:off]
+autocompact=false
+
+# Token display format.
+#   true  = exact count with commas (e.g., 64,000 free)
+#   false = abbreviated with suffix  (e.g., 64.0k free)
+# Also affects the delta display (+2,500 vs +2.5k).
 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 token delta since last refresh (e.g., +2,500).
+# Displays how many tokens were consumed since the previous statusline update.
+# Requires file I/O on every refresh to read the previous state.
+# Disable if you want to reduce disk overhead.
 show_delta=true
 
-# Show session_id in status line
+# Show the session ID at the end of the statusline.
+# Useful when running multiple Claude Code instances to identify sessions.
+# Double-click in terminal to select and copy.
 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
+# Show input/output token breakdown.
+# Reserved for future use — currently read but not displayed.
+show_io_tokens=true
+
+# Disable rotating text and icon animations for accessibility.
+#   false = animations enabled (default)
+#   true  = static display, no motion
+reduced_motion=false
+
+
+# ─── Model Intelligence (MI) ────────────────────────────────────────────────
+#
+# MI measures how effectively the model uses its context window. The score
+# ranges from 0.000 (fully degraded) to 1.000 (optimal). As context fills,
+# MI degrades following a model-specific curve.
+
+# Show the MI score in the statusline (e.g., MI:0.918).
+# When enabled, also requires state file I/O for tracking.
+#   false = MI score hidden (default)
+#   true  = MI score visible
+show_mi=false
+
+# Override the MI degradation curve beta for all models.
+# Each model has a built-in profile that controls how quickly MI degrades:
+#   opus   = 1.8  (retains quality longest, steep drop near end)
+#   sonnet = 1.5  (moderate degradation)
+#   haiku  = 1.2  (degrades earliest)
+# Set to 0 to use the model-specific profile (recommended).
+# Set a positive value (e.g., 1.5) to override for all models.
+mi_curve_beta=0
+
+
+# ─── Zone Threshold Overrides ───────────────────────────────────────────────
+#
+# Zones indicate how much context pressure your session is under:
+#   Plan   (P) = plenty of room, ideal for planning and exploration
+#   Code   (C) = normal coding zone, context is filling but healthy
+#   Dump   (D) = getting full, consider wrapping up or starting fresh
+#   ExDump (X) = critical, autocompact may trigger, quality degrading
+#   Dead   (Z) = context exhausted, start a new session
+#
+# There are two threshold sets: one for large models (1M+ context) using
+# absolute token counts, and one for standard models using ratios (0-1).
+#
+# Uncomment and set a positive value to override the built-in defaults.
+# Invalid values (negative, non-numeric, ratios outside 0-1) are ignored
+# with a warning to stderr.
+
+# Context windows >= this value use 1M-class thresholds (token count).
+# Models below this threshold use the standard ratio-based zones.
+# large_model_threshold=500000
+
+# --- 1M-Class Models (context >= large_model_threshold) ---
+# Values are absolute token counts for zone boundaries (tokens used).
+# zone_1m_plan_max=70000       # Plan -> Code boundary
+# zone_1m_code_max=100000      # Code -> Dump boundary
+# zone_1m_dump_max=250000      # Dump -> ExDump boundary
+# zone_1m_xdump_max=275000     # ExDump -> Dead boundary
+
+# --- Standard Models (context < large_model_threshold) ---
+# Ratios are 0-1 fractions of the total context window.
+# zone_std_dump_ratio=0.40     # Dump zone starts at 40% utilization
+# zone_std_warn_buffer=30000   # Show warning this many tokens before dump zone
+# zone_std_hard_limit=0.70     # Hard limit at 70% utilization
+# zone_std_dead_ratio=0.75     # Dead zone starts at 75% utilization
+
+
+# ─── Base Color Slots ───────────────────────────────────────────────────────
+#
+# Override the 6 base palette colors used for MI-based traffic-light coloring
+# and as fallbacks for per-property colors (see next section).
+#
+# Accepts named colors or hex codes (#rrggbb).
+#
+# Named colors (18 available):
+#   Standard:  black, red, green, yellow, blue, magenta, cyan, white
+#   Bright:    bright_black, bright_red, bright_green, bright_yellow,
+#              bright_blue, bright_magenta, bright_cyan, bright_white
+#   Special:   bold_white, dim
+#
+# Hex colors: any #rrggbb value (requires 24-bit color terminal support)
+#
+# Unrecognized values are ignored with a warning to stderr.
+
+# Traffic-light colors — used for MI score and context zone indicators.
+# Colors are determined by BOTH MI score and context utilization:
+#   color_green  -> MI >= 0.90 AND context < 40% (model operating well)
+#   color_yellow -> MI in (0.80, 0.90) OR context in [40%, 80%) (pressure building)
+#   color_red    -> MI <= 0.80 OR context >= 80% (significant degradation)
+color_green=#7dcfff
+color_yellow=#e0af68
+color_red=#f7768e
+
+# Legacy element fallback colors:
+#   color_blue    -> fallback for project name (if color_project_name not set)
+#   color_magenta -> fallback for branch name (if color_branch_name not set)
+#   color_cyan    -> git change-count brackets (e.g., [3])
+color_blue=#7aa2f7
+color_magenta=#bb9af7
+color_cyan=#2ac3de
+
+
+# ─── Per-Property Colors ────────────────────────────────────────────────────
+#
+# Override individual statusline elements. These take precedence over
+# base color slots above.
+#
+# Fallback chain: per-property key -> base color slot -> built-in default
+#
+# For example, if color_project_name is not set, it falls back to color_blue
+# (if set), then to the built-in cyan.
+
+# Context tokens remaining — the most critical info.
+# When not set, uses zone traffic-light color (green/yellow/red) automatically.
+# Set explicitly to use a fixed color regardless of zone.
+# color_context_length=bold_white
+
+# Project directory name (e.g., "my-project").
+color_project_name=bright_cyan
+
+# Git branch name (e.g., "main").
+color_branch_name=bright_magenta
+
+# MI score display (e.g., "MI:0.918").
+# When not set, uses MI-based traffic-light color automatically.
+color_mi_score=#ff9e64
+
+# Zone indicator label (e.g., "Plan", "Code", "Dump").
+# When not set, uses zone traffic-light color automatically.
+# color_zone=bright_green
+
+# Structural elements: model name, token delta, session ID.
+# "dim" makes these visually recede so primary info stands out.
+color_separator=dim
+
+
+# ─── Statusline Layout Reference ────────────────────────────────────────────
+#
+# The statusline elements are displayed in this order (highest priority first):
+#
+#   project_name | branch [changes] | tokens_free (%) | Zone | MI:score | +delta | Model | session_id
+#
+# Example output:
+#   my-project | main [3] | 64,000 free (32.0%) | Code | MI:0.918 | +2,500 | Opus 4.6 | abc-123
+#
+# If the terminal is too narrow, lower-priority elements are dropped:
+#   1. session_id   (dropped first)
+#   2. model name
+#   3. token delta
+#   4. MI score
+#   5. zone indicator
+#   6. context info
+#   7. git info
+#   8. project name  (always shown, never dropped)
 `;
             fs.writeFileSync(configPath, defaultConfig);
         } catch (e) {
             process.stderr.write(`[statusline] warning: failed to create config: ${e.message}\n`);
+            return config;
         }
+    }
+
+    if (!fs.existsSync(configPath)) {
         return config;
     }
 
@@ -464,6 +686,24 @@ show_session=true
                 if (ansi) {
                     config.colors[COLOR_CONFIG_KEYS[keyTrimmed]] = ansi;
                 }
+            } else if (ZONE_INT_KEYS.has(keyTrimmed)) {
+                const v = parseInt(rawValue, 10);
+                if (!isNaN(v) && v > 0) {
+                    config.zoneConfig[keyTrimmed] = v;
+                } else {
+                    process.stderr.write(
+                        `[statusline] warning: ${keyTrimmed} must be a positive integer, ignoring '${rawValue}'\n`
+                    );
+                }
+            } else if (ZONE_FLOAT_KEYS.has(keyTrimmed)) {
+                const v = parseFloat(rawValue);
+                if (!isNaN(v) && v > 0 && v < 1) {
+                    config.zoneConfig[keyTrimmed] = v;
+                } else {
+                    process.stderr.write(
+                        `[statusline] warning: ${keyTrimmed} must be between 0 and 1, ignoring '${rawValue}'\n`
+                    );
+                }
             }
         }
     } catch (e) {
@@ -572,7 +812,7 @@ process.stdin.on('end', () => {
             : `${(freeTokens / 1000).toFixed(1)}k`;
 
         // Zone indicator — determines color for both context info and zone label
-        const zoneResult = getContextZone(usedTokens, totalSize);
+        const zoneResult = getContextZone(usedTokens, totalSize, config.zoneConfig);
         const zoneAnsi = zoneAnsiColor(zoneResult.colorName);
 
         // Context info uses zone color (traffic-light), with per-property override