cc-context-stats 1.3.0

package/.pre-commit-config.yaml

@@ -0,0 +1,74 @@
+# Pre-commit hooks for claude-statusline project
+# Install: pip install pre-commit && pre-commit install
+# Run all: pre-commit run --all-files
+
+default_language_version:
+  python: python3
+
+repos:
+  # General file checks
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.5.0
+    hooks:
+      - id: check-yaml
+      - id: check-json
+      - id: check-toml
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+      - id: mixed-line-ending
+        args: ['--fix=lf']
+      - id: check-executables-have-shebangs
+      - id: check-shebang-scripts-are-executable
+      - id: detect-private-key
+      - id: check-merge-conflict
+      - id: check-added-large-files
+        args: ['--maxkb=500']
+
+  # ShellCheck for bash scripts
+  - repo: https://github.com/shellcheck-py/shellcheck-py
+    rev: v0.9.0.6
+    hooks:
+      - id: shellcheck
+        args: ['--severity=warning']
+        files: \.(sh|bash)$
+
+  # Python: Ruff linter and formatter
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.1.14
+    hooks:
+      - id: ruff
+        args: ['--fix']
+        files: \.py$
+      - id: ruff-format
+        files: \.py$
+
+  # JavaScript: ESLint
+  - repo: https://github.com/pre-commit/mirrors-eslint
+    rev: v8.56.0
+    hooks:
+      - id: eslint
+        files: \.js$
+        types: [javascript]
+        additional_dependencies:
+          - eslint@8.56.0
+
+  # Prettier for JS, JSON, MD
+  - repo: https://github.com/pre-commit/mirrors-prettier
+    rev: v4.0.0-alpha.8
+    hooks:
+      - id: prettier
+        types_or: [javascript, json, markdown]
+        additional_dependencies:
+          - prettier@3.2.5
+
+  # Markdown lint
+  - repo: https://github.com/igorshubovych/markdownlint-cli
+    rev: v0.39.0
+    hooks:
+      - id: markdownlint
+        args: ['--fix', '--disable', 'MD013', 'MD024', 'MD033', 'MD040', 'MD041', '--']
+
+ci:
+  autofix_prs: true
+  autofix_commit_msg: 'style: auto-fix pre-commit issues'
+  autoupdate_schedule: monthly

package/.prettierrc

@@ -0,0 +1,33 @@
+{
+  "printWidth": 100,
+  "tabWidth": 4,
+  "useTabs": false,
+  "semi": true,
+  "singleQuote": true,
+  "quoteProps": "as-needed",
+  "trailingComma": "es5",
+  "bracketSpacing": true,
+  "arrowParens": "avoid",
+  "endOfLine": "lf",
+  "overrides": [
+    {
+      "files": "*.json",
+      "options": {
+        "tabWidth": 2
+      }
+    },
+    {
+      "files": "*.md",
+      "options": {
+        "tabWidth": 2,
+        "proseWrap": "preserve"
+      }
+    },
+    {
+      "files": "*.{yml,yaml}",
+      "options": {
+        "tabWidth": 2
+      }
+    }
+  ]
+}

package/.shellcheckrc

@@ -0,0 +1,10 @@
+# ShellCheck configuration for claude-statusline project
+
+# Set default shell to bash
+shell=bash
+
+# Enable external sources for sourcing config files
+external-sources=true
+
+# Severity: error, warning, info, style
+severity=style

package/CHANGELOG.md

