cc-context-stats 1.7.0 → 1.8.1

package/docs/configuration.md

@@ -1,118 +0,0 @@
-# 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
-
-# Disable rotating text animations
-reduced_motion=false  # (default) Animations enabled
-reduced_motion=true   # Disable animations for accessibility
-```
-
-## 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.
-
-## 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

@@ -1,143 +0,0 @@
-# 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
-```
-
-### 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
-
-```
-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 cc-context-stats v1.7.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

@@ -1,255 +0,0 @@
-# Installation Guide
-
-## Quick Install
-
-### One-Line Install (Recommended)
-
-```bash
-curl -fsSL https://raw.githubusercontent.com/luongnv89/cc-context-stats/main/install.sh | bash
-```
-
-This downloads and runs the installer directly from GitHub. It installs the **full** statusline script and the `context-stats` CLI tool.
-
-### NPM (Recommended for Node.js users)
-
-```bash
-npm install -g cc-context-stats
-```
-
-Or with yarn:
-
-```bash
-yarn global add cc-context-stats
-```
-
-After installation, add to `~/.claude/settings.json`:
-
-```json
-{
-  "statusLine": {
-    "type": "command",
-    "command": "claude-statusline"
-  }
-}
-```
-
-### Python (Recommended for Python users)
-
-```bash
-pip install cc-context-stats
-```
-
-Or with uv:
-
-```bash
-uv pip install cc-context-stats
-```
-
-After installation, add to `~/.claude/settings.json`:
-
-```json
-{
-  "statusLine": {
-    "type": "command",
-    "command": "claude-statusline"
-  }
-}
-```
-
-### Install from Source
-
-```bash
-git clone https://github.com/luongnv89/cc-context-stats.git
-cd cc-context-stats
-./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
-# Python (via pip)
-pip install cc-context-stats
-
-# Or manually copy the script
-git clone https://github.com/luongnv89/cc-context-stats.git
-copy cc-context-stats\scripts\statusline.py %USERPROFILE%\.claude\statusline.py
-```
-
-Or with Node.js:
-
-```powershell
-# Node.js (via npm)
-npm install -g cc-context-stats
-
-# Or manually copy the script
-copy cc-context-stats\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`
-
-### pip / npm Install
-
-If you installed via `pip install cc-context-stats` or `npm install -g cc-context-stats`:
-
-```json
-{
-  "statusLine": {
-    "type": "command",
-    "command": "claude-statusline"
-  }
-}
-```
-
-### Bash (macOS/Linux)
-
-```json
-{
-  "statusLine": {
-    "type": "command",
-    "command": "~/.claude/statusline.sh"
-  }
-}
-```
-
-### Python (Manual Copy)
-
-```json
-{
-  "statusLine": {
-    "type": "command",
-    "command": "python ~/.claude/statusline.py"
-  }
-}
-```
-
-Windows:
-
-```json
-{
-  "statusLine": {
-    "type": "command",
-    "command": "python %USERPROFILE%\\.claude\\statusline.py"
-  }
-}
-```
-
-### Node.js (Manual Copy)
-
-```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   # Only needed for bash scripts
-```
-
-### Linux (Debian/Ubuntu)
-
-```bash
-sudo apt install jq   # Only needed for bash scripts
-```
-
-### Linux (Fedora/RHEL)
-
-```bash
-sudo dnf install jq   # Only needed for bash scripts
-```
-
-### Windows
-
-No additional requirements for Python/Node.js scripts (via pip or npm).
-
-For bash scripts via WSL:
-
-```bash
-sudo apt install jq
-```
-
-## Verify Installation
-
-Test your statusline:
-
-```bash
-# If installed via pip or npm
-echo '{"model":{"display_name":"Test"}}' | claude-statusline
-
-# Bash script (macOS/Linux)
-echo '{"model":{"display_name":"Test"}}' | ~/.claude/statusline.sh
-
-# Python script (manual copy)
-echo '{"model":{"display_name":"Test"}}' | python3 ~/.claude/statusline.py
-
-# Node.js script (manual copy)
-echo '{"model":{"display_name":"Test"}}' | node ~/.claude/statusline.js
-
-# 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

@@ -1,140 +0,0 @@
-# Available Scripts
-
-## Overview
-
-| Script                  | Platform     | Requirements | State Writes | Features                          |
-| ----------------------- | ------------ | ------------ | ------------ | --------------------------------- |
-| `statusline-full.sh`    | macOS, Linux | `jq`         | No           | Full-featured with all indicators |
-| `statusline-git.sh`     | macOS, Linux | `jq`         | No           | Git branch and changes            |
-| `statusline-minimal.sh` | macOS, Linux | `jq`         | No           | Model + directory only            |
-| `statusline.py`         | All          | Python 3     | Yes          | Cross-platform, full-featured     |
-| `statusline.js`         | All          | Node.js 18+  | Yes          | Cross-platform, full-featured     |
-| `context-stats.sh`      | macOS, Linux | Bash         | No           | Token usage visualization (CLI)   |
-
-## Installation Methods
-
-| Method | Statusline Command | Context Stats Command |
-| ------ | ------------------ | --------------------- |
-| `pip install cc-context-stats` | `claude-statusline` | `context-stats` |
-| `npm install -g cc-context-stats` | `claude-statusline` | `context-stats` |
-| Shell installer (`install.sh`) | `~/.claude/statusline.sh` | `~/.local/bin/context-stats` |
-
-## Bash Scripts
-
-### statusline-full.sh (Recommended for bash users)
-
-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
-
-> **Note:** Does not write state files. For context-stats CLI support, use the Python or Node.js script instead.
-
-### 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.
-
-Features beyond bash scripts:
-- Writes state files for context-stats CLI
-- Duplicate-entry deduplication
-- State file rotation (10k/5k threshold)
-- 5-second git command timeout
-
-### statusline.js
-
-Node.js implementation matching `statusline-full.sh` functionality. Works on all platforms with Node.js 18+ installed.
-
-Features beyond bash scripts:
-- Writes state files for context-stats CLI
-- Duplicate-entry deduplication
-- State file rotation (10k/5k threshold)
-- 5-second git command timeout
-
-## Utility Scripts
-
-### context-stats.sh
-
-Standalone bash CLI tool for visualizing token consumption. Reads state files written by the Python or Node.js statusline scripts. 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 (defaults, overridable via `~/.claude/statusline.conf`):
-
-| Color   | Code         | Usage                      | Config Key      |
-| ------- | ------------ | -------------------------- | --------------- |
-| Blue    | `\033[0;34m` | Directory                  | `color_blue`    |
-| Magenta | `\033[0;35m` | Git branch                 | `color_magenta` |
-| Cyan    | `\033[0;36m` | Changes count              | `color_cyan`    |
-| Green   | `\033[0;32m` | High availability (>50%)   | `color_green`   |
-| Yellow  | `\033[0;33m` | Medium availability (>25%) | `color_yellow`  |
-| Red     | `\033[0;31m` | Low availability (<=25%)   | `color_red`     |
-| Dim     | `\033[2m`    | Model, AC indicator        | —               |
-| Reset   | `\033[0m`    | Reset formatting           | —               |
-
-See [Configuration](configuration.md#custom-colors) for details on overriding colors with named colors or hex codes.