cc-context-stats 1.8.0 → 1.8.2

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.

package/docs/troubleshooting.md

@@ -1,278 +0,0 @@
-# Troubleshooting
-
-## Common Issues
-
-### Status line not appearing
-
-**macOS/Linux:**
-
-1. Check script is executable:
-
-   ```bash
-   chmod +x ~/.claude/statusline.sh
-   ```
-
-2. Test the script:
-
-   ```bash
-   echo '{"model":{"display_name":"Test"}}' | ~/.claude/statusline.sh
-   ```
-
-3. Verify settings.json configuration:
-
-   ```bash
-   cat ~/.claude/settings.json
-   ```
-
-**pip/npm install:**
-
-1. Verify the command is available:
-
-   ```bash
-   which claude-statusline
-   ```
-
-2. Test it:
-
-   ```bash
-   echo '{"model":{"display_name":"Test"}}' | claude-statusline
-   ```
-
-3. Ensure your settings.json uses `"command": "claude-statusline"` (not a file path).
-
-**Windows (Python):**
-
-```powershell
-echo {"model":{"display_name":"Test"}} | python %USERPROFILE%\.claude\statusline.py
-```
-
-### jq not found
-
-The bash scripts require `jq` for JSON parsing. Python and Node.js scripts do **not** need `jq`.
-
-**macOS:**
-
-```bash
-brew install jq
-```
-
-**Linux (Debian/Ubuntu):**
-
-```bash
-sudo apt install jq
-```
-
-**Linux (Fedora/RHEL):**
-
-```bash
-sudo dnf install jq
-```
-
-Alternatively, use the Python or Node.js version which don't require `jq`.
-
-### context-stats command not found
-
-**If installed via pip or npm:**
-
-1. Verify installation:
-
-   ```bash
-   which context-stats
-   ```
-
-2. Reinstall if missing:
-
-   ```bash
-   pip install cc-context-stats   # or: npm install -g cc-context-stats
-   ```
-
-**If installed via shell installer:**
-
-1. Verify installation:
-
-   ```bash
-   ls -la ~/.local/bin/context-stats
-   ```
-
-2. Check PATH:
-
-   ```bash
-   echo $PATH | grep -q "$HOME/.local/bin" && echo "In PATH" || echo "Not in PATH"
-   ```
-
-3. Add to PATH if needed:
-
-   ```bash
-   # zsh
-   echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
-   source ~/.zshrc
-
-   # bash
-   echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
-   source ~/.bashrc
-   ```
-
-### pip install fails
-
-1. Ensure Python 3.9+:
-
-   ```bash
-   python3 --version
-   ```
-
-2. Try with `--user` flag:
-
-   ```bash
-   pip install --user cc-context-stats
-   ```
-
-3. Or use `uv`:
-
-   ```bash
-   uv pip install cc-context-stats
-   ```
-
-### npm install fails
-
-1. Ensure Node.js 18+:
-
-   ```bash
-   node --version
-   ```
-
-2. Try with sudo (Linux/macOS):
-
-   ```bash
-   sudo npm install -g cc-context-stats
-   ```
-
-3. Or fix npm permissions:
-
-   ```bash
-   mkdir -p ~/.npm-global
-   npm config set prefix '~/.npm-global'
-   echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.zshrc
-   source ~/.zshrc
-   npm install -g cc-context-stats
-   ```
-
-### No token graph data
-
-Token history requires:
-
-1. Python or Node.js statusline script (bash scripts do **not** write state files)
-2. `show_delta=true` in `~/.claude/statusline.conf` (default)
-3. Active Claude Code session generating state files
-4. State files at `~/.claude/statusline/statusline.<session_id>.state`
-
-Check for state files:
-
-```bash
-ls -la ~/.claude/statusline/statusline.*.state
-```
-
-### Git info not showing
-
-1. Verify you're in a git repository:
-
-   ```bash
-   git rev-parse --is-inside-work-tree
-   ```
-
-2. Check git is installed:
-
-   ```bash
-   which git
-   ```
-
-3. Git commands have a 5-second timeout. If your repo is very large, git operations may time out silently.
-
-### Wrong token colors
-
-Token colors depend on availability percentage:
-
-| Availability | Expected Color |
-| ------------ | -------------- |
-| > 50%        | Green          |
-| > 25%        | Yellow         |
-| <= 25%       | Red            |
-
-If colors look wrong, check terminal color support.
-
-### Delta always shows zero
-
-Token delta requires multiple statusline refreshes. The first refresh establishes a baseline; subsequent refreshes show the delta.
-
-If delta is always zero after multiple refreshes, check that the state file is being written:
-
-```bash
-wc -l ~/.claude/statusline/statusline.*.state
-```
-
-### Configuration not taking effect
-
-1. Check config file location:
-
-   ```bash
-   cat ~/.claude/statusline.conf
-   ```
-
-2. Verify syntax (no spaces around `=`):
-
-   ```bash
-   # Correct
-   show_delta=true
-
-   # Wrong
-   show_delta = true
-   ```
-
-3. Restart Claude Code after config changes.
-
-## Debug Mode
-
-### Test script output
-
-```bash
-# Create test input
-cat << 'EOF' > /tmp/test-input.json
-{
-  "model": {"display_name": "Opus 4.5"},
-  "cwd": "/test/project",
-  "session_id": "test123",
-  "context": {
-    "tokens_remaining": 64000,
-    "context_window": 200000,
-    "autocompact_buffer_tokens": 45000
-  }
-}
-EOF
-
-# Test each script
-cat /tmp/test-input.json | ~/.claude/statusline.sh
-cat /tmp/test-input.json | python3 ~/.claude/statusline.py
-cat /tmp/test-input.json | node ~/.claude/statusline.js
-
-# Test pip/npm installed version
-cat /tmp/test-input.json | claude-statusline
-```
-
-### Check state files
-
-```bash
-# View state file content
-cat ~/.claude/statusline/statusline.*.state
-
-# Watch state file updates
-watch -n 1 'tail -5 ~/.claude/statusline/statusline.*.state'
-```
-
-## Getting Help
-
-- Check [existing issues](https://github.com/luongnv89/cc-context-stats/issues)
-- Open a new issue with:
-  - Operating system
-  - Shell type (bash/zsh)
-  - Installation method (pip, npm, shell installer, manual)
-  - Script version being used
-  - Error messages or unexpected behavior