cc-context-stats 1.3.0

package/docs/troubleshooting.md

@@ -0,0 +1,189 @@
+# 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
+   ```
+
+**Windows (Python):**
+
+```powershell
+echo {"model":{"display_name":"Test"}} | python %USERPROFILE%\.claude\statusline.py
+```
+
+### jq not found
+
+The bash scripts require `jq` for JSON parsing.
+
+**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
+
+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
+   ```
+
+### No token graph data
+
+Token history requires:
+
+1. `show_delta=true` in `~/.claude/statusline.conf` (default)
+2. Active Claude Code session generating state files
+3. 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
+   ```
+
+### 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.
+
+### 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
+```
+
+### 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)
+  - Script version being used
+  - Error messages or unexpected behavior

package/install

@@ -0,0 +1,344 @@
+#!/bin/bash
+#
+# Claude Code Status Line Installer
+# Installs and configures a status line for Claude Code
+#
+# Usage:
+#   Local:  ./install.sh
+#   Remote: curl -fsSL https://raw.githubusercontent.com/luongnv89/claude-statusline/main/install.sh | bash
+#
+
+set -e
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[0;33m'
+BLUE='\033[0;34m'
+RESET='\033[0m'
+
+CLAUDE_DIR="$HOME/.claude"
+SETTINGS_FILE="$CLAUDE_DIR/settings.json"
+LOCAL_BIN="$HOME/.local/bin"
+
+# GitHub repository info for remote installation
+GITHUB_RAW_URL="https://raw.githubusercontent.com/luongnv89/claude-statusline/main"
+GITHUB_API_URL="https://api.github.com/repos/luongnv89/claude-statusline"
+
+# Detect if running from pipe (curl) or locally
+detect_install_mode() {
+    # Check if we have a valid script file with scripts directory
+    if [ -n "${BASH_SOURCE[0]}" ] && [ -f "${BASH_SOURCE[0]}" ]; then
+        SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+        if [ -d "$SCRIPT_DIR/scripts" ]; then
+            INSTALL_MODE="local"
+            INTERACTIVE=true
+            [ -t 0 ] || INTERACTIVE=false
+            return
+        fi
+    fi
+    # Running from curl/pipe or script directory not found
+    INSTALL_MODE="remote"
+    INTERACTIVE=false
+}
+
+echo -e "${BLUE}Claude Code Status Line Installer${RESET}"
+echo "=================================="
+echo
+
+detect_install_mode
+
+if [ "$INSTALL_MODE" = "remote" ]; then
+    echo -e "${YELLOW}Remote installation mode${RESET}"
+    echo "Downloading from GitHub..."
+    echo
+else
+    echo -e "${GREEN}Local installation mode${RESET}"
+    echo
+fi
+
+# Check for curl (required for remote installation)
+check_curl() {
+    if [ "$INSTALL_MODE" = "remote" ]; then
+        if ! command -v curl &>/dev/null; then
+            echo -e "${RED}Error: 'curl' is required for remote installation${RESET}"
+            exit 1
+        fi
+    fi
+}
+
+# Check for jq (required for bash scripts)
+check_jq() {
+    if ! command -v jq &>/dev/null; then
+        echo -e "${YELLOW}Warning: 'jq' is not installed.${RESET}"
+        echo "jq is required for bash status line scripts."
+        echo
+        if [[ "$OSTYPE" == "darwin"* ]]; then
+            echo "Install with: brew install jq"
+        else
+            echo "Install with: sudo apt install jq (Debian/Ubuntu)"
+            echo "         or: sudo yum install jq (RHEL/CentOS)"
+        fi
+        echo
+        if [ "$INTERACTIVE" = true ]; then
+            read -p "Continue anyway? (y/n) " -n 1 -r
+            echo
+            if [[ ! $REPLY =~ ^[Yy]$ ]]; then
+                exit 1
+            fi
+        fi
+    else
+        echo -e "${GREEN}✓${RESET} jq is installed"
+    fi
+}
+
+# Download a file from GitHub
+download_file() {
+    local remote_path="$1"
+    local dest_path="$2"
+    local url="$GITHUB_RAW_URL/$remote_path"
+
+    if curl -fsSL "$url" -o "$dest_path"; then
+        chmod +x "$dest_path"
+        return 0
+    else
+        echo -e "${RED}Error: Failed to download $remote_path${RESET}"
+        return 1
+    fi
+}
+
+# Get latest commit hash from GitHub
+get_remote_commit_hash() {
+    local hash
+    hash=$(curl -fsSL "$GITHUB_API_URL/commits/main" 2>/dev/null | grep -m1 '"sha"' | cut -d'"' -f4 | head -c7)
+    echo "${hash:-unknown}"
+}
+
+# Select script type
+select_script() {
+    echo
+    echo "Available status line scripts:"
+    echo "  1) minimal  - Simple: model + directory"
+    echo "  2) git      - With git branch info"
+    echo "  3) full     - Full featured with context usage (recommended)"
+    echo "  4) python   - Python version (full featured)"
+    echo "  5) node     - Node.js version (full featured)"
+    echo
+
+    if [ "$INTERACTIVE" = true ]; then
+        read -rp "Select script [1-5, default: 3]: " choice
+    else
+        echo "Non-interactive mode detected. Using default: full (3)"
+        choice=3
+    fi
+
+    case ${choice:-3} in
+    1)
+        SCRIPT_REMOTE="scripts/statusline-minimal.sh"
+        SCRIPT_NAME="statusline.sh"
+        ;;
+    2)
+        SCRIPT_REMOTE="scripts/statusline-git.sh"
+        SCRIPT_NAME="statusline.sh"
+        ;;
+    3)
+        SCRIPT_REMOTE="scripts/statusline-full.sh"
+        SCRIPT_NAME="statusline.sh"
+        ;;
+    4)
+        SCRIPT_REMOTE="scripts/statusline.py"
+        SCRIPT_NAME="statusline.py"
+        ;;
+    5)
+        SCRIPT_REMOTE="scripts/statusline.js"
+        SCRIPT_NAME="statusline.js"
+        ;;
+    *)
+        echo -e "${RED}Invalid choice${RESET}"
+        exit 1
+        ;;
+    esac
+
+    if [ "$INSTALL_MODE" = "local" ]; then
+        SCRIPT_SRC="$SCRIPT_DIR/$SCRIPT_REMOTE"
+    fi
+}
+
+# Create .claude directory if needed
+ensure_claude_dir() {
+    if [ ! -d "$CLAUDE_DIR" ]; then
+        echo -e "${YELLOW}Creating $CLAUDE_DIR directory...${RESET}"
+        mkdir -p "$CLAUDE_DIR"
+    fi
+    echo -e "${GREEN}✓${RESET} Claude directory exists: $CLAUDE_DIR"
+}
+
+# Install/copy script
+install_script() {
+    DEST="$CLAUDE_DIR/$SCRIPT_NAME"
+
+    if [ -f "$DEST" ]; then
+        echo
+        echo -e "${YELLOW}Warning: $DEST already exists${RESET}"
+        if [ "$INTERACTIVE" = true ]; then
+            read -p "Overwrite? (y/n) " -n 1 -r
+            echo
+            if [[ ! $REPLY =~ ^[Yy]$ ]]; then
+                echo "Keeping existing script."
+                return
+            fi
+        else
+            echo "Overwriting in non-interactive mode..."
+        fi
+    fi
+
+    if [ "$INSTALL_MODE" = "local" ]; then
+        cp "$SCRIPT_SRC" "$DEST"
+        chmod +x "$DEST"
+    else
+        download_file "$SCRIPT_REMOTE" "$DEST"
+    fi
+    echo -e "${GREEN}✓${RESET} Installed: $DEST"
+}
+
+# Install token-graph CLI tool
+install_token_graph() {
+    echo
+
+    # Create ~/.local/bin if it doesn't exist
+    if [ ! -d "$LOCAL_BIN" ]; then
+        echo -e "${YELLOW}Creating $LOCAL_BIN directory...${RESET}"
+        mkdir -p "$LOCAL_BIN"
+    fi
+
+    DEST="$LOCAL_BIN/token-graph"
+
+    if [ -f "$DEST" ]; then
+        echo -e "${YELLOW}Warning: $DEST already exists${RESET}"
+        if [ "$INTERACTIVE" = true ]; then
+            read -p "Overwrite? (y/n) " -n 1 -r
+            echo
+            if [[ ! $REPLY =~ ^[Yy]$ ]]; then
+                echo "Keeping existing token-graph."
+                return
+            fi
+        else
+            echo "Overwriting in non-interactive mode..."
+        fi
+    fi
+
+    # Get commit hash for version embedding
+    local commit_hash
+    if [ "$INSTALL_MODE" = "local" ]; then
+        commit_hash=$(git -C "$SCRIPT_DIR" rev-parse --short HEAD 2>/dev/null || echo "unknown")
+        cp "$SCRIPT_DIR/scripts/token-graph.sh" "$DEST"
+    else
+        commit_hash=$(get_remote_commit_hash)
+        download_file "scripts/token-graph.sh" "$DEST"
+    fi
+
+    # Embed commit hash
+    sed -i.bak "s/COMMIT_HASH=\"dev\"/COMMIT_HASH=\"$commit_hash\"/" "$DEST" && rm -f "$DEST.bak"
+    chmod +x "$DEST"
+    echo -e "${GREEN}✓${RESET} Installed: $DEST (v1.0.0-$commit_hash)"
+
+    # Check if ~/.local/bin is in PATH
+    if [[ ":$PATH:" != *":$LOCAL_BIN:"* ]]; then
+        echo
+        echo -e "${YELLOW}Note: $LOCAL_BIN is not in your PATH${RESET}"
+        echo "Add it to your shell configuration:"
+        echo
+        if [[ "$SHELL" == *"zsh"* ]]; then
+            echo "  echo 'export PATH=\"\$HOME/.local/bin:\$PATH\"' >> ~/.zshrc"
+            echo "  source ~/.zshrc"
+        else
+            echo "  echo 'export PATH=\"\$HOME/.local/bin:\$PATH\"' >> ~/.bashrc"
+            echo "  source ~/.bashrc"
+        fi
+    fi
+}
+
+# Create config file with defaults if it doesn't exist
+create_config() {
+    CONFIG_FILE="$CLAUDE_DIR/statusline.conf"
+
+    if [ -f "$CONFIG_FILE" ]; then
+        echo -e "${GREEN}✓${RESET} Config file exists: $CONFIG_FILE"
+        return
+    fi
+
+    cat >"$CONFIG_FILE" <<'EOF'
+# Autocompact setting - sync with Claude Code's /config
+autocompact=true
+
+# Token display format
+token_detail=true
+
+# Show token delta since last refresh (adds file I/O on every refresh)
+# Disable if you don't need it to reduce overhead
+show_delta=true
+
+# Show session_id in status line
+show_session=true
+EOF
+    echo -e "${GREEN}✓${RESET} Created config file: $CONFIG_FILE"
+}
+
+# Update settings.json
+update_settings() {
+    echo
+
+    # Create settings file if it doesn't exist
+    if [ ! -f "$SETTINGS_FILE" ]; then
+        echo '{}' >"$SETTINGS_FILE"
+        echo -e "${GREEN}✓${RESET} Created $SETTINGS_FILE"
+    fi
+
+    # Check if jq is available for JSON manipulation
+    if command -v jq &>/dev/null; then
+        # Backup existing settings
+        cp "$SETTINGS_FILE" "$SETTINGS_FILE.backup"
+
+        # Add/update statusLine configuration
+        SCRIPT_PATH="$HOME/.claude/$SCRIPT_NAME"
+        jq --arg cmd "$SCRIPT_PATH" '.statusLine = {"type": "command", "command": $cmd}' \
+            "$SETTINGS_FILE.backup" >"$SETTINGS_FILE"
+
+        rm "$SETTINGS_FILE.backup"
+        echo -e "${GREEN}✓${RESET} Updated settings.json with statusLine configuration"
+    else
+        echo -e "${YELLOW}Note: Could not update settings.json (jq not installed)${RESET}"
+        echo
+        echo "Please add this to $SETTINGS_FILE manually:"
+        echo
+        echo '  "statusLine": {'
+        echo '    "type": "command",'
+        echo "    \"command\": \"~/.claude/$SCRIPT_NAME\""
+        echo '  }'
+    fi
+}
+
+# Main installation
+main() {
+    check_curl
+    check_jq
+    ensure_claude_dir
+    select_script
+    install_script
+    install_token_graph
+    create_config
+    update_settings
+
+    echo
+    echo -e "${GREEN}Installation complete!${RESET}"
+    echo
+    echo "Your status line is now configured."
+    echo "Restart Claude Code to see the changes."
+    echo
+    echo "To customize, edit: $CLAUDE_DIR/$SCRIPT_NAME"
+    echo "To change settings, edit: $CLAUDE_DIR/statusline.conf"
+    echo
+    echo "Run 'token-graph' to visualize token usage for any session."
+}
+
+main