cc-context-stats 1.6.2 → 1.7.0

package/CHANGELOG.md

@@ -7,6 +7,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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
 ```

package/docs/configuration.md

@@ -22,6 +22,10 @@ show_delta=false   # Disable delta display
 # Show session_id in status line
 show_session=true  # (default) Show session ID
 show_session=false # Hide session ID
+
+# Disable rotating text animations
+reduced_motion=false  # (default) Animations enabled
+reduced_motion=true   # Disable animations for accessibility
 ```
 
 ## Status Line Components
@@ -81,3 +85,34 @@ The session ID at the end helps:
 - Debug session-specific issues
 
 Double-click to select and copy. Set `show_session=false` to hide.
+
+## Custom Colors
+
+Override any status line color with named colors or hex codes:
+
+```bash
+# Available slots
+color_green=#7dcfff       # Context >50% free
+color_yellow=bright_yellow # Context 25-50% free
+color_red=#f7768e         # Context <25% free
+color_blue=bright_blue    # Directory name
+color_magenta=#bb9af7     # Git branch
+color_cyan=bright_cyan    # Git change count
+```
+
+### Supported color values
+
+**Named colors**: `black`, `red`, `green`, `yellow`, `blue`, `magenta`, `cyan`, `white`, `bright_black`, `bright_red`, `bright_green`, `bright_yellow`, `bright_blue`, `bright_magenta`, `bright_cyan`, `bright_white`
+
+**Hex colors**: Any `#rrggbb` value (requires terminal with 24-bit color support)
+
+Unrecognized color values are ignored with a warning to stderr. Omitted slots use defaults.
+
+## Config File Format
+
+The config file uses simple `key=value` syntax:
+
+- No spaces around `=`
+- Lines starting with `#` are comments
+- Unrecognized keys are ignored
+- Missing keys use defaults shown above

package/docs/context-stats.md

@@ -40,6 +40,17 @@ context-stats --type io          # Input/output token breakdown
 context-stats --type all         # Show all graphs
 ```
 
+### Diagnostic Dump
+
+The `explain` command shows how cc-context-stats interprets Claude Code's JSON context. Pipe any session JSON to stdin:
+
+```bash
+echo '{"model":{"display_name":"Opus"},...}' | context-stats explain
+echo '{"model":{"display_name":"Opus"},...}' | context-stats explain --no-color
+```
+
+Output includes model info, workspace, context window breakdown with derived values (free tokens, autocompact buffer), cost, session metadata, vim/agent extensions, active config, and raw JSON.
+
 ## Output
 
 ```
@@ -68,7 +79,7 @@ Session Summary
   Output Tokens:       43,429
   Session Duration:    2h 29m
 
-Powered by cc-context-stats v1.6.1 - https://github.com/luongnv89/cc-context-stats
+Powered by cc-context-stats v1.7.0 - https://github.com/luongnv89/cc-context-stats
 ```
 
 ## Features