cc-context-stats 1.3.0

package/config/settings-example.json

@@ -0,0 +1,7 @@
+{
+  "statusLine": {
+    "type": "command",
+    "command": "~/.claude/statusline.sh",
+    "padding": 0
+  }
+}

package/config/settings-node.json

@@ -0,0 +1,7 @@
+{
+  "statusLine": {
+    "type": "command",
+    "command": "~/.claude/statusline.js",
+    "padding": 0
+  }
+}

package/config/settings-python.json

@@ -0,0 +1,7 @@
+{
+  "statusLine": {
+    "type": "command",
+    "command": "~/.claude/statusline.py",
+    "padding": 0
+  }
+}

package/docs/configuration.md

@@ -0,0 +1,83 @@
+# Configuration
+
+The configuration file `~/.claude/statusline.conf` is automatically created with default settings on first run.
+
+Windows location: `%USERPROFILE%\.claude\statusline.conf`
+
+## Settings
+
+```bash
+# Autocompact setting - sync with Claude Code's /config
+autocompact=true   # (default) Show reserved buffer for compacting
+autocompact=false  # When autocompact is disabled via /config
+
+# Token display format
+token_detail=true  # (default) Show exact token count: 64,000 free
+token_detail=false # Show abbreviated tokens: 64.0k free
+
+# Show token delta since last refresh
+show_delta=true    # (default) Show delta like [+2,500]
+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
+```
+
+## Status Line Components
+
+```
+[Opus 4.5] my-project | main [3] | 64,000 free (32.0%) [+2,500] [AC:45k] session_id
+```
+
+| Component     | Description              | Color            |
+| ------------- | ------------------------ | ---------------- |
+| `[Opus 4.5]`  | Current AI model         | Dim              |
+| `my-project`  | Current directory        | Blue             |
+| `main`        | Git branch               | Magenta          |
+| `[3]`         | Uncommitted changes      | Cyan             |
+| `64,000 free` | Available tokens         | Green/Yellow/Red |
+| `(32.0%)`     | Context usage percentage | -                |
+| `[+2,500]`    | Token delta              | -                |
+| `[AC:45k]`    | Autocompact buffer       | Dim              |
+| `session_id`  | Current session          | Dim              |
+
+## Token Colors
+
+Context availability is color-coded:
+
+| Availability | Color  |
+| ------------ | ------ |
+| > 50%        | Green  |
+| > 25%        | Yellow |
+| <= 25%       | Red    |
+
+## Autocompact Display
+
+- `[AC:45k]` - Autocompact enabled, 45k tokens reserved
+- `[AC:off]` - Autocompact disabled
+
+## Token Display Formats
+
+| Setting              | Display                          |
+| -------------------- | -------------------------------- |
+| `token_detail=true`  | `64,000 free (32.0%)` `[+2,500]` |
+| `token_detail=false` | `64.0k free (32.0%)` `[+2.5k]`   |
+
+## Token Delta
+
+The `[+X,XXX]` indicator shows tokens consumed since last refresh:
+
+- Only positive deltas are shown
+- First run shows no delta (no baseline yet)
+- Each session has its own state file to avoid conflicts
+
+## Session ID
+
+The session ID at the end helps:
+
+- Identify sessions when running multiple Claude Code instances
+- Correlate logs with specific sessions
+- Debug session-specific issues
+
+Double-click to select and copy. Set `show_session=false` to hide.

package/docs/context-stats.md

