cc-context-stats 1.6.1 → 1.7.0

package/docs/installation.md

@@ -5,32 +5,62 @@
 ### One-Line Install (Recommended)
 
 ```bash
-curl -fsSL https://raw.githubusercontent.com/luongnv89/claude-statusline/main/install.sh | bash
+curl -fsSL https://raw.githubusercontent.com/luongnv89/cc-context-stats/main/install.sh | bash
 ```
 
-This downloads and runs the installer directly from GitHub. In non-interactive mode, it installs the **full** statusline script by default.
+This downloads and runs the installer directly from GitHub. It installs the **full** statusline script and the `context-stats` CLI tool.
 
-### Interactive Install
+### NPM (Recommended for Node.js users)
 
-To choose a different script variant:
+```bash
+npm install -g cc-context-stats
+```
+
+Or with yarn:
+
+```bash
+yarn global add cc-context-stats
+```
+
+After installation, add to `~/.claude/settings.json`:
+
+```json
+{
+  "statusLine": {
+    "type": "command",
+    "command": "claude-statusline"
+  }
+}
+```
+
+### Python (Recommended for Python users)
 
 ```bash
-bash <(curl -fsSL https://raw.githubusercontent.com/luongnv89/claude-statusline/main/install.sh)
+pip install cc-context-stats
 ```
 
-This runs the installer interactively, allowing you to select from:
+Or with uv:
 
-1. minimal - Simple: model + directory
-2. git - With git branch info
-3. full - Full featured with context usage (recommended)
-4. python - Python version (full featured)
-5. node - Node.js version (full featured)
+```bash
+uv pip install cc-context-stats
+```
+
+After installation, add to `~/.claude/settings.json`:
+
+```json
+{
+  "statusLine": {
+    "type": "command",
+    "command": "claude-statusline"
+  }
+}
+```
 
 ### Install from Source
 
 ```bash
 git clone https://github.com/luongnv89/cc-context-stats.git
-cd claude-statusline
+cd cc-context-stats
 ./install.sh
 ```
 
@@ -46,14 +76,22 @@ The installer will:
 Use the Python or Node.js version (no `jq` required):
 
 ```powershell
+# Python (via pip)
+pip install cc-context-stats
+
+# Or manually copy the script
 git clone https://github.com/luongnv89/cc-context-stats.git
-copy claude-statusline\scripts\statusline.py %USERPROFILE%\.claude\statusline.py
+copy cc-context-stats\scripts\statusline.py %USERPROFILE%\.claude\statusline.py
 ```
 
 Or with Node.js:
 
 ```powershell
-copy claude-statusline\scripts\statusline.js %USERPROFILE%\.claude\statusline.js
+# Node.js (via npm)
+npm install -g cc-context-stats
+
+# Or manually copy the script
+copy cc-context-stats\scripts\statusline.js %USERPROFILE%\.claude\statusline.js
 ```
 
 ## Manual Installation
@@ -93,6 +131,19 @@ Add to your Claude Code settings:
 - macOS/Linux: `~/.claude/settings.json`
 - Windows: `%USERPROFILE%\.claude\settings.json`
 
+### pip / npm Install
+
+If you installed via `pip install cc-context-stats` or `npm install -g cc-context-stats`:
+
+```json
+{
+  "statusLine": {
+    "type": "command",
+    "command": "claude-statusline"
+  }
+}
+```
+
 ### Bash (macOS/Linux)
 
 ```json
@@ -104,7 +155,7 @@ Add to your Claude Code settings:
 }
 ```
 
-### Python (All Platforms)
+### Python (Manual Copy)
 
 ```json
 {
@@ -126,7 +177,7 @@ Windows:
 }
 ```
 
-### Node.js (All Platforms)
+### Node.js (Manual Copy)
 
 ```json
 {
@@ -153,24 +204,24 @@ Windows:
 ### macOS
 
 ```bash
-brew install jq
+brew install jq   # Only needed for bash scripts
 ```
 
 ### Linux (Debian/Ubuntu)
 
 ```bash
-sudo apt install jq
+sudo apt install jq   # Only needed for bash scripts
 ```
 
 ### Linux (Fedora/RHEL)
 
 ```bash