@@ -0,0 +1,100 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [1.2.0] - 2025-01-08
+
+### Added
+
+- **Context Zones** - Status indicator based on context usage:
+  - 🟢 Smart Zone (< 40%): "You are in the smart zone"
+  - 🟡 Dumb Zone (40-80%): "You are in the dumb zone - Dex Horthy says so"
+  - 🔴 Wrap Up Zone (> 80%): "Better to wrap up and start a new session"
+- **Project name display** - Header now shows "Context Stats (project-name • session-id)"
+
+### Changed
+
+- **Watch mode enabled by default** - `context-stats` now runs in live monitoring mode (2s refresh)
+- **Delta graph by default** - Shows "Context Growth Per Interaction" instead of both graphs
+- Added `--no-watch` flag to show graphs once and exit
+- Simplified installer - no script selection, auto-overwrite existing files
+- Renamed graph labels to focus on context (e.g., "Context Usage Over Time")
+- Cleaned up session summary - removed clutter, highlighted status
+
+## [1.1.0] - 2025-01-08
+
+### Changed
+
+- **BREAKING**: Renamed package from `cc-statusline` to `cc-context-stats`
+- **BREAKING**: Renamed `token-graph` CLI command to `context-stats`
+- Pivoted project focus to real-time token monitoring and context tracking
+- Updated tagline: "Never run out of context unexpectedly"
+
+### Migration
+
+If upgrading from `cc-statusline`:
+
+```bash
+pip uninstall cc-statusline
+pip install cc-context-stats
+```
+
+The `claude-statusline` command still works. Replace `token-graph` with `context-stats`.
+
+## [1.0.2] - 2025-01-08
+
+### Fixed
+
+- Fixed remaining context showing negative values in context-stats by using `current_used_tokens` instead of cumulative `total_input_tokens + total_output_tokens`
+- Fixed ANSI escape codes not rendering properly in watch mode by using `sys.stdout.write()` instead of `print()` for cursor control sequences
+- Fixed color codes in summary statistics using ColorManager instead of raw ANSI constants
+
+## [1.0.1] - 2025-01-07
+
+### Added
+
+- pip/uv installable Python package (`cc-statusline` on PyPI)
+- `context_window_size` field to state file for tracking remaining context
+- Remaining context display in context-stats summary
+
+### Fixed
+
+- Restored executable permissions on script files
+- Fixed stdin detection in pipe mode using INTERACTIVE flag
+
+### Changed
+
+- Cleaned up unused `show_io_tokens` option
+- Fixed shellcheck warnings in shell scripts
+
+## [1.0.0] - 2025-01-06
+
+### Added
+
+- Comprehensive test suite with Bats (Bash), pytest (Python), and Jest (Node.js)
+- GitHub Actions CI/CD pipeline with multi-platform testing
+- Code quality tools: ShellCheck, Ruff, ESLint, Prettier
+- Pre-commit hooks for automated code quality checks
+- EditorConfig for consistent formatting across editors
+- CONTRIBUTING.md with development setup instructions
+- Dependabot configuration for automated dependency updates
+- Release automation workflow
+- Full-featured status line script (`statusline-full.sh`)
+- Git-aware status line script (`statusline-git.sh`)
+- Minimal status line script (`statusline-minimal.sh`)
+- Cross-platform Python implementation (`statusline.py`)
+- Cross-platform Node.js implementation (`statusline.js`)
+- Interactive installer script (`install.sh`)
+- Configuration examples for Claude Code
+- Autocompact (AC) buffer indicator
+- Context window usage with color-coded percentages
+- Git branch and uncommitted changes display
+
+## [0.x] - Pre-release
+
+Initial development versions with basic status line functionality.

package/CONTRIBUTING.md

