cc-context-stats 1.6.2 → 1.8.0

package/CHANGELOG.md

@@ -7,6 +7,45 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.8.0] - 2026-03-15
+
+### Added
+
+- **Model Intelligence (MI) score** — Heuristic quality score estimating answer quality based on context utilization, cache efficiency, and output productivity. Inspired by the Michelangelo paper (arXiv:2409.12640). Displayed as `MI:X.XX` in the statusline with green/yellow/red color coding
+- **MI score in all implementations** — MI computation available across Python package, standalone Python, Node.js, and Bash (via `awk`) statusline scripts with full cross-implementation parity
+- **MI timeseries graph** — `context-stats --type mi` renders MI score trajectory over time as an ASCII graph with decimal Y-axis labels
+- **MI in session summary** — `context-stats` summary now shows MI score with sub-component breakdown (CPS, ES, PS) and interpretation text
+- **Shared test vectors** — `tests/fixtures/mi_test_vectors.json` with 6 vectors ensuring Python and Node.js produce identical MI scores within ±0.01 tolerance
+- **`label_fn` parameter for `render_timeseries()`** — Optional custom Y-axis label formatter, used by MI graph to display decimals instead of token counts
+- **Bash feature parity** — `statusline-full.sh` now supports custom color overrides, state file rotation, MI score display, and all config keys (`show_mi`, `mi_curve_beta`, `reduced_motion`, `show_io_tokens`)
+- **Config: `show_mi`** — Toggle MI score display (default: `true`)
+- **Config: `mi_curve_beta`** — Adjust MI degradation curve shape (default: `1.5`)
+
+### Changed
+
+- **Compact context display** — Removed "free" word from context info (`872,748 (87.3%)` instead of `872,748 free (87.3%)`) across all implementations
+- **Decoupled state reads from `show_delta`** — State file is now read when either `show_delta` or `show_mi` is enabled, allowing MI to work independently of delta display
+- **Node.js terminal width default** — Changed from `80` to `200` when no TTY is detected (matching Python behavior), preventing `fitToWidth` from dropping statusline parts in Claude Code's subprocess
+
+### Fixed
+
+- **Node.js terminal width** — Fixed `getTerminalWidth()` defaulting to 80 in Claude Code's subprocess, which caused MI, delta, AC, and session parts to be silently dropped
+
+## [1.7.0] - 2026-03-14
+
+### Added
+
+- **Configurable colors** - Custom color themes via `~/.claude/statusline.conf` using named colors (`bright_cyan`) or hex codes (`#7dcfff`). Six configurable slots: `color_green`, `color_yellow`, `color_red`, `color_blue`, `color_magenta`, `color_cyan`
+- **`context-stats explain` command** - Diagnostic dump that pretty-prints Claude Code's JSON context with derived values (free tokens, autocompact buffer, effective free), active config, vim/agent/output_style extensions, and raw JSON. Supports `--no-color` flag
+- **24-bit true color support** - Hex color codes (`#rrggbb`) are converted to ANSI 24-bit escape sequences for full RGB color customization
+- **Cross-implementation sync documentation** - Added sync points table to CLAUDE.md documenting triplicated logic across Python, Node.js, and Bash implementations
+
+### Changed
+
+- **ColorManager accepts overrides** - `ColorManager` now takes an optional `overrides` dict, allowing config-driven color customization throughout the package
+- **Git info uses configurable colors** - Branch and change count colors now respect user color overrides in all three implementations
+- **Config parsing preserves raw values** - Config reader now preserves case for color values while lowercasing only for boolean comparison
+
 ## [1.6.2] - 2026-03-13
 
 ### Fixed

package/CLAUDE.md

