cc-context-stats 1.5.1 → 1.6.0

package/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,49 @@
+---
+name: Bug Report
+about: Report a bug to help us improve
+title: '[BUG] '
+labels: bug
+assignees: ''
+---
+
+## Bug Description
+
+A clear and concise description of what the bug is.
+
+## Steps to Reproduce
+
+1. Install cc-context-stats via '...'
+2. Run '...'
+3. See error
+
+## Expected Behavior
+
+A clear and concise description of what you expected to happen.
+
+## Actual Behavior
+
+What actually happened instead.
+
+## Screenshots
+
+If applicable, add screenshots to help explain your problem.
+
+## Environment
+
+- OS: [e.g., macOS 14.0, Ubuntu 22.04, Windows 11]
+- Shell: [e.g., zsh, bash, PowerShell]
+- cc-context-stats version: [e.g., 1.6.0]
+- Installation method: [npm, pip, shell script]
+- Node.js version: [if applicable]
+- Python version: [if applicable]
+- Claude Code version: [if applicable]
+
+## Additional Context
+
+Add any other context about the problem here.
+
+## State File Content (if relevant)
+
+```
+# Paste output of: cat ~/.claude/statusline/statusline.*.state
+```

package/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,31 @@
+---
+name: Feature Request
+about: Suggest an idea for this project
+title: '[FEATURE] '
+labels: enhancement
+assignees: ''
+---
+
+## Problem Statement
+
+A clear and concise description of what the problem is.
+Ex. I'm always frustrated when [...]
+
+## Proposed Solution
+
+A clear and concise description of what you want to happen.
+
+## Alternatives Considered
+
+A clear and concise description of any alternative solutions or features you've considered.
+
+## Use Cases
+
+Describe specific use cases where this feature would be beneficial:
+
+1. Use case 1
+2. Use case 2
+
+## Additional Context
+
+Add any other context, mockups, or screenshots about the feature request here.

package/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,33 @@
+## Description
+
+Brief description of the changes in this PR.
+
+## Related Issue
+
+Fixes #(issue number)
+
+## Type of Change
+
+- [ ] Bug fix (non-breaking change which fixes an issue)
+- [ ] New feature (non-breaking change which adds functionality)
+- [ ] Breaking change (fix or feature that would cause existing functionality to change)
+- [ ] Documentation update
+- [ ] Refactoring (no functional changes)
+
+## Checklist
+
+- [ ] My code follows the project's style guidelines
+- [ ] I have performed a self-review of my code
+- [ ] I have made corresponding changes to the documentation
+- [ ] My changes generate no new warnings
+- [ ] I have added tests that prove my fix is effective or that my feature works
+- [ ] New and existing unit tests pass locally with my changes
+- [ ] All three implementations (bash, Python, Node.js) produce consistent output (if applicable)
+
+## Screenshots (if applicable)
+
+Add screenshots to help explain your changes.
+
+## Additional Notes
+
+Any additional information that reviewers should know.

package/.github/workflows/ci.yml

@@ -183,6 +183,42 @@ jobs:
           flags: node
           fail_ci_if_error: false
 
+  # ============================================
+  # CROSS-IMPLEMENTATION PARITY TESTS
+  # ============================================
+  parity-test:
+    name: Parity Tests (${{ matrix.os }})
+    needs: [python-test, node-test]
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Install Bats
+        run: |
+          if [[ "$RUNNER_OS" == "Linux" ]]; then
+            sudo apt-get update && sudo apt-get install -y bats
+          elif [[ "$RUNNER_OS" == "macOS" ]]; then
+            brew install bats-core
+          fi
+
+      - name: Run parity tests
+        run: bats tests/bash/test_parity.bats
+
   # ============================================
   # INTEGRATION TESTS
   # ============================================
@@ -238,7 +274,7 @@ jobs:
   # ============================================
   ci-success:
     name: CI Success
-    needs: [bash-lint, bash-test, python-lint, python-test, node-lint, node-test, integration-test]
+    needs: [bash-lint, bash-test, python-lint, python-test, node-lint, node-test, integration-test, parity-test]
     runs-on: ubuntu-latest
     if: always()
     steps:
