cc-context-stats 1.5.0 → 1.6.0

package/assets/logo/logo-full.svg

@@ -1,30 +1,40 @@
-<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 xmlns="http://www.w3.org/2000/svg" viewBox="0 0 360 72" width="360" height="72">
+  <defs>
+    <linearGradient id="full-wave-grad" x1="0%" y1="0%" x2="100%" y2="0%">
+      <stop offset="0%" stop-color="#22C55E"/>
+      <stop offset="50%" stop-color="#E9AB34"/>
+      <stop offset="100%" stop-color="#EF4444"/>
+    </linearGradient>
+  </defs>
+
+  <!-- Background pill -->
+  <rect width="360" height="72" rx="14" fill="#1A1A1A"/>
+
+  <!-- Mark: Context wave in left area -->
+  <g transform="translate(8, 4)">
+    <!-- Context wave -->
+    <path d="M 10 48 C 16 48, 18 42, 22 40 C 26 38, 28 36, 32 32 C 36 28, 38 22, 42 18 C 46 14, 50 16, 54 14"
+          stroke="url(#full-wave-grad)" stroke-width="3.5" fill="none" stroke-linecap="round" stroke-linejoin="round"/>
+
+    <!-- Echo line -->
+    <path d="M 10 52 C 16 52, 18 46, 22 44 C 26 42, 28 40, 32 36 C 36 32, 38 26, 42 22 C 46 18, 50 20, 54 18"
+          stroke="url(#full-wave-grad)" stroke-width="1.5" fill="none" stroke-linecap="round" opacity="0.3"/>
+
+    <!-- Cursor dot -->
+    <circle cx="42" cy="18" r="3.5" fill="#E9AB34"/>
+    <circle cx="42" cy="18" r="6" fill="#E9AB34" opacity="0.15"/>
+
+    <!-- Baseline -->
+    <line x1="10" y1="54" x2="54" y2="54" stroke="#8B7D6B" stroke-width="1" stroke-linecap="round" opacity="0.4"/>
+  </g>
+
+  <!-- Divider -->
+  <line x1="76" y1="16" x2="76" y2="56" stroke="#8B7D6B" stroke-width="1" opacity="0.25"/>
+
+  <!-- Wordmark -->
+  <text x="90" y="35" font-family="'SF Mono', 'JetBrains Mono', 'Fira Code', 'Cascadia Code', monospace" font-size="22" font-weight="700" fill="#FFFFFF" letter-spacing="-0.3">cc-context</text>
+  <text x="90" y="55" font-family="'SF Mono', 'JetBrains Mono', 'Fira Code', 'Cascadia Code', monospace" font-size="15" font-weight="500" fill="#E9AB34" letter-spacing="3">stats</text>
+
+  <!-- Right accent bar -->
+  <rect x="348" y="20" width="2" height="32" rx="1" fill="#E9AB34" opacity="0.5"/>
 </svg>

package/assets/logo/logo-icon.svg

@@ -1,26 +1,27 @@
 <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"/>
+  <defs>
+    <linearGradient id="icon-wave-grad" x1="0%" y1="0%" x2="100%" y2="0%">
+      <stop offset="0%" stop-color="#22C55E"/>
+      <stop offset="50%" stop-color="#E9AB34"/>
+      <stop offset="100%" stop-color="#EF4444"/>
+    </linearGradient>
+  </defs>
 
-  <!-- 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"/>
+  <!-- Background -->
+  <rect width="512" height="512" rx="96" fill="#1A1A1A"/>
 
-  <!-- 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"/>
+  <!-- Context wave (scaled up) -->
+  <path d="M 96 376 C 144 376, 160 328, 192 312 C 224 296, 240 280, 272 248 C 304 216, 320 168, 352 136 C 384 104, 400 120, 432 104"
+        stroke="url(#icon-wave-grad)" stroke-width="24" fill="none" stroke-linecap="round" stroke-linejoin="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"/>
+  <!-- Echo line -->
+  <path d="M 96 408 C 144 408, 160 360, 192 344 C 224 328, 240 312, 272 280 C 304 248, 320 200, 352 168 C 384 136, 400 152, 432 136"
+        stroke="url(#icon-wave-grad)" stroke-width="10" fill="none" stroke-linecap="round" opacity="0.25"/>
 
