cc-context-stats 1.3.0 → 1.5.1

package/.claude/settings.local.json

@@ -79,7 +79,42 @@
       "Skill(pre-commit)",
       "Bash(npm run format:check:*)",
       "Bash(bash:*)",
-      "Bash(git tag:*)"
+      "Bash(git tag:*)",
+      "Bash(git pull:*)",
+      "Bash(git rebase:*)",
+      "Bash(git stash:*)",
+      "Bash(npm whoami:*)",
+      "Bash(git filter-branch:*)",
+      "Bash(gh issue view:*)",
+      "Bash(head:*)",
+      "Bash(/Users/montimage/buildspace/luongnv89/cc-context-stats/.venv/bin/python -m pytest:*)",
+      "Bash(/Users/montimage/buildspace/luongnv89/cc-context-stats/.venv/bin/python3 -m pytest:*)",
+      "Bash(/Users/montimage/buildspace/luongnv89/cc-context-stats/.venv/bin/python3.14 -m pytest:*)",
+      "Bash(/Users/montimage/buildspace/luongnv89/cc-context-stats/venv/bin/python3 -m pytest:*)",
+      "Bash(/Users/montimage/buildspace/luongnv89/cc-context-stats/venv/bin/pip install:*)",
+      "Bash(.test_venv/bin/pip install:*)",
+      "Bash(.test_venv/bin/python3.14 -m pytest:*)",
+      "Bash(.venv/bin/pip install:*)",
+      "Bash(.venv/bin/python3.14 -m pytest:*)",
+      "Bash(.venv/bin/context-stats:*)",
+      "Bash(npx jest:*)",
+      "Bash(gh workflow:*)",
+      "Bash(git -C /Users/montimage/buildspace/luongnv89/cc-context-stats status)",
+      "Bash(git -C /Users/montimage/buildspace/luongnv89/cc-context-stats diff)",
+      "Bash(git -C /Users/montimage/buildspace/luongnv89/cc-context-stats log --oneline -5)",
+      "Bash(git -C /Users/montimage/buildspace/luongnv89/cc-context-stats add tests/python/test_statusline.py)",
+      "Bash(git -C /Users/montimage/buildspace/luongnv89/cc-context-stats commit -m \"$\\(cat <<''EOF''\nfix: resolve Windows CI failures caused by Unicode encoding in Python tests\n\nSet PYTHONUTF8=1 for subprocess calls and use explicit utf-8 encoding\nfor read_text\\(\\) to handle Unicode characters \\(emojis/icons\\) on Windows\nwhere the default cp1252 encoding cannot decode them.\nEOF\n\\)\")",
+      "Bash(git -C /Users/montimage/buildspace/luongnv89/cc-context-stats push)",
+      "Bash(COLUMNS=200 cat tests/fixtures/json/valid_full.json | scripts/statusline-full.sh 2>&1)",
+      "Bash(export COLUMNS=200 && cat tests/fixtures/json/valid_full.json | scripts/statusline-full.sh 2>&1)",
+      "Bash(gh release:*)",
+      "Read(//Users/montimage/.claude/**)",
+      "Bash(git checkout:*)",
+      "Bash(npm publish:*)",
+      "Bash(npm view:*)",
+      "WebSearch",
+      "Bash(COLUMNS=120 python3 -c \"import shutil; print\\(shutil.get_terminal_size\\(\\).columns\\)\")",
+      "Bash(COLUMNS=80 python3 -c \"import shutil; print\\(shutil.get_terminal_size\\(\\).columns\\)\")"
     ]
   }
 }

package/.github/workflows/ci.yml

@@ -110,10 +110,12 @@ jobs:
           cache-dependency-path: 'requirements-dev.txt'
 
       - name: Install dependencies
-        run: pip install -r requirements-dev.txt
+        run: |
+          pip install -r requirements-dev.txt
+          pip install -e .
 
       - name: Run pytest with coverage
-        run: pytest tests/python/ -v --cov=scripts --cov-report=xml --cov-report=term
+        run: pytest tests/python/ -v --cov=scripts --cov=src --cov-report=xml --cov-report=term
 
       - name: Upload coverage to Codecov
         if: matrix.os == 'ubuntu-latest' && matrix.python-version == '3.11'