@@ -0,0 +1,132 @@
+# Context Stats
+
+Real-time context monitoring for Claude Code sessions. Know when you're in the Smart Zone, Dumb Zone, or Wrap Up Zone.
+
+## Context Zones
+
+Context Stats tracks your context usage and warns you as performance degrades:
+
+| Zone                | Context Used | Status   | Message                                         |
+| ------------------- | ------------ | -------- | ----------------------------------------------- |
+| 🟢 **Smart Zone**   | < 40%        | Optimal  | "You are in the smart zone"                     |
+| 🟡 **Dumb Zone**    | 40-80%       | Degraded | "You are in the dumb zone - Dex Horthy says so" |
+| 🔴 **Wrap Up Zone** | > 80%        | Critical | "Better to wrap up and start a new session"     |
+
+## Usage
+
+By default, `context-stats` runs in live monitoring mode:
+
+```bash
+# Live monitoring (default, refreshes every 2s)
+context-stats
+
+# Custom refresh interval
+context-stats -w 5
+
+# Show once and exit
+context-stats --no-watch
+
+# Show specific session
+context-stats <session_id>
+```
+
+### Graph Types
+
+```bash
+context-stats --type delta       # Context growth per interaction (default)
+context-stats --type cumulative  # Total context usage over time
+context-stats --type both        # Show both graphs
+context-stats --type io          # Input/output token breakdown
+context-stats --type all         # Show all graphs
+```
+
+## Output
+
+```
+Context Stats (my-project • abc123def)
+
+Context Growth Per Interaction
+Max: 4,787  Min: 0  Points: 254
+
+     4,787 │                                        ●
+           │                                    ●   ▒
+           │     ●●         ●                   ▒   ░
+           │     ●                              ░   ░
+     2,052 │     ░ ●    ● ●                     ░   ░ ●
+           │     ░        ▒ ●  ● ●   ●  ●    ● ●░   ░ ▒   ●●
+           │●●●●●●●●●●●●●●●●●●●●●●●●●●● ●●●●●●●●●●●●●●●●●●●●●●
+         0 │●●●●●░▒●●●●▒▒●●▒░●●░▒▒▒▒▒●●●▒●▒●●▒●▒░●●▒●░●●▒●▒▒●▒
+           └─────────────────────────────────────────────────
+           10:40                11:29                12:01
+
+Session Summary
+----------------------------------------------------------------------------
+  >>> DUMB ZONE <<< (You are in the dumb zone - Dex Horthy says so)
+
+  Context Remaining:   43,038 (21%)
+  Input Tokens:        59,015
+  Output Tokens:       43,429
+  Session Duration:    2h 29m
+
+Powered by claude-statusline v1.2.0 - https://github.com/luongnv89/cc-context-stats
+```
+
+## Features
+
+- **Live Monitoring**: Automatic refresh every 2 seconds (configurable)
+- **Zone Awareness**: Color-coded status based on context usage
+- **Project Display**: Shows project name and session ID
+- **ASCII Graphs**: Smooth area charts with gradient fills
+- **Minimal Output**: Clean summary with just the essential info
+
+## Graph Symbols
+
+| Symbol | Meaning                 |
+| ------ | ----------------------- |
+| `●`    | Trend line              |
+| `▒`    | Medium fill (near line) |
+| `░`    | Light fill (area below) |
+| `│`    | Y-axis                  |
+| `└─`   | X-axis                  |
+
+## Watch Mode
+
+By default, context-stats runs in watch mode. Press `Ctrl+C` to exit.
+
+Features:
+
+- **Flicker-free updates**: Uses cursor repositioning for smooth redraws
+- **Live timestamp**: Shows refresh indicator in header
+- **Hidden cursor**: Clean display without cursor blinking
+- **Auto-adapt**: Responds to terminal size changes
+
+To disable watch mode and show graphs once:
+
+```bash
+context-stats --no-watch
+```
+
+## Data Source
+
+Reads from `~/.claude/statusline/statusline.<session_id>.state` files, automatically created by the status line script.
+
+## CLI Reference
+
+```
+context-stats [session_id] [options]
+
+ARGUMENTS:
+    session_id    Optional session ID. If not provided, uses the latest session.
+
+OPTIONS:
+    --type <type>  Graph type to display:
+                   - delta: Context growth per interaction (default)
+                   - cumulative: Total context usage over time
+                   - io: Input/output tokens over time
+                   - both: Show cumulative and delta graphs
+                   - all: Show all graphs including I/O
+    -w [interval]  Set refresh interval in seconds (default: 2)
+    --no-watch     Show graphs once and exit (disable live monitoring)
+    --no-color     Disable color output
+    --help         Show help message
+```