-  <!-- 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"/>
+  <!-- Cursor dot -->
+  <circle cx="352" cy="136" r="28" fill="#E9AB34"/>
+  <circle cx="352" cy="136" r="48" fill="#E9AB34" opacity="0.12"/>
 
-  <!-- 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"/>
+  <!-- Baseline -->
+  <line x1="96" y1="424" x2="432" y2="424" stroke="#8B7D6B" stroke-width="6" stroke-linecap="round" opacity="0.35"/>
 </svg>

package/assets/logo/logo-mark.svg

@@ -1,26 +1,28 @@
 <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"/>
+  <defs>
+    <linearGradient id="wave-grad" x1="0%" y1="0%" x2="100%" y2="0%">
+      <stop offset="0%" stop-color="#22C55E"/>
+      <stop offset="50%" stop-color="#E9AB34"/>
+      <stop offset="100%" stop-color="#EF4444"/>
+    </linearGradient>
+  </defs>
 
-  <!-- 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"/>
+  <!-- Background -->
+  <rect width="64" height="64" rx="14" fill="#1A1A1A"/>
 
-  <!-- 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"/>
+  <!-- Context wave: a flowing curve rising from left (low usage) to right (high usage) -->
+  <!-- This represents the context growth graph - the core concept of the tool -->
+  <path d="M 10 48 C 16 48, 18 42, 22 40 C 26 38, 28 36, 32 32 C 36 28, 38 22, 42 18 C 46 14, 50 16, 54 14"
+        stroke="url(#wave-grad)" stroke-width="3.5" fill="none" stroke-linecap="round" stroke-linejoin="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"/>
+  <!-- Secondary pulse line (echo effect for depth) -->
+  <path d="M 10 52 C 16 52, 18 46, 22 44 C 26 42, 28 40, 32 36 C 36 32, 38 26, 42 22 C 46 18, 50 20, 54 18"
+        stroke="url(#wave-grad)" stroke-width="1.5" fill="none" stroke-linecap="round" opacity="0.3"/>
 
-  <!-- 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"/>
+  <!-- Cursor dot at the "current position" on the wave -->
+  <circle cx="42" cy="18" r="3.5" fill="#E9AB34"/>
+  <circle cx="42" cy="18" r="6" fill="#E9AB34" opacity="0.15"/>
 
-  <!-- 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"/>
+  <!-- Baseline -->
+  <line x1="10" y1="54" x2="54" y2="54" stroke="#8B7D6B" stroke-width="1" stroke-linecap="round" opacity="0.4"/>
 </svg>

package/assets/logo/logo-white.svg

@@ -1,23 +1,24 @@
-<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 -->
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 360 72" width="360" height="72">
+  <!-- White version for dark backgrounds — no background rectangle -->
 
-  <!-- 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"/>
+  <!-- Mark: Context wave -->
+  <g transform="translate(8, 4)">
+    <path d="M 10 48 C 16 48, 18 42, 22 40 C 26 38, 28 36, 32 32 C 36 28, 38 22, 42 18 C 46 14, 50 16, 54 14"
+          stroke="#FFFFFF" stroke-width="3.5" fill="none" stroke-linecap="round" stroke-linejoin="round"/>
+    <path d="M 10 52 C 16 52, 18 46, 22 44 C 26 42, 28 40, 32 36 C 36 32, 38 26, 42 22 C 46 18, 50 20, 54 18"
+          stroke="#FFFFFF" stroke-width="1.5" fill="none" stroke-linecap="round" opacity="0.25"/>
+    <circle cx="42" cy="18" r="3.5" fill="#FFFFFF"/>
+    <circle cx="42" cy="18" r="6" fill="#FFFFFF" opacity="0.12"/>
+    <line x1="10" y1="54" x2="54" y2="54" stroke="#FFFFFF" stroke-width="1" stroke-linecap="round" opacity="0.3"/>
+  </g>
 
   <!-- Divider -->