-sudo dnf install jq
+sudo dnf install jq   # Only needed for bash scripts
 ```
 
 ### Windows
 
-No additional requirements for Python/Node.js scripts.
+No additional requirements for Python/Node.js scripts (via pip or npm).
 
 For bash scripts via WSL:
 
@@ -180,12 +231,21 @@ sudo apt install jq
 
 ## Verify Installation
 
-Test your statusline script:
+Test your statusline:
 
 ```bash
-# macOS/Linux
+# If installed via pip or npm
+echo '{"model":{"display_name":"Test"}}' | claude-statusline
+
+# Bash script (macOS/Linux)
 echo '{"model":{"display_name":"Test"}}' | ~/.claude/statusline.sh
 
+# Python script (manual copy)
+echo '{"model":{"display_name":"Test"}}' | python3 ~/.claude/statusline.py
+
+# Node.js script (manual copy)
+echo '{"model":{"display_name":"Test"}}' | node ~/.claude/statusline.js
+
 # Windows (Python)
 echo {"model":{"display_name":"Test"}} | python %USERPROFILE%\.claude\statusline.py
 ```

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.1",
+  "version": "1.7.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.1"
+version = "1.7.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.js

@@ -24,7 +24,7 @@
  *   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
+ *   workspace_project_dir,context_window_size
  */
 
 const { execSync } = require('child_process');
@@ -72,7 +72,7 @@ function maybeRotateStateFile(stateFile) {
     }
 }
 
-// ANSI Colors
+// ANSI Colors (defaults, overridable via config)
 const BLUE = '\x1b[0;34m';
 const MAGENTA = '\x1b[0;35m';
 const CYAN = '\x1b[0;36m';
@@ -82,6 +82,54 @@ const RED = '\x1b[0;31m';
 const DIM = '\x1b[2m';
 const RESET = '\x1b[0m';
 
+// Named colors for config parsing
+const COLOR_NAMES = {
+    black: '\x1b[0;30m',
+    red: '\x1b[0;31m',
+    green: '\x1b[0;32m',
+    yellow: '\x1b[0;33m',
+    blue: '\x1b[0;34m',
+    magenta: '\x1b[0;35m',
+    cyan: '\x1b[0;36m',
+    white: '\x1b[0;37m',
+    bright_black: '\x1b[0;90m',
+    bright_red: '\x1b[0;91m',
+    bright_green: '\x1b[0;92m',
+    bright_yellow: '\x1b[0;93m',
+    bright_blue: '\x1b[0;94m',
+    bright_magenta: '\x1b[0;95m',
+    bright_cyan: '\x1b[0;96m',
+    bright_white: '\x1b[0;97m',
+};
+
+/**
+ * Parse a color name or #rrggbb hex into an ANSI escape code.
+ * Returns null if unrecognized.
+ */
+function parseColor(value) {
+    value = value.trim().toLowerCase();
+    if (COLOR_NAMES[value]) {
+        return COLOR_NAMES[value];
+    }
+    const m = value.match(/^#([0-9a-f]{6})$/);
+    if (m) {
+        const r = parseInt(m[1].slice(0, 2), 16);
+        const g = parseInt(m[1].slice(2, 4), 16);
+        const b = parseInt(m[1].slice(4, 6), 16);
+        return `\x1b[38;2;${r};${g};${b}m`;
+    }
+    return null;
+}
+
+const COLOR_CONFIG_KEYS = {
+    color_green: 'green',
+    color_yellow: 'yellow',
+    color_red: 'red',
+    color_blue: 'blue',
+    color_magenta: 'magenta',
+    color_cyan: 'cyan',
+};
+
 /**
  * Return the visible width of a string after stripping ANSI escape sequences.
  */
@@ -125,7 +173,9 @@ function fitToWidth(parts, maxWidth) {
     return result;
 }
 
-function getGitInfo(projectDir) {
+function getGitInfo(projectDir, magentaColor, cyanColor) {
+    const mg = magentaColor || MAGENTA;
+    const cy = cyanColor || CYAN;
     const gitDir = path.join(projectDir, '.git');
     if (!fs.existsSync(gitDir) || !fs.statSync(gitDir).isDirectory()) {
         return '';
@@ -154,9 +204,9 @@ function getGitInfo(projectDir) {
         const changes = status.split('\n').filter(l => l.trim()).length;
 
         if (changes > 0) {
-            return ` | ${MAGENTA}${branch}${RESET} ${CYAN}[${changes}]${RESET}`;
+            return ` | ${mg}${branch}${RESET} ${cy}[${changes}]${RESET}`;
         }
-        return ` | ${MAGENTA}${branch}${RESET}`;
+        return ` | ${mg}${branch}${RESET}`;
     } catch {
         return '';
     }
@@ -170,6 +220,7 @@ function readConfig() {
         showSession: true,
         showIoTokens: true,
         reducedMotion: false,
+        colors: {},
     };
     const configPath = path.join(os.homedir(), '.claude', 'statusline.conf');
 
@@ -192,6 +243,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
 `;
             fs.writeFileSync(configPath, defaultConfig);
         } catch (e) {
@@ -207,9 +264,10 @@ show_session=true
             if (trimmed.startsWith('#') || !trimmed.includes('=')) {
                 continue;
             }
-            const [key, value] = trimmed.split('=', 2);
-            const keyTrimmed = key.trim();
-            const valueTrimmed = value.trim().toLowerCase();
+            const eqIdx = trimmed.indexOf('=');
+            const keyTrimmed = trimmed.slice(0, eqIdx).trim();
+            const rawValue = trimmed.slice(eqIdx + 1).trim();
+            const valueTrimmed = rawValue.toLowerCase();
             if (keyTrimmed === 'autocompact') {
                 config.autocompact = valueTrimmed !== 'false';
             } else if (keyTrimmed === 'token_detail') {
@@ -222,6 +280,11 @@ show_session=true
                 config.showIoTokens = valueTrimmed !== 'false';
             } else if (keyTrimmed === 'reduced_motion') {
                 config.reducedMotion = valueTrimmed !== 'false';
+            } else if (COLOR_CONFIG_KEYS[keyTrimmed]) {
+                const ansi = parseColor(rawValue);
+                if (ansi) {
+                    config.colors[COLOR_CONFIG_KEYS[keyTrimmed]] = ansi;
+                }
             }
         }
     } catch (e) {
@@ -250,9 +313,6 @@ process.stdin.on('end', () => {
     const model = data.model?.display_name || 'Claude';
     const dirName = path.basename(cwd) || '~';
 
-    // Git info
-    const gitInfo = getGitInfo(projectDir);
-
     // Read settings from config file
     const config = readConfig();
     const autocompactEnabled = config.autocompact;
@@ -261,6 +321,18 @@ process.stdin.on('end', () => {
     const showSession = config.showSession;
     // Note: showIoTokens setting is read but not yet implemented
 
+    // Apply color overrides from config
+    const c = config.colors || {};
+    const cGreen = c.green || GREEN;
+    const cYellow = c.yellow || YELLOW;
+    const cRed = c.red || RED;
+    const cBlue = c.blue || BLUE;
+    const cMagenta = c.magenta || MAGENTA;
+    const cCyan = c.cyan || CYAN;
+
+    // Git info (pass configurable colors)
+    const gitInfo = getGitInfo(projectDir, cMagenta, cCyan);
+
     // Extract session_id once for reuse
     const sessionId = data.session_id;
 
@@ -320,11 +392,11 @@ process.stdin.on('end', () => {
         // Color based on free percentage
         let ctxColor;
         if (freePctInt > 50) {
-            ctxColor = GREEN;
+            ctxColor = cGreen;
         } else if (freePctInt > 25) {
-            ctxColor = YELLOW;
+            ctxColor = cYellow;
         } else {
-            ctxColor = RED;
+            ctxColor = cRed;
         }
 
         contextInfo = ` | ${ctxColor}${freeDisplay} free (${freePct.toFixed(1)}%)${RESET}`;
@@ -438,7 +510,7 @@ process.stdin.on('end', () => {
     }
 
     // Output: [Model] dir | branch [n] | free (%) [+delta] [AC] session
-    const base = `${DIM}[${model}]${RESET} ${BLUE}${dirName}${RESET}`;
+    const base = `${DIM}[${model}]${RESET} ${cBlue}${dirName}${RESET}`;
     const maxWidth = getTerminalWidth();
     const parts = [base, gitInfo, contextInfo, deltaInfo, acInfo, sessionInfo];
     console.log(fitToWidth(parts, maxWidth));