@@ -0,0 +1,240 @@
+# Contributing to Claude Code Status Line
+
+Thank you for your interest in contributing to Claude Code Status Line! This document provides guidelines and instructions for contributing.
+
+## Development Setup
+
+### Prerequisites
+
+- **Git** - Version control
+- **jq** - JSON processor (for bash scripts)
+- **Python 3.9+** - For Python script and testing
+- **Node.js 18+** - For Node.js script and testing
+- **Bats** - Bash Automated Testing System
+
+### Installing Dependencies
+
+#### macOS
+
+```bash
+# Install system dependencies
+brew install jq bats-core
+
+# Clone the repository
+git clone https://github.com/luongnv89/cc-context-stats.git
+cd claude-statusline
+
+# Install Python dependencies
+python3 -m venv venv
+source venv/bin/activate
+pip install -r requirements-dev.txt
+
+# Install Node.js dependencies
+npm install
+
+# Install pre-commit hooks
+pre-commit install
+```
+
+#### Linux (Ubuntu/Debian)
+
+```bash
+# Install system dependencies
+sudo apt-get update
+sudo apt-get install -y jq bats
+
+# Clone the repository
+git clone https://github.com/luongnv89/cc-context-stats.git
+cd claude-statusline
+
+# Install Python dependencies
+python3 -m venv venv
+source venv/bin/activate
+pip install -r requirements-dev.txt
+
+# Install Node.js dependencies
+npm install
+
+# Install pre-commit hooks
+pre-commit install
+```
+
+## Project Structure
+
+```text
+claude-statusline/
+├── scripts/                    # Main scripts
+│   ├── statusline-full.sh      # Full-featured bash script
+│   ├── statusline-git.sh       # Git-aware bash script
+│   ├── statusline-minimal.sh   # Minimal bash script
+│   ├── statusline.py           # Python cross-platform script
+│   └── statusline.js           # Node.js cross-platform script
+├── config/                     # Configuration examples
+├── tests/                      # Test suites
+│   ├── fixtures/json/          # Test fixtures
+│   ├── bash/                   # Bats tests
+│   ├── python/                 # Pytest tests
+│   └── node/                   # Jest tests
+├── .github/workflows/          # CI/CD workflows
+├── install.sh                  # Installation script
+└── README.md                   # Documentation
+```
+
+## Running Tests
+
+### All Tests
+
+```bash
+# Run all tests
+npm test && pytest && bats tests/bash/*.bats
+```
+
+### Individual Test Suites
+
+```bash
+# Bash tests (requires bats)
+bats tests/bash/*.bats
+
+# Python tests
+pytest tests/python/ -v
+
+# Python tests with coverage
+pytest tests/python/ -v --cov=scripts --cov-report=html
+
+# Node.js tests
+npm test
+
+# Node.js tests with coverage
+npm run test:coverage
+```
+
+## Code Quality
+
+### Linting
+
+```bash
+# Run all linters
+pre-commit run --all-files
+
+# Individual linters
+ruff check scripts/statusline.py          # Python
+npx eslint scripts/statusline.js          # JavaScript
+shellcheck scripts/*.sh install.sh        # Bash
+```
+
+### Formatting
+
+```bash
+# Auto-format Python
+ruff format scripts/statusline.py
+
+# Auto-format JavaScript
+npx prettier --write scripts/statusline.js
+
+# Check formatting without modifying
+ruff format --check scripts/statusline.py
+npx prettier --check scripts/statusline.js
+```
+
+## Making Changes
+
+### 1. Create a Branch
+
+```bash
+git checkout -b feature/your-feature-name
+# or
+git checkout -b fix/your-bug-fix
+```
+
+### 2. Make Changes
+
+- Follow the existing code style
+- Add tests for new functionality
+- Update documentation if needed
+- Ensure all scripts produce consistent output
+
+### 3. Test Your Changes
+
+```bash
+# Run pre-commit hooks
+pre-commit run --all-files
+
+# Run all tests
+bats tests/bash/*.bats
+pytest tests/python/ -v
+npm test
+
+# Test scripts manually
+echo '{"model":{"display_name":"Test"}}' | ./scripts/statusline-full.sh
+echo '{"model":{"display_name":"Test"}}' | python3 ./scripts/statusline.py
+echo '{"model":{"display_name":"Test"}}' | node ./scripts/statusline.js
+```
+
+### 4. Commit Your Changes
+
+Use conventional commit messages:
+
+```bash
+git commit -m "feat: add new feature description"
+git commit -m "fix: fix bug description"
+git commit -m "docs: update documentation"
+git commit -m "test: add tests for feature"
+git commit -m "refactor: refactor code description"
+```
+
+### 5. Push and Create PR
+
+```bash
+git push origin feature/your-feature-name
+```
+
+Then create a Pull Request on GitHub.
+
+## Script Guidelines
+
+### Cross-Script Consistency
+
+All three implementations (bash, Python, Node.js) should produce identical output for the same input. When making changes:
+
+1. Update all three scripts consistently
+2. Run integration tests to verify parity
+3. Test on multiple platforms if possible
+
+### Output Format
+
+The status line output should follow this format:
+
+```text
+[Model] directory | branch [changes] | XXk free (XX%) [AC:XXk]
+```
+
+Components:
+
+- `[Model]` - AI model name (dim)
+- `directory` - Current directory name (blue)
+- `branch` - Git branch name (magenta)
+- `[changes]` - Uncommitted changes count (cyan)
+- `XXk free (XX%)` - Available context tokens (green/yellow/red)
+- `[AC:XXk]` - Autocompact buffer (dim)
+
+### Color Codes
+
+Use ANSI color codes consistently:
+
+- Blue: `\033[0;34m`
+- Magenta: `\033[0;35m`
+- Cyan: `\033[0;36m`
+- Green: `\033[0;32m`
+- Yellow: `\033[0;33m`
+- Red: `\033[0;31m`
+- Dim: `\033[2m`
+- Reset: `\033[0m`
+
+## Questions?
+
+If you have questions, feel free to:
+
+- Open an issue on GitHub
+- Check existing issues for similar questions
+
+Thank you for contributing!