@@ -250,7 +286,8 @@ jobs:
              [[ "${{ needs.python-test.result }}" != "success" ]] || \
              [[ "${{ needs.node-lint.result }}" != "success" ]] || \
              [[ "${{ needs.node-test.result }}" != "success" ]] || \
-             [[ "${{ needs.integration-test.result }}" != "success" ]]; then
+             [[ "${{ needs.integration-test.result }}" != "success" ]] || \
+             [[ "${{ needs.parity-test.result }}" != "success" ]]; then
             echo "One or more jobs failed"
             exit 1
           fi

package/CHANGELOG.md

@@ -7,22 +7,30 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.6.0] - 2026-03-13
+
 ### Added
 
+- **CLI `--version` flag** - `context-stats --version` / `-V` now prints the current version
+- **State file rotation** - Automatic rotation at 10,000 lines (keeps most recent 5,000) to prevent unbounded file growth
+- **Session ID validation** - Rejects path-traversal characters (`/`, `\`, `..`, null bytes) for security
+- **Git command timeout** - 5-second timeout on git operations in both Python and Node.js implementations
+- **Core data pipeline unit tests** - 51 tests across 6 classes covering config, state, formatters, graph, and CLI
+- **Cross-implementation parity test** - Ensures Python and Node.js statusline scripts produce consistent output
+- **Stderr warnings** - Critical error paths now emit warnings to stderr for debugging
+- **CSV format documentation** - Formal specification of the 14-field state file format
+- **Comma guard for workspace paths** - Commas in `workspace_project_dir` are replaced with underscores before CSV write
+- **Open-source standard files** - Added CODE_OF_CONDUCT.md, CONTRIBUTING.md, SECURITY.md, and GitHub issue/PR templates
 - **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
+
+### Dependencies
+
+- Bumped prettier from 3.7.4 to 3.8.0
 
 ## [1.2.0] - 2025-01-08
 

package/CLAUDE.md

@@ -0,0 +1,54 @@
+# CLAUDE.md
+
+## Project Purpose
+
+cc-context-stats provides real-time context window monitoring for Claude Code sessions. It tracks token consumption over time and displays live ASCII graphs so users can see how much context remains.
+
+## Dual-Implementation Rationale
+
+The statusline is implemented in three languages (Bash, Python, Node.js) so users can choose whichever runtime they have available. Claude Code invokes the statusline script via stdin JSON pipe — any implementation that reads JSON from stdin and writes formatted text to stdout works. The Python and Node.js implementations also persist state to CSV files read by the `context-stats` CLI.
+
+## CSV Format Contract
+
+State files are append-only CSV at `~/.claude/statusline/statusline.<session_id>.state` with 14 comma-separated fields. See [docs/CSV_FORMAT.md](docs/CSV_FORMAT.md) for the full field specification. Key constraint: `workspace_project_dir` has commas replaced with underscores before writing.
+
+## Statusline Script Landscape
+
+| Script | Language | State writes | Notes |
+|---|---|---|---|
+| `scripts/statusline-full.sh` | Bash | No | Full display, requires `jq` |
+| `scripts/statusline-git.sh` | Bash | No | Git-focused variant |
+| `scripts/statusline-minimal.sh` | Bash | No | Minimal variant |
+| `scripts/statusline.py` | Python 3 | Yes | Pip-installable via package |
+| `scripts/statusline.js` | Node.js | Yes | Standalone script |
+
+## Test Commands
+
+```bash
+# Python tests
+source venv/bin/activate
+pytest tests/python/ -v
+
+# Node.js tests
+npm test
+
+# Bash integration tests
+bats tests/bash/*.bats
+
+# All tests
+pytest && npm test && bats tests/bash/*.bats
+```
+
+## Key Architectural Decisions
+
+- **Append-only CSV state files** with rotation at 10,000 lines (keeps most recent 5,000)
+- **No network requests** — all data stays local in `~/.claude/statusline/`
+- **Session ID validation** — rejects `/`, `\`, `..`, and null bytes for path-traversal defense
+- **5-second git command timeout** in both Python and Node.js implementations
+- **Config via `~/.claude/statusline.conf`** — simple key=value pairs
+
+## Cross-References
+
+- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) — system architecture and data flow
+- [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) — setup, testing, and contribution guide
+- [docs/CSV_FORMAT.md](docs/CSV_FORMAT.md) — state file field specification

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,59 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity
+and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes
+* Focusing on what is best for the overall community
+
+Examples of unacceptable behavior:
+
+* The use of sexualized language or imagery, and sexual attention or advances
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information without explicit permission
+* Other conduct which could reasonably be considered inappropriate
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+luongnv89@gmail.com.
+
+All complaints will be reviewed and investigated promptly and fairly.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.0, available at
+https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
+
+[homepage]: https://www.contributor-covenant.org

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Nguyen Luong
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -177,9 +177,18 @@ Context Stats hooks into Claude Code's state files to track token usage across y
 - [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
+- [Architecture](docs/ARCHITECTURE.md) - System design and components
+- [Development](docs/DEVELOPMENT.md) - Dev setup and debugging
+- [Deployment](docs/DEPLOYMENT.md) - Publishing and release process
 - [Troubleshooting](docs/troubleshooting.md) - Common issues
 - [Changelog](CHANGELOG.md) - Version history
 
+## Contributing
+
+Contributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md) for details on the development setup, branching strategy, and PR process.
+
+This project follows the [Contributor Covenant Code of Conduct](CODE_OF_CONDUCT.md).
+
 ## Migration from cc-statusline
 
 If you were using the previous `cc-statusline` package:

package/RELEASE_NOTES.md

@@ -1,10 +1,19 @@
-## v1.5.1 — 2026-03-11
+## v1.6.0 — 2026-03-13
 
-### 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
+### Features
+- **CLI `--version` flag** — `context-stats --version` / `-V` now prints the current version
+- **State file rotation** — Automatic rotation at 10,000 lines (keeps most recent 5,000) to prevent unbounded file growth
+- **Session ID validation** — Rejects path-traversal characters (`/`, `\`, `..`, null bytes) for security
+- **Git command timeout** — 5-second timeout on git operations in both Python and Node.js implementations
+- **Core data pipeline unit tests** — 51 tests across 6 classes covering config, state, formatters, graph, and CLI
+- **Cross-implementation parity test** — Ensures Python and Node.js statusline scripts produce consistent output
+- **Stderr warnings** — Critical error paths now emit warnings to stderr for debugging
+- **CSV format documentation** — Formal specification of the 14-field state file format
+- **Comma guard for workspace paths** — Commas in `workspace_project_dir` are replaced with underscores before CSV write
+- **Open-source standard files** — Added CODE_OF_CONDUCT.md, CONTRIBUTING.md, SECURITY.md, and GitHub issue/PR templates
+- **NPM Package** — `cc-context-stats` now available on npm for JavaScript/Node.js environments
 
-### Other Changes
-- Update logo SVG assets
+### Dependencies
+- Bumped prettier from 3.7.4 to 3.8.0
 
-**Full Changelog**: https://github.com/luongnv89/cc-context-stats/compare/v1.5.0...v1.5.1
+**Full Changelog**: https://github.com/luongnv89/cc-context-stats/compare/v1.5.1...v1.6.0

package/SECURITY.md

@@ -0,0 +1,44 @@
+# Security Policy
+
+## Supported Versions
+
+| Version | Supported          |
+| ------- | ------------------ |
+| 1.5.x   | :white_check_mark: |
+| < 1.5   | :x:                |
+
+## Reporting a Vulnerability
+
+We take security vulnerabilities seriously. If you discover a security issue, please report it responsibly.
+
+### How to Report
+
+1. **Do NOT** open a public GitHub issue for security vulnerabilities
+2. Email your findings to luongnv89@gmail.com
+3. Include detailed steps to reproduce the vulnerability
+4. Allow up to 48 hours for an initial response
+
+### What to Include
+
+- Type of vulnerability
+- Full paths of affected source files
+- Location of the affected source code (tag/branch/commit or direct URL)
+- Step-by-step instructions to reproduce
+- Proof-of-concept or exploit code (if possible)
+- Impact of the issue
+
+### What to Expect
+
+- Acknowledgment of your report within 48 hours
+- Regular updates on our progress
+- Credit in the security advisory (if desired)
+- Notification when the issue is fixed
+
+## Security Best Practices
+
+When contributing to this project:
+
+- Never commit secrets, API keys, or credentials
+- Use environment variables for sensitive configuration
+- Follow secure coding practices
+- Report any security concerns immediately

package/TODOS.md

@@ -0,0 +1,72 @@
+# TODOs
+
+Items identified from the HOLD SCOPE mega review (2026-03-12).
+
+## P1 — High Priority
+
+### ~~1. Cross-implementation parity test~~ ✅ Done
+**What:** Add a CI integration test that feeds identical JSON to both Python (`statusline.py`) and Node.js (`statusline.js`) scripts and asserts they write identical CSV state lines and produce equivalent stdout.
+**Why:** The two implementations share no code or schema contract. Drift has occurred before and will occur again. This catches it automatically.
+**Effort:** S
+**Depends on:** None
+**Status:** Implemented in `tests/bash/test_parity.bats` with CI job in `.github/workflows/ci.yml`. Archived as `openspec/changes/archive/2026-03-12-cross-impl-parity-test/`.
+
+### ~~2. Document CSV state file format + comma guard~~ ✅ Done
+**What:** Create `docs/CSV_FORMAT.md` documenting all 14 fields with types and examples. Fix `docs/ARCHITECTURE.md` which incorrectly states "each line is a JSON record." Sanitize `workspace_project_dir` to strip/escape commas before CSV serialization (in both Python and Node.js).
+**Why:** The CSV format is an implicit contract across 5 writer implementations with zero documentation. Commas in directory paths silently corrupt rows.
+**Effort:** S
+**Depends on:** None
+**Status:** Created `docs/CSV_FORMAT.md`, fixed ARCHITECTURE.md JSON→CSV, added comma→underscore guard in Python (`state.py`, `statusline.py`), Node.js (`statusline.js`), and bash (`statusline-full.sh`). Parity test with comma fixture passes. Archived as `openspec/changes/archive/2026-03-12-csv-format-doc-comma-guard/`.
+
+### ~~3. Stderr logging for critical error paths~~ ✅ Done
+**What:** Replace `except OSError: pass` with `sys.stderr.write()` warnings in: `StateFile.append_entry()`, `Config._create_default()`, `Config._read_config()`. Add `UnicodeDecodeError` to config read exception handling. Apply equivalent changes in `statusline.js`.
+**Why:** State write failures cause silent data loss — users see stale dashboards with no indication of why. Statusline output goes to stdout (consumed by Claude Code), so stderr is safe for diagnostics.
+**Effort:** S
+**Depends on:** None
+**Status:** Added `[statusline] warning:` stderr messages to all critical data pipeline error handlers in `config.py`, `state.py`, `statusline.py`, and `statusline.js`. Added `UnicodeDecodeError` to config read exception handling in both Python files. Non-critical handlers (git info, file migration) left silent.
+
+### ~~4. Core data pipeline unit tests~~ ✅ Done
+**What:** Add test files covering: (1) `StateEntry.from_csv_line` ↔ `to_csv_line` round-trip, (2) `calculate_deltas` and `detect_spike`, (3) zone threshold logic in `render_summary`. Cover edge cases: empty data, single entry, negative deltas, boundary percentages (39%/40%/79%/80%).
+**Why:** The primary user-facing feature (`context-stats` CLI) has zero unit tests on its core logic — CSV parsing, statistics, and zone detection are all untested.
+**Effort:** M
+**Depends on:** None
+**Status:** Implemented in `tests/python/test_data_pipeline.py` with 51 tests across 6 classes: TestStateEntryRoundTrip (14), TestStateEntryProperties (3), TestCalculateDeltas (8), TestCalculateStats (6), TestDetectSpike (10), TestZoneThresholds (10). Covers CSV round-trip with old/new formats, comma sanitization, boundary spike detection (exact 15%/3x thresholds), and zone boundaries at 39/40% and 79/80%.
+
+## P2 — Medium Priority
+
+### ~~5. State file cap + rotate~~ ✅ Done
+**What:** After `StateFile.append_entry()`, check line count. If >10,000 lines, truncate to the most recent 5,000. Apply in both Python and Node.js writers.
+**Why:** State files are append-only with no rotation. `read_history()` loads entire files into memory. Heavy users could accumulate 50k+ lines across long sessions.
+**Effort:** S
+**Depends on:** None
+**Status:** Added `_maybe_rotate()` to Python `StateFile` and `maybeRotateStateFile()` to Node.js `statusline.js`. Both use atomic temp-file + rename. Threshold: 10,000 lines, retain: 5,000 lines. Unit tests in `tests/python/test_state_rotation_validation.py` and `tests/node/rotation.test.js`.
+
+### ~~6. Sanitize session_id input~~ ✅ Done
+**What:** Reject session IDs containing `/`, `\`, or `..` at the CLI entry point (`parse_args`) and in `StateFile.__init__()`. Print a clear error message and exit.
+**Why:** Defense-in-depth against path traversal via `context-stats ../../etc/passwd`. Claude Code generates safe UUIDs, but the CLI accepts arbitrary user input.
+**Effort:** XS
+**Depends on:** None
+**Status:** Added `_validate_session_id()` helper in `state.py`, called in `StateFile.__init__()` and `parse_args()` in `context_stats.py`. Rejects `/`, `\`, `..`, and null bytes. Unit tests and CLI subprocess tests in `tests/python/test_state_rotation_validation.py`.
+
+### ~~7. Node.js git command timeout~~ ✅ Done
+**What:** Add `timeout: 5000` to both `execSync` calls in `statusline.js` `getGitInfo()`.
+**Why:** Python's `get_git_info()` has `timeout=5`. Node.js has none — git hangs (network FS, large repo) would block the statusline process indefinitely.
+**Effort:** XS
+**Depends on:** None
+**Status:** Added `timeout: 5000` to both `execSync` calls (`git rev-parse` and `git status`) in `getGitInfo()` in `scripts/statusline.js`.
+
+### ~~8. Repo-level CLAUDE.md~~ ✅ Done
+**What:** Create `CLAUDE.md` at repo root documenting: project purpose, dual-implementation rationale, CSV format contract, test running instructions (`pytest`, `npm test`, `bats`), key architectural decisions, and the 5-script statusline landscape.
+**Why:** Helps AI assistants and new contributors understand the project quickly. Currently the only CLAUDE.md is the user's personal global one.
+**Effort:** S
+**Depends on:** TODO 2 (CSV format doc) for cross-reference
+**Status:** Created `CLAUDE.md` at repo root with all required sections. Cross-references `docs/ARCHITECTURE.md`, `docs/DEVELOPMENT.md`, and `docs/CSV_FORMAT.md`.
+
+## P3 — Low Priority
+
+### ~~9. Add --version flag to context-stats CLI~~ ✅ Done
+**What:** Add `--version` argument to `parse_args()` that prints `cc-context-stats {version}` and exits.
+**Why:** Users can't determine installed version without running the full tool. The footer shows version but only on successful render.
+**Effort:** XS
+**Depends on:** None
+**Status:** Added `--version` / `-V` flag to `parse_args()` in `context_stats.py`. Prints `cc-context-stats {__version__}` and exits. Updated help text and module docstring.

package/docs/ARCHITECTURE.md

@@ -0,0 +1,101 @@
+# Architecture
+
+## Overview
+
+cc-context-stats provides real-time context monitoring for Claude Code sessions. It consists of two main components:
+
+1. **Status Line** - A compact one-line display integrated into Claude Code's UI
+2. **Context Stats CLI** - A live terminal dashboard with ASCII graphs
+
+## System Architecture
+
+```
+┌─────────────┐     JSON stdin      ┌──────────────────┐
+│ Claude Code  │ ──────────────────> │ Statusline Script │
+│   (host)     │ <────────────────── │  (sh/py/js)       │
+└─────────────┘     stdout text     └──────┬───────────┘
+                                           │ writes
+                                           ▼
+                                    ┌──────────────────┐
+                                    │  State Files      │
+                                    │  ~/.claude/       │
+                                    │  statusline/      │
+                                    └──────┬───────────┘
+                                           │ reads
+                                           ▼
+                                    ┌──────────────────┐
+                                    │ Context Stats CLI │
+                                    │  (Python)         │
+                                    └──────────────────┘
+```
+
+## Component Details
+
+### Status Line Scripts
+
+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         |
+
+**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`
+6. Script outputs formatted ANSI text to stdout
+
+### Python Package (`src/claude_statusline/`)
+
+The pip-installable package provides both the statusline and context-stats CLI:
+
+```
+src/claude_statusline/
+├── __init__.py
+├── __main__.py
+├── cli/
+│   ├── 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
+├── formatters/
+│   ├── 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
+└── ui/
+    ├── icons.py           # Unicode icons
+    └── waiting.py         # Waiting animation
+```
+
+### State Files
+
+State files persist token history between statusline refreshes:
+
+```
+~/.claude/statusline/statusline.<session_id>.state
+```
+
+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.
+
+## Data Privacy
+
+All data stays local:
+- State files are written to `~/.claude/statusline/`
+- No network requests are made
+- No telemetry or analytics
+
+## Configuration
+
+User preferences are stored in `~/.claude/statusline.conf` as simple `key=value` pairs. See [Configuration](configuration.md) for details.

package/docs/CSV_FORMAT.md

@@ -0,0 +1,40 @@
+# CSV State File Format
+
+State files are stored at `~/.claude/statusline/statusline.<session_id>.state`. Each line is a CSV record with 14 comma-separated fields.
+
+## Field Specification
+
+| Index | Field | Type | Description |
+|-------|-------|------|-------------|
+| 0 | `timestamp` | integer | Unix timestamp in seconds |
+| 1 | `total_input_tokens` | integer | Cumulative input tokens for the session |
+| 2 | `total_output_tokens` | integer | Cumulative output tokens for the session |
+| 3 | `current_input_tokens` | integer | Input tokens for the current request |
+| 4 | `current_output_tokens` | integer | Output tokens for the current request |
+| 5 | `cache_creation` | integer | Cache creation input tokens |
+| 6 | `cache_read` | integer | Cache read input tokens |
+| 7 | `cost_usd` | float | Total session cost in USD |
+| 8 | `lines_added` | integer | Total lines added in session |
+| 9 | `lines_removed` | integer | Total lines removed in session |
+| 10 | `session_id` | string | Session identifier (UUID) |
+| 11 | `model_id` | string | Model identifier (e.g., `claude-opus-4-5`) |
+| 12 | `workspace_project_dir` | string | Project directory path (commas replaced with underscores) |
+| 13 | `context_window_size` | integer | Context window size in tokens |
+
+## Constraints
+
+- Fields are separated by commas with no quoting or escaping.
+- The `workspace_project_dir` field (index 12) is sanitized before writing: all comma characters (`,`) are replaced with underscores (`_`) to prevent CSV corruption.
+- Numeric fields default to `0` when absent. String fields default to empty string.
+- Lines are newline-terminated (`\n`).
+- Files are append-only.
+
+## Legacy Format
+
+Older state files may contain 2-field lines: `timestamp,total_input_tokens`. The reader defaults all other fields to zero/empty for these lines.
+
+## Example
+
+```
+1710288000,75000,8500,50000,5000,10000,20000,0.05234,250,45,abc-123-def,claude-opus-4-5,/home/user/my-project,200000
+```