package/docs/installation.md

@@ -0,0 +1,195 @@
+# Installation Guide
+
+## Quick Install
+
+### One-Line Install (Recommended)
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/luongnv89/claude-statusline/main/install.sh | bash
+```
+
+This downloads and runs the installer directly from GitHub. In non-interactive mode, it installs the **full** statusline script by default.
+
+### Interactive Install
+
+To choose a different script variant:
+
+```bash
+bash <(curl -fsSL https://raw.githubusercontent.com/luongnv89/claude-statusline/main/install.sh)
+```
+
+This runs the installer interactively, allowing you to select from:
+
+1. minimal - Simple: model + directory
+2. git - With git branch info
+3. full - Full featured with context usage (recommended)
+4. python - Python version (full featured)
+5. node - Node.js version (full featured)
+
+### Install from Source
+
+```bash
+git clone https://github.com/luongnv89/cc-context-stats.git
+cd claude-statusline
+./install.sh
+```
+
+The installer will:
+
+1. Install the statusline script to `~/.claude/`
+2. Install `context-stats` CLI tool to `~/.local/bin/`
+3. Create default configuration at `~/.claude/statusline.conf`
+4. Update `~/.claude/settings.json`
+
+### Windows
+
+Use the Python or Node.js version (no `jq` required):
+
+```powershell
+git clone https://github.com/luongnv89/cc-context-stats.git
+copy claude-statusline\scripts\statusline.py %USERPROFILE%\.claude\statusline.py
+```
+
+Or with Node.js:
+
+```powershell
+copy claude-statusline\scripts\statusline.js %USERPROFILE%\.claude\statusline.js
+```
+
+## Manual Installation
+
+### macOS / Linux
+
+```bash
+cp scripts/statusline-full.sh ~/.claude/statusline.sh
+chmod +x ~/.claude/statusline.sh
+```
+
+### Context Stats CLI (Optional)
+
+```bash
+cp scripts/context-stats.sh ~/.local/bin/context-stats
+chmod +x ~/.local/bin/context-stats
+```
+
+Ensure `~/.local/bin` is in your PATH:
+
+```bash
+# For zsh
+echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
+source ~/.zshrc
+
+# For bash
+echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
+source ~/.bashrc
+```
+
+## Configure Claude Code
+
+Add to your Claude Code settings:
+
+**File location:**
+
+- macOS/Linux: `~/.claude/settings.json`
+- Windows: `%USERPROFILE%\.claude\settings.json`
+
+### Bash (macOS/Linux)
+
+```json
+{
+  "statusLine": {
+    "type": "command",
+    "command": "~/.claude/statusline.sh"
+  }
+}
+```
+
+### Python (All Platforms)
+
+```json
+{
+  "statusLine": {
+    "type": "command",
+    "command": "python ~/.claude/statusline.py"
+  }
+}
+```
+
+Windows:
+
+```json
+{
+  "statusLine": {
+    "type": "command",
+    "command": "python %USERPROFILE%\\.claude\\statusline.py"
+  }
+}
+```
+
+### Node.js (All Platforms)
+
+```json
+{
+  "statusLine": {
+    "type": "command",
+    "command": "node ~/.claude/statusline.js"
+  }
+}
+```
+
+Windows:
+
+```json
+{
+  "statusLine": {
+    "type": "command",
+    "command": "node %USERPROFILE%\\.claude\\statusline.js"
+  }
+}
+```
+
+## Requirements
+
+### macOS
+
+```bash
+brew install jq
+```
+
+### Linux (Debian/Ubuntu)
+
+```bash
+sudo apt install jq
+```
+
+### Linux (Fedora/RHEL)
+
+```bash
+sudo dnf install jq
+```
+
+### Windows
+
+No additional requirements for Python/Node.js scripts.
+
+For bash scripts via WSL:
+
+```bash
+sudo apt install jq
+```
+
+## Verify Installation
+
+Test your statusline script:
+
+```bash
+# macOS/Linux
+echo '{"model":{"display_name":"Test"}}' | ~/.claude/statusline.sh
+
+# Windows (Python)
+echo {"model":{"display_name":"Test"}} | python %USERPROFILE%\.claude\statusline.py
+```
+
+You should see output like: `[Test] directory`
+
+Restart Claude Code to see the status line.

package/docs/scripts.md

@@ -0,0 +1,116 @@
+# Available Scripts
+
+## Overview
+
+| Script                  | Platform     | Requirements | Features                          |
+| ----------------------- | ------------ | ------------ | --------------------------------- |
+| `statusline-full.sh`    | macOS, Linux | `jq`         | Full-featured with all indicators |
+| `statusline-git.sh`     | macOS, Linux | `jq`         | Git branch and changes            |
+| `statusline-minimal.sh` | macOS, Linux | `jq`         | Model + directory only            |
+| `statusline.py`         | All          | Python 3     | Cross-platform, full-featured     |
+| `statusline.js`         | All          | Node.js      | Cross-platform, full-featured     |
+| `context-stats.sh`      | macOS, Linux | None         | Token usage visualization         |
+
+## Bash Scripts
+
+### statusline-full.sh (Recommended)
+
+Complete status line with all features:
+
+- Model name
+- Current directory
+- Git branch and changes
+- Token usage with color coding
+- Token delta tracking
+- Autocompact indicator
+- Session ID
+
+### statusline-git.sh
+
+Lighter version with git info:
+
+- Model name
+- Current directory
+- Git branch and changes
+
+### statusline-minimal.sh
+
+Minimal footprint:
+
+- Model name
+- Current directory
+
+## Cross-Platform Scripts
+
+### statusline.py
+
+Python implementation matching `statusline-full.sh` functionality. Works on Windows, macOS, and Linux without additional dependencies beyond Python 3.
+
+### statusline.js
+
+Node.js implementation matching `statusline-full.sh` functionality. Works on all platforms with Node.js installed.
+
+## Utility Scripts
+
+### context-stats.sh
+
+Standalone CLI tool for visualizing token consumption. See [Context Stats](context-stats.md) for details.
+
+## Output Format
+
+All statusline scripts produce consistent output:
+
+```
+[Model] directory | branch [changes] | XXk free (XX%) [+delta] [AC:XXk] session_id
+```
+
+## Architecture
+
+```mermaid
+graph LR
+    A[Claude Code] -->|JSON stdin| B[Statusline Script]
+    B -->|Parse| C[Model Info]
+    B -->|Parse| D[Context Info]
+    B -->|Check| E[Git Status]
+    B -->|Read| F[Config File]
+    B -->|Write| G[State File]
+    C --> H[Format Output]
+    D --> H
+    E --> H
+    F --> H
+    H -->|stdout| A
+```
+
+## Input Format
+
+Scripts receive JSON via stdin from Claude Code:
+
+```json
+{
+  "model": {
+    "display_name": "Opus 4.5"
+  },
+  "cwd": "/path/to/project",
+  "session_id": "abc123",
+  "context": {
+    "tokens_remaining": 64000,
+    "context_window": 200000,
+    "autocompact_buffer_tokens": 45000
+  }
+}
+```
+
+## Color Codes
+
+All scripts use consistent ANSI colors:
+
+| Color   | Code         | Usage                      |
+| ------- | ------------ | -------------------------- |
+| Blue    | `\033[0;34m` | Directory                  |
+| Magenta | `\033[0;35m` | Git branch                 |
+| Cyan    | `\033[0;36m` | Changes count              |
+| Green   | `\033[0;32m` | High availability (>50%)   |
+| Yellow  | `\033[0;33m` | Medium availability (>25%) |
+| Red     | `\033[0;31m` | Low availability (<=25%)   |
+| Dim     | `\033[2m`    | Model, AC indicator        |
+| Reset   | `\033[0m`    | Reset formatting           |