package/PUBLISHING_GUIDE.md

@@ -0,0 +1,69 @@
+# npm Package Publishing Guide
+
+## Step 1: Access Your npm Account with Recovery Code
+
+1. Go to https://www.npmjs.com/login
+2. Enter your credentials (luong.nguyen + password)
+3. When prompted for 2FA, click "Use a recovery code or request a reset"
+4. Enter one of your 8-character recovery codes
+5. You should now be logged into your npm account
+
+## Step 2: Set Up Microsoft Authenticator
+
+1. Once logged in, click your profile picture (top right)
+2. Go to "Account"
+3. Under "Two-Factor Authentication", click "Modify 2FA"
+4. Choose to add an "Authenticator app"
+5. npm will show you a QR code
+
+### In Microsoft Authenticator:
+
+1. Open Microsoft Authenticator app
+2. Tap the `+` button (top right)
+3. Choose "Personal account" or "Work/school account"
+4. Tap "Scan QR code"
+5. Scan the QR code from npm website
+6. The app will now show "npm" with a 6-digit code
+
+## Step 3: Publish Your Package
+
+1. Get the current 6-digit code from Microsoft Authenticator
+2. Run this command in your terminal:
+
+```bash
+cd /Users/montimage/buildspace/luongnv89/cc-context-stats
+./publish.sh YOUR_6_DIGIT_CODE
+```
+
+For example:
+
+```bash
+./publish.sh 123456
+```
+
+## Step 4: Verify Publication
+
+After successful publishing, you can verify with:
+
+```bash
+npm view cc-context-stats
+```
+
+## Important Notes:
+
+- Recovery codes are single-use - once you use one, it's gone
+- Keep your remaining recovery codes safe
+- Microsoft Authenticator will provide new codes every 30 seconds
+- The package will be published as "cc-context-stats@1.3.0"
+
+## Troubleshooting:
+
+If you get "Invalid OTP" error:
+
+- Wait for a new code to generate in Microsoft Authenticator (codes change every 30 seconds)
+- Make sure you're typing the code correctly
+
+If you can't log into the website:
+
+- Try a different recovery code
+- Make sure you're typing the 8-character code correctly (no spaces)

package/README.md