package/.github/workflows/release.yml

@@ -69,7 +69,9 @@ jobs:
         run: sudo apt-get update && sudo apt-get install -y jq bats
 
       - name: Install Python dependencies
-        run: pip install -r requirements-dev.txt
+        run: |
+          pip install -r requirements-dev.txt
+          pip install -e .
 
       - name: Install Node.js dependencies
         run: npm ci

package/CHANGELOG.md

@@ -7,6 +7,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- **NPM Package** - `cc-context-stats` now available on npm for JavaScript/Node.js environments
+  - Install via `npm install -g cc-context-stats` or `yarn global add cc-context-stats`
+  - Provides same functionality as Python package for Node.js users
+- **Enhanced Documentation** - Updated README with npm installation instructions and badges
+
+### Changed
+
+- **Package Metadata** - Synchronized package descriptions across npm and PyPI for consistency
+- **Keywords** - Aligned keywords across npm and Python packages for better discoverability
+- **Installation Section** - Moved shell script installation to the top of README as the recommended method
+- **Install Script Documentation** - Enhanced `install.sh` with comprehensive header documentation including:
+  - Features overview (real-time monitoring, live dashboard, zone detection)
+  - Requirements (curl, jq)
+  - Installation destinations and file descriptions
+
 ## [1.2.0] - 2025-01-08
 
 ### Added

package/README.md

