cc-context-stats 1.3.0 → 1.5.0

package/.claude/settings.local.json

@@ -79,7 +79,39 @@
       "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:*)"
     ]
   }
 }

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/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,9 @@
+## What's Changed
+
+### Refactoring
+- **Remove icon and pacman display options from statusline** — Simplify the statusline by removing `icon_mode` config option (`standard`/`pacman`/`off`), activity icons, and pacman meter visualization. Activity tier detection and text labels are preserved for context-stats. Net removal of ~413 lines across 10 files (#13) @luongnv89
+
+### Bug Fixes
+- **Eliminate watch mode flickering via double-buffered rendering** — Replace cursor-home + line-by-line overwrites with full-frame buffering that writes the entire screen in a single `sys.stdout.write()` call, eliminating visible flicker during watch mode refreshes
+
+**Full Changelog**: https://github.com/luongnv89/cc-context-stats/compare/v1.4.0...v1.5.0

package/assets/logo/favicon.svg

@@ -0,0 +1,16 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16" width="16" height="16">
+  <!-- Favicon — ultra-minimal gauge -->
+  <rect width="16" height="16" rx="3" fill="#000000"/>
+  <!-- Gauge arc -->
+  <path d="M 2.5 12 A 6 6 0 1 1 13.5 12" stroke="#1a1a1a" stroke-width="1.8" fill="none" stroke-linecap="round"/>
+  <!-- Green segment -->
+  <path d="M 2.5 12 A 6 6 0 0 1 4.6 6.4" stroke="#22C55E" stroke-width="1.8" fill="none" stroke-linecap="round"/>
+  <!-- Yellow segment -->
+  <path d="M 4.6 6.4 A 6 6 0 0 1 11.4 6.4" stroke="#F59E0B" stroke-width="1.8" fill="none" stroke-linecap="round"/>
+  <!-- Red segment -->
+  <path d="M 11.4 6.4 A 6 6 0 0 1 13.5 12" stroke="#EF4444" stroke-width="1.8" fill="none" stroke-linecap="round"/>
+  <!-- Needle -->
+  <line x1="8" y1="8" x2="5.2" y2="5.2" stroke="#FFFFFF" stroke-width="1" stroke-linecap="round"/>
+  <!-- Pivot -->
+  <circle cx="8" cy="8" r="1" fill="#22C55E"/>
+</svg>

package/assets/logo/logo-black.svg

@@ -0,0 +1,23 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 320 64" width="320" height="64">
+  <!-- Black version for light backgrounds -->
+
+  <!-- Gauge track arc (light gray) -->
+  <path d="M 12 50 A 22 22 0 1 1 52 50" stroke="#E5E7EB" stroke-width="5" fill="none" stroke-linecap="round"/>
+  <!-- Green zone -->
+  <path d="M 12 50 A 22 22 0 0 1 18.2 30.4" stroke="#16A34A" stroke-width="5" fill="none" stroke-linecap="round"/>
+  <!-- Yellow zone -->
+  <path d="M 18.2 30.4 A 22 22 0 0 1 45.8 30.4" stroke="#D97706" stroke-width="5" fill="none" stroke-linecap="round"/>
+  <!-- Red zone -->
+  <path d="M 45.8 30.4 A 22 22 0 0 1 52 50" stroke="#DC2626" stroke-width="5" fill="none" stroke-linecap="round"/>
+  <!-- Needle -->
+  <line x1="32" y1="38" x2="21" y2="27" stroke="#000000" stroke-width="2.5" stroke-linecap="round"/>
+  <!-- Pivot -->
+  <circle cx="32" cy="38" r="3" fill="#16A34A"/>
+
+  <!-- Divider -->
+  <line x1="68" y1="12" x2="68" y2="52" stroke="#D1D5DB" stroke-width="1"/>
+
+  <!-- Wordmark black -->
+  <text x="82" y="30" font-family="'SF Mono', 'Fira Mono', 'Courier New', monospace" font-size="18" font-weight="700" fill="#000000" letter-spacing="-0.5">cc-context</text>
+  <text x="82" y="50" font-family="'SF Mono', 'Fira Mono', 'Courier New', monospace" font-size="14" font-weight="500" fill="#16A34A" letter-spacing="2">stats</text>
+</svg>

package/assets/logo/logo-full.svg

@@ -0,0 +1,30 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 320 64" width="320" height="64">
+  <!-- Background -->
+  <rect width="320" height="64" rx="12" fill="#000000"/>
+
+  <!-- Mark: Gauge icon (left, inset) -->
+  <!-- Gauge track arc -->
+  <path d="M 12 50 A 22 22 0 1 1 52 50" stroke="#1a1a1a" stroke-width="5" fill="none" stroke-linecap="round"/>
+  <!-- Green zone -->
+  <path d="M 12 50 A 22 22 0 0 1 18.2 30.4" stroke="#22C55E" stroke-width="5" fill="none" stroke-linecap="round"/>
+  <!-- Yellow zone -->
+  <path d="M 18.2 30.4 A 22 22 0 0 1 45.8 30.4" stroke="#F59E0B" stroke-width="5" fill="none" stroke-linecap="round"/>
+  <!-- Red zone -->
+  <path d="M 45.8 30.4 A 22 22 0 0 1 52 50" stroke="#EF4444" stroke-width="5" fill="none" stroke-linecap="round"/>
+  <!-- Needle -->
+  <line x1="32" y1="38" x2="21" y2="27" stroke="#FFFFFF" stroke-width="2.5" stroke-linecap="round"/>
+  <!-- Pivot -->
+  <circle cx="32" cy="38" r="3" fill="#22C55E"/>
+
+  <!-- Divider line -->
+  <line x1="68" y1="12" x2="68" y2="52" stroke="#1f1f1f" stroke-width="1"/>
+
+  <!-- Wordmark: "cc-context" on top row, "stats" accent -->
+  <!-- Primary text -->
+  <text x="82" y="30" font-family="'SF Mono', 'Fira Mono', 'Courier New', monospace" font-size="18" font-weight="700" fill="#FFFFFF" letter-spacing="-0.5">cc-context</text>
+  <!-- Accent text with green highlight -->
+  <text x="82" y="50" font-family="'SF Mono', 'Fira Mono', 'Courier New', monospace" font-size="14" font-weight="500" fill="#22C55E" letter-spacing="2">stats</text>
+
+  <!-- Subtle border accent on right -->
+  <rect x="308" y="16" width="2" height="32" rx="1" fill="#22C55E" opacity="0.6"/>
+</svg>

package/assets/logo/logo-icon.svg

@@ -0,0 +1,26 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512" width="512" height="512">
+  <!-- App icon — square with padding and rounded corners -->
+  <rect width="512" height="512" rx="96" fill="#000000"/>
+
+  <!-- Gauge track (background) -->
+  <path d="M 96 352 A 176 176 0 1 1 416 352" stroke="#111111" stroke-width="38" fill="none" stroke-linecap="round"/>
+
+  <!-- Green zone (0-40%) -->
+  <path d="M 96 352 A 176 176 0 0 1 145.6 194.8" stroke="#22C55E" stroke-width="38" fill="none" stroke-linecap="round"/>
+
+  <!-- Yellow zone (40-80%) -->
+  <path d="M 145.6 194.8 A 176 176 0 0 1 366.4 194.8" stroke="#F59E0B" stroke-width="38" fill="none" stroke-linecap="round"/>
+
+  <!-- Red zone (80-100%) -->
+  <path d="M 366.4 194.8 A 176 176 0 0 1 416 352" stroke="#EF4444" stroke-width="38" fill="none" stroke-linecap="round"/>
+
+  <!-- Needle at ~55% -->
+  <line x1="256" y1="256" x2="168" y2="168" stroke="#FFFFFF" stroke-width="20" stroke-linecap="round"/>
+
+  <!-- Pivot dot -->
+  <circle cx="256" cy="256" r="24" fill="#22C55E"/>
+
+  <!-- Label dots at zone boundaries -->
+  <circle cx="96" cy="352" r="8" fill="#6B7280"/>
+  <circle cx="416" cy="352" r="8" fill="#6B7280"/>
+</svg>

package/assets/logo/logo-mark.svg

@@ -0,0 +1,26 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" width="64" height="64">
+  <!-- Background square with rounded corners -->
+  <rect width="64" height="64" rx="12" fill="#000000"/>
+
+  <!-- Gauge track arc (background) -->
+  <path d="M 12 44 A 22 22 0 1 1 52 44" stroke="#1a1a1a" stroke-width="5" fill="none" stroke-linecap="round"/>
+
+  <!-- Gauge fill: green zone (0-40%) -->
+  <path d="M 12 44 A 22 22 0 0 1 18.2 24.4" stroke="#22C55E" stroke-width="5" fill="none" stroke-linecap="round"/>
+
+  <!-- Gauge fill: yellow zone (40-80%) -->
+  <path d="M 18.2 24.4 A 22 22 0 0 1 45.8 24.4" stroke="#F59E0B" stroke-width="5" fill="none" stroke-linecap="round"/>
+
+  <!-- Gauge fill: red zone (80-100%) -->
+  <path d="M 45.8 24.4 A 22 22 0 0 1 52 44" stroke="#EF4444" stroke-width="5" fill="none" stroke-linecap="round"/>
+
+  <!-- Needle at ~55% (in dumb zone) -->
+  <line x1="32" y1="32" x2="21" y2="21" stroke="#FFFFFF" stroke-width="2.5" stroke-linecap="round"/>
+
+  <!-- Needle pivot center dot -->
+  <circle cx="32" cy="32" r="3" fill="#22C55E"/>
+
+  <!-- Tick marks at zone boundaries -->
+  <line x1="12" y1="44" x2="14.5" y2="41.5" stroke="#6B7280" stroke-width="1.5" stroke-linecap="round"/>
+  <line x1="52" y1="44" x2="49.5" y2="41.5" stroke="#6B7280" stroke-width="1.5" stroke-linecap="round"/>
+</svg>

package/assets/logo/logo-white.svg

@@ -0,0 +1,23 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 320 64" width="320" height="64">
+  <!-- White version for dark backgrounds — no bg rect -->
+
+  <!-- Gauge track arc (dim white) -->
+  <path d="M 12 50 A 22 22 0 1 1 52 50" stroke="rgba(255,255,255,0.15)" stroke-width="5" fill="none" stroke-linecap="round"/>
+  <!-- Green zone -->
+  <path d="M 12 50 A 22 22 0 0 1 18.2 30.4" stroke="#22C55E" stroke-width="5" fill="none" stroke-linecap="round"/>
+  <!-- Yellow zone -->
+  <path d="M 18.2 30.4 A 22 22 0 0 1 45.8 30.4" stroke="#F59E0B" stroke-width="5" fill="none" stroke-linecap="round"/>
+  <!-- Red zone -->
+  <path d="M 45.8 30.4 A 22 22 0 0 1 52 50" stroke="#EF4444" stroke-width="5" fill="none" stroke-linecap="round"/>
+  <!-- Needle -->
+  <line x1="32" y1="38" x2="21" y2="27" stroke="#FFFFFF" stroke-width="2.5" stroke-linecap="round"/>
+  <!-- Pivot -->
+  <circle cx="32" cy="38" r="3" fill="#22C55E"/>
+
+  <!-- Divider -->
+  <line x1="68" y1="12" x2="68" y2="52" stroke="rgba(255,255,255,0.2)" stroke-width="1"/>
+
+  <!-- Wordmark white -->
+  <text x="82" y="30" font-family="'SF Mono', 'Fira Mono', 'Courier New', monospace" font-size="18" font-weight="700" fill="#FFFFFF" letter-spacing="-0.5">cc-context</text>
+  <text x="82" y="50" font-family="'SF Mono', 'Fira Mono', 'Courier New', monospace" font-size="14" font-weight="500" fill="#22C55E" letter-spacing="2">stats</text>
+</svg>

package/assets/logo/logo-wordmark.svg

@@ -0,0 +1,7 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 220 48" width="220" height="48">
+  <!-- Background transparent -->
+  <!-- Primary text -->
+  <text x="0" y="28" font-family="'SF Mono', 'Fira Mono', 'Courier New', monospace" font-size="22" font-weight="700" fill="#000000" letter-spacing="-0.5">cc-context</text>
+  <!-- Accent -->
+  <text x="0" y="44" font-family="'SF Mono', 'Fira Mono', 'Courier New', monospace" font-size="14" font-weight="500" fill="#22C55E" letter-spacing="2">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.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": {
     "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.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" }
 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",