@@ -0,0 +1,179 @@
+# Claude Code Context Stats
+
+[![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/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**Never run out of context unexpectedly** - monitor your session context in real-time.
+
+![Context Stats](images/context-status-dumbzone.png)
+
+## Why Context Stats?
+
+When working with Claude Code on complex tasks, you can easily burn through your context window without realizing it. As your context fills up, Claude's performance degrades - this is what Dex Horthy calls the "dumb zone". Context Stats helps you:
+
+- **Know your zone** - See if you're in the Smart Zone, Dumb Zone, or Wrap Up Zone
+- **Track context usage** - Real-time monitoring with live-updating graphs
+- **Get early warnings** - Color-coded status alerts you before performance degrades
+- **Make informed decisions** - Know when to start a fresh session
+
+## Context Zones
+
+| Zone                | Context Used | Status   | What It Means                                 |
+| ------------------- | ------------ | -------- | --------------------------------------------- |
+| 🟢 **Smart Zone**   | < 40%        | Optimal  | Claude is performing at its best              |
+| 🟡 **Dumb Zone**    | 40-80%       | Degraded | Context getting full, Claude may miss details |
+| 🔴 **Wrap Up Zone** | > 80%        | Critical | Better to wrap up and start a new session     |
+
+## Installation
+
+```bash
+pip install cc-context-stats
+```
+
+Or with uv:
+
+```bash
+uv pip install cc-context-stats
+```
+
+## Quick Start
+
+### Real-Time Monitoring
+
+Get your session ID from the status line (the last part after the pipe `|`), then run:
+
+```bash
+context-stats <session_id>
+```
+
+For example:
+
+```bash
+context-stats abc123def-456-789
+```
+
+This opens a live dashboard that refreshes every 2 seconds, showing:
+
+- Your current project and session
+- Context growth per interaction graph
+- Your current zone status
+- Remaining context percentage
+
+Press `Ctrl+C` to exit.
+
+### Status Line Integration
+
+Add to `~/.claude/settings.json`:
+
+```json
+{
+  "statusLine": {
+    "type": "command",
+    "command": "claude-statusline"
+  }
+}
+```
+
+Restart Claude Code to see real-time token stats in your status bar.
+
+## Context Stats CLI
+
+```bash
+context-stats                    # Live monitoring (default)
+context-stats -w 5               # Custom refresh interval (5 seconds)
+context-stats --no-watch         # Show once and exit
+context-stats --type cumulative  # Show cumulative context usage
+context-stats --type both        # Show both graphs
+context-stats --type all         # Show all graphs including I/O
+context-stats <session_id>       # View specific session
+```
+
+### Output Example
+
+```
+Context Stats (my-project • abc123def)
+
+Context Growth Per Interaction
+Max: 4,787  Min: 0  Points: 254
+...graph...
+
+Session Summary
+----------------------------------------------------------------------------
+  Context Remaining:   43,038/200,000 (21%)
+  >>> DUMB ZONE <<< (You are in the dumb zone - Dex Horthy says so)
+
+  Last Growth:         +2,500
+  Input Tokens:        1,234
+  Output Tokens:       567
+  Lines Changed:       +45 / -12
+  Total Cost:          $0.1234
+  Model:               claude-sonnet-4-20250514
+  Session Duration:    2h 29m
+```
+
+## Status Line
+
+![Status Line](images/statusline-detail.png)
+
+The status line shows at-a-glance metrics in your Claude Code interface:
+
+| Component | Description                               |
+| --------- | ----------------------------------------- |
+| Model     | Current Claude model                      |
+| Context   | Tokens used / remaining with color coding |
+| Delta     | Token change since last update            |
+| Git       | Branch name and uncommitted changes       |
+| Session   | Session ID for correlation                |
+
+## Configuration
+
+Create `~/.claude/statusline.conf`:
+
+```bash
+token_detail=true   # Show exact token counts (vs abbreviated like "12.5k")
+show_delta=true     # Show token delta in status line
+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.
+
+## Documentation
+
+- [Context Stats Guide](docs/context-stats.md) - Detailed usage guide
+- [Configuration Options](docs/configuration.md) - All settings explained
+- [Installation Guide](docs/installation.md) - Platform-specific setup
+- [Troubleshooting](docs/troubleshooting.md) - Common issues
+- [Changelog](CHANGELOG.md) - Version history
+
+## Migration from cc-statusline
+
+If you were using the previous `cc-statusline` package:
+
+```bash
+pip uninstall cc-statusline
+pip install cc-context-stats
+```
+
+The `claude-statusline` command still works. The main change is `token-graph` is now `context-stats`.
+
+## 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
+
+MIT