@@ -1,9 +1,18 @@
-# Claude Code Context Stats
+<div align="center">
+  <img src="assets/logo/logo-full.svg" alt="cc-context-stats" width="320"/>
+
+  <h3>Know your zone. Ship with confidence.</h3>
+
+  <p>Real-time context monitoring for Claude Code — so you always know when you're sharp and when to wrap up.</p>
 
 [![PyPI version](https://badge.fury.io/py/cc-context-stats.svg)](https://pypi.org/project/cc-context-stats/)
-[![Downloads](https://img.shields.io/pypi/dm/cc-context-stats)](https://pypi.org/project/cc-context-stats/)
+[![npm version](https://badge.fury.io/js/cc-context-stats.svg)](https://www.npmjs.com/package/cc-context-stats)
+[![PyPI Downloads](https://img.shields.io/pypi/dm/cc-context-stats)](https://pypi.org/project/cc-context-stats/)
+[![npm Downloads](https://img.shields.io/npm/dm/cc-context-stats)](https://www.npmjs.com/package/cc-context-stats)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
+</div>
+
 **Never run out of context unexpectedly** - monitor your session context in real-time.
 
 ![Context Stats](images/context-status-dumbzone.png)
@@ -27,6 +36,28 @@ When working with Claude Code on complex tasks, you can easily burn through your
 
 ## Installation
 
+### Shell Script
+
+For the quickest setup:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/luongnv89/cc-context-stats/main/install.sh | bash
+```
+
+### NPM
+
+```bash
+npm install -g cc-context-stats
+```
+
+Or with yarn:
+
+```bash
+yarn global add cc-context-stats
+```
+
+### Python
+
 ```bash
 pip install cc-context-stats
 ```
@@ -137,14 +168,6 @@ show_session=true   # Show session ID
 autocompact=true    # Show autocompact buffer indicator
 ```
 
-## Shell Script Installation
-
-For users who prefer shell scripts:
-
-```bash
-curl -fsSL https://raw.githubusercontent.com/luongnv89/cc-context-stats/main/install.sh | bash
-```
-
 ## How It Works
 
 Context Stats hooks into Claude Code's state files to track token usage across your sessions. Data is stored locally in `~/.claude/statusline/` and never sent anywhere.
@@ -171,7 +194,6 @@ The `claude-statusline` command still works. The main change is `token-graph` is
 ## Related
 
 - [Claude Code Documentation](https://docs.anthropic.com/en/docs/claude-code)
-- [Dex Horthy on Context Windows](https://twitter.com/daborhty) - The "dumb zone" concept
 - [Blog: Building this project](https://medium.com/@luongnv89/closing-the-gap-between-mvp-and-production-with-feature-dev-an-official-plugin-from-anthropic-444e2f00a0ad)
 
 ## License

package/RELEASE_NOTES.md

@@ -0,0 +1,10 @@
+## v1.5.1 — 2026-03-11
+
+### Bug Fixes
+- **Fix session ID disappearing from statusline** — Claude Code runs statusline scripts as piped subprocesses with no real TTY, causing terminal width detection to always return 80 columns. This made `fit_to_width()` drop lower-priority parts like session ID even when the real terminal had plenty of space. Now uses 200 columns as default when no TTY is detected; Claude Code's own UI handles overflow.
+- **Fix CI failures** — Resolve ESLint, Python 3.9 compatibility, and release workflow issues
+
+### Other Changes
+- Update logo SVG assets
+
+**Full Changelog**: https://github.com/luongnv89/cc-context-stats/compare/v1.5.0...v1.5.1

package/assets/logo/favicon.svg

@@ -0,0 +1,19 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16" width="16" height="16">
+  <defs>
+    <linearGradient id="fav-grad" x1="0%" y1="0%" x2="100%" y2="0%">
+      <stop offset="0%" stop-color="#22C55E"/>
+      <stop offset="50%" stop-color="#E9AB34"/>
+      <stop offset="100%" stop-color="#EF4444"/>
+    </linearGradient>
+  </defs>
+
+  <!-- Background -->
+  <rect width="16" height="16" rx="3" fill="#1A1A1A"/>
+
+  <!-- Simplified wave for 16x16 -->
+  <path d="M 2 12 C 4 12, 5 10, 7 8 C 9 6, 10 4, 12 3 C 13 2, 14 3, 14 2.5"
+        stroke="url(#fav-grad)" stroke-width="1.5" fill="none" stroke-linecap="round"/>
+
+  <!-- Dot -->
+  <circle cx="12" cy="3" r="1.5" fill="#E9AB34"/>
+</svg>

package/assets/logo/logo-black.svg

@@ -0,0 +1,24 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 360 72" width="360" height="72">
+  <!-- Black version for light backgrounds — no background rectangle -->
+
+  <!-- Mark: Context wave -->
+  <g transform="translate(8, 4)">
+    <path d="M 10 48 C 16 48, 18 42, 22 40 C 26 38, 28 36, 32 32 C 36 28, 38 22, 42 18 C 46 14, 50 16, 54 14"
+          stroke="#1A1A1A" stroke-width="3.5" fill="none" stroke-linecap="round" stroke-linejoin="round"/>
+    <path d="M 10 52 C 16 52, 18 46, 22 44 C 26 42, 28 40, 32 36 C 36 32, 38 26, 42 22 C 46 18, 50 20, 54 18"
+          stroke="#1A1A1A" stroke-width="1.5" fill="none" stroke-linecap="round" opacity="0.25"/>
+    <circle cx="42" cy="18" r="3.5" fill="#1A1A1A"/>
+    <circle cx="42" cy="18" r="6" fill="#1A1A1A" opacity="0.12"/>
+    <line x1="10" y1="54" x2="54" y2="54" stroke="#1A1A1A" stroke-width="1" stroke-linecap="round" opacity="0.3"/>
+  </g>
+
+  <!-- Divider -->
+  <line x1="76" y1="16" x2="76" y2="56" stroke="#1A1A1A" stroke-width="1" opacity="0.2"/>
+
+  <!-- Wordmark -->
+  <text x="90" y="35" font-family="'SF Mono', 'JetBrains Mono', 'Fira Code', 'Cascadia Code', monospace" font-size="22" font-weight="700" fill="#1A1A1A" letter-spacing="-0.3">cc-context</text>
+  <text x="90" y="55" font-family="'SF Mono', 'JetBrains Mono', 'Fira Code', 'Cascadia Code', monospace" font-size="15" font-weight="500" fill="#1A1A1A" letter-spacing="3" opacity="0.6">stats</text>
+
+  <!-- Right accent bar -->
+  <rect x="348" y="20" width="2" height="32" rx="1" fill="#1A1A1A" opacity="0.35"/>
+</svg>

package/assets/logo/logo-full.svg

@@ -0,0 +1,40 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 360 72" width="360" height="72">
+  <defs>
+    <linearGradient id="full-wave-grad" x1="0%" y1="0%" x2="100%" y2="0%">
+      <stop offset="0%" stop-color="#22C55E"/>
+      <stop offset="50%" stop-color="#E9AB34"/>
+      <stop offset="100%" stop-color="#EF4444"/>
+    </linearGradient>
+  </defs>
+
+  <!-- Background pill -->
+  <rect width="360" height="72" rx="14" fill="#1A1A1A"/>
+
+  <!-- Mark: Context wave in left area -->
+  <g transform="translate(8, 4)">
+    <!-- Context wave -->
+    <path d="M 10 48 C 16 48, 18 42, 22 40 C 26 38, 28 36, 32 32 C 36 28, 38 22, 42 18 C 46 14, 50 16, 54 14"
+          stroke="url(#full-wave-grad)" stroke-width="3.5" fill="none" stroke-linecap="round" stroke-linejoin="round"/>
+
+    <!-- Echo line -->
+    <path d="M 10 52 C 16 52, 18 46, 22 44 C 26 42, 28 40, 32 36 C 36 32, 38 26, 42 22 C 46 18, 50 20, 54 18"
+          stroke="url(#full-wave-grad)" stroke-width="1.5" fill="none" stroke-linecap="round" opacity="0.3"/>
+
+    <!-- Cursor dot -->
+    <circle cx="42" cy="18" r="3.5" fill="#E9AB34"/>
+    <circle cx="42" cy="18" r="6" fill="#E9AB34" opacity="0.15"/>
+
+    <!-- Baseline -->
+    <line x1="10" y1="54" x2="54" y2="54" stroke="#8B7D6B" stroke-width="1" stroke-linecap="round" opacity="0.4"/>
+  </g>
+
+  <!-- Divider -->
+  <line x1="76" y1="16" x2="76" y2="56" stroke="#8B7D6B" stroke-width="1" opacity="0.25"/>
+
+  <!-- Wordmark -->
+  <text x="90" y="35" font-family="'SF Mono', 'JetBrains Mono', 'Fira Code', 'Cascadia Code', monospace" font-size="22" font-weight="700" fill="#FFFFFF" letter-spacing="-0.3">cc-context</text>
+  <text x="90" y="55" font-family="'SF Mono', 'JetBrains Mono', 'Fira Code', 'Cascadia Code', monospace" font-size="15" font-weight="500" fill="#E9AB34" letter-spacing="3">stats</text>
+
+  <!-- Right accent bar -->
+  <rect x="348" y="20" width="2" height="32" rx="1" fill="#E9AB34" opacity="0.5"/>
+</svg>

package/assets/logo/logo-icon.svg

@@ -0,0 +1,27 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512" width="512" height="512">
+  <defs>
+    <linearGradient id="icon-wave-grad" x1="0%" y1="0%" x2="100%" y2="0%">
+      <stop offset="0%" stop-color="#22C55E"/>
+      <stop offset="50%" stop-color="#E9AB34"/>
+      <stop offset="100%" stop-color="#EF4444"/>
+    </linearGradient>
+  </defs>
+
+  <!-- Background -->
+  <rect width="512" height="512" rx="96" fill="#1A1A1A"/>
+
+  <!-- Context wave (scaled up) -->
+  <path d="M 96 376 C 144 376, 160 328, 192 312 C 224 296, 240 280, 272 248 C 304 216, 320 168, 352 136 C 384 104, 400 120, 432 104"
+        stroke="url(#icon-wave-grad)" stroke-width="24" fill="none" stroke-linecap="round" stroke-linejoin="round"/>
+
+  <!-- Echo line -->
+  <path d="M 96 408 C 144 408, 160 360, 192 344 C 224 328, 240 312, 272 280 C 304 248, 320 200, 352 168 C 384 136, 400 152, 432 136"
+        stroke="url(#icon-wave-grad)" stroke-width="10" fill="none" stroke-linecap="round" opacity="0.25"/>
+
+  <!-- Cursor dot -->
+  <circle cx="352" cy="136" r="28" fill="#E9AB34"/>
+  <circle cx="352" cy="136" r="48" fill="#E9AB34" opacity="0.12"/>
+
+  <!-- Baseline -->
+  <line x1="96" y1="424" x2="432" y2="424" stroke="#8B7D6B" stroke-width="6" stroke-linecap="round" opacity="0.35"/>
+</svg>

package/assets/logo/logo-mark.svg

@@ -0,0 +1,28 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" width="64" height="64">
+  <defs>
+    <linearGradient id="wave-grad" x1="0%" y1="0%" x2="100%" y2="0%">
+      <stop offset="0%" stop-color="#22C55E"/>
+      <stop offset="50%" stop-color="#E9AB34"/>
+      <stop offset="100%" stop-color="#EF4444"/>
+    </linearGradient>
+  </defs>
+
+  <!-- Background -->
+  <rect width="64" height="64" rx="14" fill="#1A1A1A"/>
+
+  <!-- Context wave: a flowing curve rising from left (low usage) to right (high usage) -->
+  <!-- This represents the context growth graph - the core concept of the tool -->
+  <path d="M 10 48 C 16 48, 18 42, 22 40 C 26 38, 28 36, 32 32 C 36 28, 38 22, 42 18 C 46 14, 50 16, 54 14"
+        stroke="url(#wave-grad)" stroke-width="3.5" fill="none" stroke-linecap="round" stroke-linejoin="round"/>
+
+  <!-- Secondary pulse line (echo effect for depth) -->
+  <path d="M 10 52 C 16 52, 18 46, 22 44 C 26 42, 28 40, 32 36 C 36 32, 38 26, 42 22 C 46 18, 50 20, 54 18"
+        stroke="url(#wave-grad)" stroke-width="1.5" fill="none" stroke-linecap="round" opacity="0.3"/>
+
+  <!-- Cursor dot at the "current position" on the wave -->
+  <circle cx="42" cy="18" r="3.5" fill="#E9AB34"/>
+  <circle cx="42" cy="18" r="6" fill="#E9AB34" opacity="0.15"/>
+
+  <!-- Baseline -->
+  <line x1="10" y1="54" x2="54" y2="54" stroke="#8B7D6B" stroke-width="1" stroke-linecap="round" opacity="0.4"/>
+</svg>

package/assets/logo/logo-white.svg

@@ -0,0 +1,24 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 360 72" width="360" height="72">
+  <!-- White version for dark backgrounds — no background rectangle -->
+
+  <!-- Mark: Context wave -->
+  <g transform="translate(8, 4)">
+    <path d="M 10 48 C 16 48, 18 42, 22 40 C 26 38, 28 36, 32 32 C 36 28, 38 22, 42 18 C 46 14, 50 16, 54 14"
+          stroke="#FFFFFF" stroke-width="3.5" fill="none" stroke-linecap="round" stroke-linejoin="round"/>
+    <path d="M 10 52 C 16 52, 18 46, 22 44 C 26 42, 28 40, 32 36 C 36 32, 38 26, 42 22 C 46 18, 50 20, 54 18"
+          stroke="#FFFFFF" stroke-width="1.5" fill="none" stroke-linecap="round" opacity="0.25"/>
+    <circle cx="42" cy="18" r="3.5" fill="#FFFFFF"/>
+    <circle cx="42" cy="18" r="6" fill="#FFFFFF" opacity="0.12"/>
+    <line x1="10" y1="54" x2="54" y2="54" stroke="#FFFFFF" stroke-width="1" stroke-linecap="round" opacity="0.3"/>
+  </g>
+
+  <!-- Divider -->
+  <line x1="76" y1="16" x2="76" y2="56" stroke="#FFFFFF" stroke-width="1" opacity="0.2"/>
+
+  <!-- Wordmark -->
+  <text x="90" y="35" font-family="'SF Mono', 'JetBrains Mono', 'Fira Code', 'Cascadia Code', monospace" font-size="22" font-weight="700" fill="#FFFFFF" letter-spacing="-0.3">cc-context</text>
+  <text x="90" y="55" font-family="'SF Mono', 'JetBrains Mono', 'Fira Code', 'Cascadia Code', monospace" font-size="15" font-weight="500" fill="#FFFFFF" letter-spacing="3" opacity="0.7">stats</text>
+
+  <!-- Right accent bar -->
+  <rect x="348" y="20" width="2" height="32" rx="1" fill="#FFFFFF" opacity="0.4"/>
+</svg>

package/assets/logo/logo-wordmark.svg

@@ -0,0 +1,6 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 260 52" width="260" height="52">
+  <!-- Wordmark only — transparent background -->
+  <!-- "cc-context" bold, "stats" in golden amber below -->
+  <text x="0" y="30" font-family="'SF Mono', 'JetBrains Mono', 'Fira Code', 'Cascadia Code', monospace" font-size="24" font-weight="700" fill="#1A1A1A" letter-spacing="-0.3">cc-context</text>
+  <text x="0" y="48" font-family="'SF Mono', 'JetBrains Mono', 'Fira Code', 'Cascadia Code', monospace" font-size="15" font-weight="500" fill="#E9AB34" letter-spacing="3">stats</text>
+</svg>

package/install.sh

@@ -1,12 +1,28 @@
 #!/bin/bash
 #
-# Claude Code Status Line Installer
-# Installs and configures a status line for Claude Code
+# Claude Code Context Stats Installer
+# Installs and configures context monitoring for Claude Code
+#
+# Features:
+#   - Real-time context usage monitoring (status line integration)
+#   - Live dashboard with context-stats CLI tool
+#   - Automatic detection of Smart Zone, Dumb Zone, and Wrap Up Zone
+#   - Local data storage in ~/.claude/statusline/
 #
 # Usage:
 #   Local:  ./install.sh
 #   Remote: curl -fsSL https://raw.githubusercontent.com/luongnv89/cc-context-stats/main/install.sh | bash
 #
+# Requirements:
+#   - curl (for remote installation)
+#   - jq (for JSON configuration, optional but recommended)
+#
+# What gets installed:
+#   - ~/.claude/statusline.sh - Status line command
+#   - ~/.local/bin/context-stats - CLI tool for live context monitoring
+#   - ~/.claude/statusline.conf - Configuration file
+#   - ~/.claude/settings.json - Claude Code settings updated
+#
 
 set -e
 
@@ -208,6 +224,9 @@ show_delta=true
 
 # Show session_id in status line
 show_session=true
+
+# Disable rotating text animations
+reduced_motion=false
 EOF
     echo -e "${GREEN}✓${RESET} Created config file: $CONFIG_FILE"
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "cc-context-stats",
-  "version": "1.3.0",
-  "description": "Custom status line scripts for Claude Code",
+  "version": "1.5.1",
+  "description": "Monitor your Claude Code session context in real-time - track token usage and never run out of context",
   "main": "scripts/statusline.js",
   "scripts": {
     "test": "jest",
@@ -15,9 +15,13 @@
   "keywords": [
     "claude",
     "claude-code",
+    "context",
+    "tokens",
+    "monitoring",
     "statusline",
     "terminal",
-    "cli"
+    "cli",
+    "dashboard"
   ],
   "author": "luongnv89",
   "license": "MIT",

package/pyproject.toml

@@ -4,8 +4,8 @@ build-backend = "hatchling.build"
 
 [project]
 name = "cc-context-stats"
-version = "1.3.0"
-description = "Never run out of context unexpectedly - monitor your session context in real-time"
+version = "1.5.1"
+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" }
 requires-python = ">=3.9"
@@ -15,11 +15,13 @@ authors = [
 keywords = [
     "claude",
     "claude-code",
+    "context",
     "tokens",
-    "context-window",
     "monitoring",
-    "visualization",
+    "statusline",
+    "terminal",
     "cli",
+    "dashboard",
 ]
 classifiers = [
     "Development Status :: 4 - Beta",