-  <line x1="68" y1="12" x2="68" y2="52" stroke="rgba(255,255,255,0.2)" stroke-width="1"/>
+  <line x1="76" y1="16" x2="76" y2="56" stroke="#FFFFFF" stroke-width="1" opacity="0.2"/>
 
-  <!-- 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>
+  <!-- Wordmark -->
+  <text x="90" y="35" font-family="'SF Mono', 'JetBrains Mono', 'Fira Code', 'Cascadia Code', monospace" font-size="22" font-weight="700" fill="#FFFFFF" letter-spacing="-0.3">cc-context</text>
+  <text x="90" y="55" font-family="'SF Mono', 'JetBrains Mono', 'Fira Code', 'Cascadia Code', monospace" font-size="15" font-weight="500" fill="#FFFFFF" letter-spacing="3" opacity="0.7">stats</text>
+
+  <!-- Right accent bar -->
+  <rect x="348" y="20" width="2" height="32" rx="1" fill="#FFFFFF" opacity="0.4"/>
 </svg>

package/assets/logo/logo-wordmark.svg

@@ -1,7 +1,6 @@
-<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 xmlns="http://www.w3.org/2000/svg" viewBox="0 0 260 52" width="260" height="52">
+  <!-- Wordmark only — transparent background -->
+  <!-- "cc-context" bold, "stats" in golden amber below -->
+  <text x="0" y="30" font-family="'SF Mono', 'JetBrains Mono', 'Fira Code', 'Cascadia Code', monospace" font-size="24" font-weight="700" fill="#1A1A1A" letter-spacing="-0.3">cc-context</text>
+  <text x="0" y="48" font-family="'SF Mono', 'JetBrains Mono', 'Fira Code', 'Cascadia Code', monospace" font-size="15" font-weight="500" fill="#E9AB34" letter-spacing="3">stats</text>
 </svg>

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
+```

package/docs/DEPLOYMENT.md

@@ -0,0 +1,60 @@
+# Deployment
+
+## Distribution Channels
+
+cc-context-stats is distributed through three channels:
+
+| Channel      | Package Name      | Command                              |
+| ------------ | ----------------- | ------------------------------------ |
+| Shell script | N/A               | `curl -fsSL .../install.sh \| bash`  |
+| PyPI         | `cc-context-stats`| `pip install cc-context-stats`       |
+| npm          | `cc-context-stats`| `npm install -g cc-context-stats`    |
+
+## Publishing to PyPI
+
+```bash
+# Ensure clean build
+rm -rf dist/ build/
+
+# Build
+python -m build
+
+# Check package
+twine check dist/*
+
+# Upload to PyPI
+twine upload dist/*
+```
+
+## Publishing to npm
+
+```bash
+# Verify package.json
+npm pack --dry-run
+
+# Publish
+npm publish
+```
+
+## Release Workflow
+
+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
+   - Builds Python and npm packages
+   - Creates a GitHub Release with release notes
+
+## Version Management
+
+Versions must be updated in sync across:
+
+- `pyproject.toml` - `[project] version`
+- `package.json` - `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.

package/docs/DEVELOPMENT.md

@@ -0,0 +1,125 @@
+# Development Guide
+
+## Prerequisites
+
+- **Git** - Version control
+- **jq** - JSON processor (for bash scripts)
+- **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)
+
+## Setup
+
+```bash
+# Clone the repository
+git clone https://github.com/luongnv89/cc-context-stats.git
+cd cc-context-stats
+
+# Python setup
+python3 -m venv venv
+source venv/bin/activate
+pip install -r requirements-dev.txt
+pip install -e ".[dev]"
+
+# Node.js setup
+npm install
+
+# Install pre-commit hooks
+pre-commit install
+```
+
+## Project Layout
+
+```
+cc-context-stats/
+├── src/claude_statusline/    # Python package source
+├── scripts/                  # Standalone scripts (sh/py/js)
+├── tests/
+│   ├── bash/                 # Bats tests
+│   ├── python/               # Pytest tests
+│   └── node/                 # Jest tests
+├── config/                   # Configuration examples
+├── docs/                     # Documentation
+├── .github/workflows/        # CI/CD
+├── pyproject.toml            # Python build config
+└── package.json              # Node.js config
+```
+
+## Running Tests
+
+```bash
+# 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
+```
+
+## Linting & Formatting
+
+```bash
+# Run all checks via pre-commit
+pre-commit run --all-files
+
+# Individual tools
+ruff check src/ scripts/statusline.py            # Python lint
+ruff format src/ scripts/statusline.py           # Python format
+npx eslint scripts/statusline.js                 # JavaScript lint
+npx prettier --write scripts/statusline.js       # JavaScript format
+shellcheck scripts/*.sh install.sh               # Bash lint
+```
+
+## Manual Testing
+
+```bash
+# Test statusline scripts with mock input
+echo '{"model":{"display_name":"Test"},"cwd":"/test","session_id":"abc123","context":{"tokens_remaining":64000,"context_window":200000}}' | python3 scripts/statusline.py
+
+echo '{"model":{"display_name":"Test"}}' | node scripts/statusline.js
+
+echo '{"model":{"display_name":"Test"}}' | bash scripts/statusline-full.sh
+```
+
+## Building
+
+```bash
+# Python package
+python -m build
+
+# Verify package
+twine check dist/*
+```
+
+## Cross-Script Consistency
+
+All three implementations (bash, Python, Node.js) must produce identical output for the same input. When modifying status line behavior:
+
+1. Update all three script variants
+2. Run integration tests to verify parity
+3. Test on multiple platforms if possible
+
+## Debugging
+
+### State files
+
+```bash
+# View current state files
+ls -la ~/.claude/statusline/statusline.*.state
+
+# Inspect state content
+cat ~/.claude/statusline/statusline.<session_id>.state
+```
+
+### Verbose testing
+
+```bash
+# Python with verbose output
+pytest tests/python/ -v -s
+
+# Node.js with verbose output
+npx jest --verbose
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cc-context-stats",
-  "version": "1.5.0",
+  "version": "1.6.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": {
@@ -32,7 +32,7 @@
   "devDependencies": {
     "eslint": "^8.56.0",
     "jest": "^29.7.0",
-    "prettier": "^3.2.0"
+    "prettier": "^3.8.1"
   },
   "engines": {
     "node": ">=18"

package/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "cc-context-stats"
-version = "1.5.0"
+version = "1.6.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" }

package/scripts/statusline-full.sh

@@ -116,13 +116,21 @@ visible_width() {
 }
 
 get_terminal_width() {
-    # Return terminal width, fallback to 80
+    # Return terminal width for fit_to_width truncation.
+    # When running inside Claude Code's statusline subprocess, neither $COLUMNS
+    # nor tput can detect the real terminal width (they always return 80).
+    # If COLUMNS is explicitly set, trust it. Otherwise use 200 as default
+    # so no parts are unnecessarily dropped; Claude Code handles overflow.
     if [[ -n "$COLUMNS" ]]; then
         echo "$COLUMNS"
     else
         local cols
         cols=$(tput cols 2>/dev/null || echo 80)
-        echo "$cols"
+        if [[ "$cols" -eq 80 ]]; then
+            echo 200
+        else
+            echo "$cols"
+        fi
     fi
 }
 
@@ -170,7 +178,7 @@ cost_usd=$(echo "$input" | jq -r '.cost.total_cost_usd // 0')
 lines_added=$(echo "$input" | jq -r '.cost.total_lines_added // 0')
 lines_removed=$(echo "$input" | jq -r '.cost.total_lines_removed // 0')
 model_id=$(echo "$input" | jq -r '.model.id // ""')
-workspace_project_dir=$(echo "$input" | jq -r '.workspace.project_dir // ""')
+workspace_project_dir=$(echo "$input" | jq -r '.workspace.project_dir // ""' | tr ',' '_')
 
 if [[ "$total_size" -gt 0 && "$current_usage" != "null" ]]; then
     # Get tokens from current_usage (includes cache)