@@ -47,6 +47,18 @@ pytest && npm test && bats tests/bash/*.bats
 - **5-second git command timeout** in both Python and Node.js implementations
 - **Config via `~/.claude/statusline.conf`** — simple key=value pairs
 
+## Cross-Implementation Sync Points
+
+The following logic is duplicated across three implementations and **must be kept in sync** when modified:
+
+| Logic | Package (`src/`) | Standalone Python (`scripts/statusline.py`) | Node.js (`scripts/statusline.js`) |
+|---|---|---|---|
+| Config parsing | `core/config.py` | `read_config()` | `readConfig()` |
+| Color name map | `core/colors.py:COLOR_NAMES` | `_COLOR_NAMES` | `COLOR_NAMES` |
+| Color parser | `core/colors.py:parse_color()` | `_parse_color()` | `parseColor()` |
+| Git info | `core/git.py:get_git_info()` | `get_git_info()` | `getGitInfo()` |
+| State rotation | `core/state.py` | `maybe_rotate_state_file()` | `maybeRotateStateFile()` |
+
 ## Cross-References
 
 - [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) — system architecture and data flow

package/README.md

@@ -70,6 +70,21 @@ uv pip install cc-context-stats
 
 ## Quick Start
 
+### 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.
+
 ### Real-Time Monitoring
 
 Get your session ID from the status line (the last part after the pipe `|`), then run:
@@ -93,21 +108,6 @@ This opens a live dashboard that refreshes every 2 seconds, showing:
 
 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
@@ -118,6 +118,8 @@ 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
+context-stats explain            # Diagnostic dump (pipe JSON to stdin)
+context-stats --version          # Show version
 ```
 
 ### Output Example
@@ -162,25 +164,33 @@ The status line shows at-a-glance metrics in your Claude Code interface:
 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
+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
+reduced_motion=false # Disable animations for accessibility
+
+# Custom colors - named colors or hex (#rrggbb)
+color_green=#7dcfff
+color_red=#f7768e
+color_yellow=bright_yellow
 ```
 
 ## 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.
+Context Stats hooks into Claude Code's status line feature to track token usage across your sessions. The Python and Node.js statusline scripts write state data to local CSV files, which the context-stats CLI reads to render live graphs. Data is stored locally in `~/.claude/statusline/` and never sent anywhere.
 
 ## Documentation
 
-- [Context Stats Guide](docs/context-stats.md) - Detailed usage guide
+- [Installation Guide](docs/installation.md) - Platform-specific setup (shell, pip, npm)
+- [Context Stats Guide](docs/context-stats.md) - Detailed CLI usage guide
 - [Configuration Options](docs/configuration.md) - All settings explained
-- [Installation Guide](docs/installation.md) - Platform-specific setup
+- [Available Scripts](docs/scripts.md) - Script variants and features
 - [Architecture](docs/ARCHITECTURE.md) - System design and components
-- [Development](docs/DEVELOPMENT.md) - Dev setup and debugging
+- [CSV Format](docs/CSV_FORMAT.md) - State file field specification
+- [Development](docs/DEVELOPMENT.md) - Dev setup, testing, and debugging
 - [Deployment](docs/DEPLOYMENT.md) - Publishing and release process
-- [Troubleshooting](docs/troubleshooting.md) - Common issues
+- [Troubleshooting](docs/troubleshooting.md) - Common issues and solutions
 - [Changelog](CHANGELOG.md) - Version history
 
 ## Contributing

package/docs/ARCHITECTURE.md

@@ -9,6 +9,16 @@ cc-context-stats provides real-time context monitoring for Claude Code sessions.
 
 ## System Architecture
 
+```mermaid
+graph TD
+    CC[Claude Code Host] -->|JSON stdin| SL[Statusline Script]
+    SL -->|stdout text| CC
+    SL -->|writes CSV| SF[State Files<br/>~/.claude/statusline/]
+    SF -->|reads CSV| CS[Context Stats CLI]
+    CF[Config File<br/>~/.claude/statusline.conf] -->|reads| SL
+    GIT[Git Repository] -->|branch/status| SL
+```
+
 ```
 ┌─────────────┐     JSON stdin      ┌──────────────────┐
 │ Claude Code  │ ──────────────────> │ Statusline Script │
@@ -25,7 +35,7 @@ cc-context-stats provides real-time context monitoring for Claude Code sessions.
                                            ▼
                                     ┌──────────────────┐
                                     │ Context Stats CLI │
-                                    │  (Python)         │
+                                    │  (Python/Bash)    │
                                     └──────────────────┘
 ```
 
@@ -35,48 +45,61 @@ cc-context-stats provides real-time context monitoring for Claude Code sessions.
 
 Three implementation languages with identical output:
 
-| Script                | Language   | Dependencies |
-| --------------------- | ---------- | ------------ |
-| `statusline-full.sh`  | Bash       | `jq`         |
-| `statusline-git.sh`   | Bash       | `jq`         |
-| `statusline-minimal.sh` | Bash    | `jq`         |
-| `statusline.py`       | Python 3   | None         |
-| `statusline.js`       | Node.js 18+| None         |
+| Script                 | Language   | Dependencies | State Writes |
+| ---------------------- | ---------- | ------------ | ------------ |
+| `statusline-full.sh`   | Bash       | `jq`         | No           |
+| `statusline-git.sh`    | Bash       | `jq`         | No           |
+| `statusline-minimal.sh`| Bash       | `jq`         | No           |
+| `statusline.py`        | Python 3   | None         | Yes          |
+| `statusline.js`        | Node.js 18+| None         | Yes          |
+
+> **Note:** Only the Python and Node.js scripts write state files. The bash scripts provide status line display only, without persisting data for the context-stats CLI.
 
 **Data flow:**
 1. Claude Code pipes JSON state via stdin on each refresh
 2. Script parses model info, context tokens, session data
 3. Script reads `~/.claude/statusline.conf` for user preferences
-4. Script checks git status for branch/changes info
-5. Script writes state to `~/.claude/statusline/<session_id>.state`
+4. Script checks git status for branch/changes info (5-second timeout)
+5. Python/Node.js scripts write state to `~/.claude/statusline/<session_id>.state`
 6. Script outputs formatted ANSI text to stdout
 
+### Context Stats CLI
+
+Two implementations of the live dashboard:
+
+| Script             | Language | Install Method            |
+| ------------------ | -------- | ------------------------- |
+| `context-stats.sh` | Bash     | Shell installer           |
+| `context_stats.py` | Python   | `pip install cc-context-stats` |
+
+The Python CLI (installed via pip or npm) is the primary implementation, providing live ASCII graphs with zone awareness. The bash script is a standalone alternative installed by the shell installer.
+
 ### Python Package (`src/claude_statusline/`)
 
 The pip-installable package provides both the statusline and context-stats CLI:
 
 ```
 src/claude_statusline/
-├── __init__.py
-├── __main__.py
+├── __init__.py              # Package version and exports
+├── __main__.py              # python -m claude_statusline entry
 ├── cli/
-│   ├── statusline.py      # claude-statusline entry point
-│   └── context_stats.py   # context-stats entry point
+│   ├── statusline.py        # claude-statusline entry point
+│   └── context_stats.py     # context-stats entry point
 ├── core/
-│   ├── colors.py          # ANSI color management
-│   ├── config.py          # Configuration loading
-│   ├── git.py             # Git status detection
-│   └── state.py           # State file reading/writing
+│   ├── colors.py            # ANSI color management
+│   ├── config.py            # Configuration loading
+│   ├── git.py               # Git status detection (5s timeout)
+│   └── state.py             # State file reading/writing/rotation
 ├── formatters/
-│   ├── layout.py          # Output width/layout management
-│   ├── time.py            # Duration formatting
-│   └── tokens.py          # Token count formatting
+│   ├── layout.py            # Output width/layout management
+│   ├── time.py              # Duration formatting
+│   └── tokens.py            # Token count formatting
 ├── graphs/
-│   ├── renderer.py        # ASCII graph rendering
-│   └── statistics.py      # Data statistics
+│   ├── renderer.py          # ASCII graph rendering
+│   └── statistics.py        # Data statistics
 └── ui/
-    ├── icons.py           # Unicode icons
-    └── waiting.py         # Waiting animation
+    ├── icons.py             # Unicode icons
+    └── waiting.py           # Waiting animation
 ```
 
 ### State Files
@@ -89,6 +112,10 @@ State files persist token history between statusline refreshes:
 
 Each line is a CSV record with 14 comma-separated fields (timestamp, token counts, cost, session metadata, and context metrics). See [CSV_FORMAT.md](CSV_FORMAT.md) for the full field specification. The context-stats CLI reads these files to render graphs.
 
+**Rotation:** Files are automatically rotated at 10,000 lines, keeping the most recent 5,000 entries. This prevents unbounded file growth during long sessions.
+
+**Session ID validation:** IDs are validated to reject path-traversal characters (`/`, `\`, `..`, null bytes).
+
 ## Data Privacy
 
 All data stays local:

package/docs/CSV_FORMAT.md

@@ -28,6 +28,8 @@ State files are stored at `~/.claude/statusline/statusline.<session_id>.state`.
 - Numeric fields default to `0` when absent. String fields default to empty string.
 - Lines are newline-terminated (`\n`).
 - Files are append-only.
+- Files are automatically rotated at 10,000 lines (keeps most recent 5,000) by the Python and Node.js statusline scripts.
+- Duplicate entries (same token count as previous line) are skipped to prevent file bloat.
 
 ## Legacy Format
 

package/docs/DEPLOYMENT.md

@@ -10,6 +10,8 @@ cc-context-stats is distributed through three channels:
 | PyPI         | `cc-context-stats`| `pip install cc-context-stats`       |
 | npm          | `cc-context-stats`| `npm install -g cc-context-stats`    |
 
+Both pip and npm installs provide the `claude-statusline` and `context-stats` CLI commands.
+
 ## Publishing to PyPI
 
 ```bash
@@ -40,21 +42,30 @@ npm publish
 
 The project uses GitHub Actions for automated releases (`.github/workflows/release.yml`):
 
-1. Create and push a version tag: `git tag v1.x.x && git push --tags`
-2. The release workflow automatically:
-   - Runs the full test suite
+1. Update versions in all locations (see Version Management below)
+2. Update `CHANGELOG.md` with the new version entry
+3. Create and push a version tag: `git tag v1.x.x && git push --tags`
+4. The release workflow automatically:
+   - Runs the full test suite (Python, Node.js, Bash)
    - Builds Python and npm packages
    - Creates a GitHub Release with release notes
 
+CI is also run on every push and PR via `.github/workflows/ci.yml`.
+
 ## Version Management
 
-Versions must be updated in sync across:
+Versions must be updated in sync across these files:
 
-- `pyproject.toml` - `[project] version`
-- `package.json` - `version`
-- `CHANGELOG.md` - New version entry
-- `RELEASE_NOTES.md` - Current release notes
+| File | Field |
+| --- | --- |
+| `pyproject.toml` | `[project] version` |
+| `package.json` | `version` |
+| `src/claude_statusline/__init__.py` | `__version__` |
+| `CHANGELOG.md` | New version entry |
+| `RELEASE_NOTES.md` | Current release notes |
 
 ## Install Script
 
 The `install.sh` script is fetched directly from the `main` branch on GitHub. Changes to the installer take effect immediately for new users running the curl one-liner.
+
+The installer embeds the version from `package.json` and the current git commit hash into the installed scripts, preventing version drift between the repository and installed copies.

package/docs/DEVELOPMENT.md

@@ -7,6 +7,7 @@
 - **Python 3.9+** - For Python package and testing
 - **Node.js 18+** - For Node.js script and testing
 - **Bats** - Bash Automated Testing System (optional, for bash tests)
+- **pre-commit** - Git hook framework (optional, for automated code quality)
 
 ## Setup
 
@@ -24,7 +25,7 @@ pip install -e ".[dev]"
 # Node.js setup
 npm install
 
-# Install pre-commit hooks
+# Install pre-commit hooks (optional but recommended)
 pre-commit install
 ```
 
@@ -33,30 +34,54 @@ pre-commit install
 ```
 cc-context-stats/
 ├── src/claude_statusline/    # Python package source
+│   ├── cli/                  #   CLI entry points (statusline, context-stats)
+│   ├── core/                 #   Config, state, git, colors
+│   ├── formatters/           #   Token, time, layout formatting
+│   ├── graphs/               #   ASCII graph rendering
+│   └── ui/                   #   Icons, waiting animation
 ├── scripts/                  # Standalone scripts (sh/py/js)
+│   ├── statusline-full.sh    #   Full-featured bash statusline
+│   ├── statusline-git.sh     #   Git-focused bash variant
+│   ├── statusline-minimal.sh #   Minimal bash variant
+│   ├── statusline.py         #   Python standalone statusline
+│   ├── statusline.js         #   Node.js standalone statusline
+│   └── context-stats.sh      #   Bash context-stats CLI
 ├── tests/
 │   ├── bash/                 # Bats tests
 │   ├── python/               # Pytest tests
 │   └── node/                 # Jest tests
 ├── config/                   # Configuration examples
 ├── docs/                     # Documentation
-├── .github/workflows/        # CI/CD
-├── pyproject.toml            # Python build config
+├── .github/workflows/        # CI/CD (ci.yml, release.yml)
+├── pyproject.toml            # Python build config (hatchling)
 └── package.json              # Node.js config
 ```
 
 ## Running Tests
 
 ```bash
+# Python tests
+source venv/bin/activate
+pytest tests/python/ -v
+
+# Node.js tests (Jest)
+npm test
+
+# Bash integration tests
+bats tests/bash/*.bats
+
 # All tests
-npm test && pytest && bats tests/bash/*.bats
-
-# Individual suites
-pytest tests/python/ -v                          # Python
-pytest tests/python/ -v --cov=scripts --cov-report=html  # Python + coverage
-npm test                                          # Node.js (Jest)
-npm run test:coverage                             # Node.js + coverage
-bats tests/bash/*.bats                           # Bash
+pytest && npm test && bats tests/bash/*.bats
+```
+
+### Coverage Reports
+
+```bash
+# Python coverage
+pytest tests/python/ -v --cov=scripts --cov-report=html
+
+# Node.js coverage
+npm run test:coverage
 ```
 
 ## Linting & Formatting
@@ -92,6 +117,9 @@ python -m build
 
 # Verify package
 twine check dist/*
+
+# npm dry run
+npm pack --dry-run
 ```
 
 ## Cross-Script Consistency
@@ -102,6 +130,8 @@ All three implementations (bash, Python, Node.js) must produce identical output
 2. Run integration tests to verify parity
 3. Test on multiple platforms if possible
 
+The delta parity tests (`tests/bash/`) verify that Python and Node.js produce identical deltas for the same CSV state data.
+
 ## Debugging
 
 ### State files
@@ -110,8 +140,11 @@ All three implementations (bash, Python, Node.js) must produce identical output
 # View current state files
 ls -la ~/.claude/statusline/statusline.*.state
 
-# Inspect state content
+# Inspect state content (14 CSV fields per line)
 cat ~/.claude/statusline/statusline.<session_id>.state
+
+# Watch state file updates in real-time
+watch -n 1 'tail -5 ~/.claude/statusline/statusline.*.state'
 ```
 
 ### Verbose testing
@@ -122,4 +155,7 @@ pytest tests/python/ -v -s
 
 # Node.js with verbose output
 npx jest --verbose
+
+# Bats with verbose output
+bats --verbose-run tests/bash/*.bats
 ```