claude-statusline 2.1.2

package/docs/guide-01-configuration.md

@@ -0,0 +1,277 @@
+# Configuration Guide
+
+Complete guide to configuring claude-statusline for your workflow.
+
+## Quick Setup
+
+### Option A: Complete Example with All Options
+```bash
+# Copy the full example with all options documented
+cp .claude-statusline.json.example ~/.claude/.claude-statusline.json
+```
+
+### Option B: Minimal Example with Just Essentials
+```bash
+# Copy minimal example for quick setup
+cp .claude-statusline.json.example.min ~/.claude/.claude-statusline.json
+```
+
+### Edit Your Configuration
+```bash
+nano ~/.claude/.claude-statusline.json
+```
+
+## Runtime Selection for Maximum Performance
+
+### Understanding the Performance Difference
+
+claude-statusline can run on either Node.js or Bun runtimes, with significant performance differences:
+
+| Runtime | Response Time | Performance | When to Use |
+|---------|---------------|------------|-------------|
+| **Bun** | ~5ms | Excellent (5x faster) | Recommended for best performance |
+| **Node.js** | ~28ms | Good | Good fallback, widely available |
+
+> **Important**: Even when installed with `bun install -g`, the executable's shebang defaults to Node.js. To get Bun's performance benefits, you must explicitly specify it in your Claude Code configuration.
+
+### Claude Code Configuration Options
+
+#### Option 1: Maximum Performance (Recommended)
+Use Bun runtime explicitly:
+
+```json
+// ~/.claude/settings.json
+{
+  "statusLine": {
+    "type": "command",
+    "command": "bun claude-statusline"
+  }
+}
+```
+
+#### Option 2: Standard Configuration
+Uses Node.js runtime (default shebang):
+
+```json
+// ~/.claude/settings.json
+{
+  "statusLine": {
+    "type": "command",
+    "command": "claude-statusline"
+  }
+}
+```
+
+### Installation vs Runtime
+
+**Installation Method ≠ Runtime Used:**
+- `bun install -g claude-statusline` - Just downloads the package
+- `bun claude-statusline` - Actually uses Bun runtime for execution
+- `claude-statusline` - Uses Node.js runtime (via shebang)
+
+Both configurations work perfectly. The Bun runtime is 5x faster but requires Bun to be installed. Node.js is more widely available and still provides instant response times.
+
+## Configuration Search Order
+
+1. `./.claude-statusline.json` (project-specific)
+2. `~/.claude/.claude-statusline.json` (global) ← **Recommended**
+3. Environment variables (legacy)
+
+> **Note**: The `~/.claude/` directory is the standard location for Claude Code configurations and hooks. This keeps all your Claude settings organized in one place and follows modern CLI best practices.
+
+## Configuration Options
+
+### Core Settings
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `cacheTTL` | number | `300` | Cache duration in seconds for git operations |
+| `maxLength` | number | `1000` | Maximum input length (security) |
+| `rightMargin` | number | `15` | Right margin for Claude telemetry compatibility |
+
+### Feature Toggles
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `noEmoji` | boolean | `false` | Force ASCII mode instead of Nerd Font symbols |
+| `noGitStatus` | boolean | `false` | Disable git status indicators completely |
+| `noContextWindow` | boolean | `false` | Disable context window usage display |
+| `envContext` | boolean | `false` | Show Node.js, Python, Docker versions |
+| `truncate` | boolean | `false` | Enable smart truncation for long statuslines |
+| `debugWidth` | boolean | `false` | Show terminal width detection debug info |
+
+### Advanced Settings
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `forceWidth` | number | `null` | Override terminal width detection (testing only) |
+| `noSoftWrap` | boolean | `false` | Disable soft-wrapping completely |
+| `softWrap` | boolean | `false` | Legacy soft-wrapping (not needed with `truncate: true`) |
+
+### Symbol Customization
+
+#### Nerd Font Symbols (Default)
+```json
+"symbols": {
+  "git": "",        // Git icon
+  "model": "󰚩",     // AI model icon
+  "contextWindow": "⚡︎", // Context window usage
+  "staged": "+",       // Staged changes
+  "conflict": "×",     // Merge conflicts
+  "stashed": "⚑",     // Stashed changes
+  "ahead": "⇡",        // Ahead of upstream
+  "behind": "⇣",       // Behind upstream
+  "diverged": "⇕",    // Both ahead and behind
+  "renamed": "»",     // Renamed files
+  "deleted": "✘"      // Deleted files
+}
+```
+
+#### ASCII Symbols (when `noEmoji: true`)
+```json
+"asciiSymbols": {
+  "git": "@",         // Git icon
+  "model": "*",        // AI model icon
+  "contextWindow": "#", // Context window usage
+  "staged": "+",       // Staged changes
+  "conflict": "C",     // Merge conflicts
+  "stashed": "$",     // Stashed changes
+  "ahead": "A",        // Ahead of upstream
+  "behind": "B",       // Behind upstream
+  "diverged": "D",    // Both ahead and behind
+  "renamed": ">",     // Renamed files
+  "deleted": "X"      // Deleted files
+}
+```
+
+## Complete Example Configuration
+
+### JSON Format
+```json
+{
+  "$schema": "https://raw.githubusercontent.com/shrwnsan/claude-statusline/main/config-schema.json",
+  "cacheTTL": 300,
+  "maxLength": 1000,
+  "noEmoji": false,
+  "noGitStatus": false,
+  "envContext": true,
+  "truncate": true,
+  "softWrap": false,
+  "rightMargin": 15,
+  "debugWidth": false,
+  "symbols": {
+    "git": "@",
+    "model": "*",
+    "staged": "+",
+    "conflict": "×",
+    "stashed": "⚑",
+    "ahead": "↑",
+    "behind": "↓",
+    "diverged": "⇕",
+    "renamed": "»",
+    "deleted": "✘"
+  }
+}
+```
+
+### YAML Format (more minimal syntax)
+```yaml
+cacheTTL: 300
+maxLength: 1000
+noEmoji: false
+noGitStatus: false
+envContext: true
+truncate: true
+softWrap: false
+rightMargin: 15
+debugWidth: false
+symbols:
+  git: "@"
+  model: "*"
+  staged: "+"
+  conflict: "×"
+  stashed: "⚑"
+  ahead: "↑"
+  behind: "↓"
+  diverged: "⇕"
+  renamed: "»"
+  deleted: "✘"
+```
+
+> **Note**: The `$schema` property in JSON provides VS Code/other editors with autocompletion and validation. It's JSON-specific and not used in YAML files.
+
+## Environment Variables (Legacy Support)
+
+Environment variables are still supported for backward compatibility. These work in both bash v1.0 and TypeScript v2.0:
+
+### Bash v1.0 & TypeScript v2.0 (Legacy)
+- `CLAUDE_CODE_STATUSLINE_NO_EMOJI=1` - Force ASCII mode
+- `CLAUDE_CODE_STATUSLINE_NO_GITSTATUS=1` - Disable git indicators
+- `CLAUDE_CODE_STATUSLINE_ENV_CONTEXT=1` - Show Node.js, Python, Docker versions
+- `CLAUDE_CODE_STATUSLINE_TRUNCATE=1` - Enable smart truncation
+
+### TypeScript v2.0 Only (New Features)
+- `CLAUDE_CODE_STATUSLINE_NO_SOFT_WRAP=1` - Disable soft-wrapping
+- `CLAUDE_CODE_STATUSLINE_DEBUG_WIDTH=1` - Enable width debugging
+- `CLAUDE_CODE_STATUSLINE_NO_CONTEXT_WINDOW=1` - Disable context window usage display
+
+> **Note**: Environment variables are considered legacy. Configuration files are recommended for better organization and more options.
+
+## Popular Configurations
+
+### Minimal Setup (Quick Start)
+```json
+{
+  "envContext": true,
+  "truncate": true
+}
+```
+
+### Developer Setup
+```json
+{
+  "envContext": true,
+  "truncate": true,
+  "noEmoji": false,
+  "debugWidth": false
+}
+```
+
+### ASCII-Only Setup
+```json
+{
+  "noEmoji": true,
+  "envContext": true,
+  "truncate": true,
+  "symbols": {
+    "git": "@",
+    "model": "*",
+    "staged": "+",
+    "conflict": "C",
+    "stashed": "$",
+    "ahead": "A",
+    "behind": "B",
+    "diverged": "D",
+    "renamed": ">",
+    "deleted": "X"
+  }
+}
+```
+
+### Performance-Optimized Setup
+```json
+{
+  "cacheTTL": 600,
+  "noGitStatus": false,
+  "envContext": false,
+  "truncate": true
+}
+```
+
+## File Formats Supported
+
+- `.claude-statusline.json` - JSON format (recommended for editor support)
+- `.claude-statusline.yaml` - YAML format (more minimal syntax)
+- `.claude-statusline.yml` - YAML format (deprecated, use `.yaml` instead)
+
+Both formats support exactly the same configuration options.

package/docs/guide-02-troubleshooting.md

@@ -0,0 +1,416 @@
+# Troubleshooting Guide
+
+This document provides comprehensive troubleshooting guidance for Claude Statusline.
+
+## Quick Diagnostics
+
+### Basic Health Check
+
+```bash
+# Check if script is executable
+ls -la /path/to/claude-statusline
+
+# Test script syntax
+bash -n /path/to/claude-statusline
+
+# Test basic functionality
+echo '{"workspace":{"current_dir":"'"$PWD"'"},"model":{"display_name":"Test"}}' | /path/to/claude-statusline
+```
+
+### Claude Code Integration Check
+
+```bash
+# Check settings.json configuration
+cat ~/.claude/settings.json | grep -A 5 statusLine
+
+# Test with Claude Code input format
+echo '{"workspace":{"current_dir":"'"$PWD"'"},"model":{"display_name":"Test Model"}}' | /path/to/claude-statusline
+
+# Check if symlink exists and is valid
+ls -la ~/.claude/statusline.sh
+readlink ~/.claude/statusline.sh
+```
+
+## Common Issues and Solutions
+
+### Issue: Statusline Not Appearing
+
+**Symptoms**: Claude Code shows default statusline or no statusline
+
+**Diagnostic Steps**:
+```bash
+# 1. Check settings.json configuration
+grep -A 5 statusLine ~/.claude/settings.json
+
+# 2. Verify script path is correct
+ls -la /path/to/claude-statusline
+
+# 3. Test script manually
+echo '{"workspace":{"current_dir":"'"$PWD"'"},"model":{"display_name":"Test"}}' | /path/to/claude-statusline
+
+# 4. Check script permissions
+chmod +x /path/to/claude-statusline
+```
+
+**Solutions**:
+1. **Update path in settings.json**:
+   ```json
+   {
+     "statusLine": {
+       "type": "command",
+       "command": "/correct/path/to/claude-statusline",
+       "padding": 0
+     }
+   }
+   ```
+
+2. **Create/update symlink**:
+   ```bash
+   ln -sf /path/to/claude-statusline ~/.claude/statusline.sh
+   ```
+
+3. **Restart Claude Code** after making changes
+
+### Issue: Nerd Font Symbols Not Displaying
+
+**Symptoms**: Square boxes, question marks, or missing symbols
+
+**Diagnostic Steps**:
+```bash
+# Test terminal font support
+echo " 󰚩 ⚑ ✘ ⇡ ⇣"
+
+# Check if Nerd Fonts are installed
+fc-list | grep -i nerd
+
+# Test with ASCII mode
+CLAUDE_CODE_STATUSLINE_NO_EMOJI=1 echo '{"workspace":{"current_dir":"'"$PWD"'"},"model":{"display_name":"Test"}}' | /path/to/claude-statusline
+```
+
+**Solutions**:
+1. **Install Nerd Fonts**:
+   ```bash
+   # Using Homebrew (macOS)
+   brew install font-jetbrains-mono-nerd-font
+   
+   # Or download from https://www.nerdfonts.com/
+   ```
+
+2. **Configure Terminal Font**:
+   - Terminal/iTerm2: Preferences → Profiles → Text → Font
+   - VS Code: Settings → `terminal.integrated.fontFamily`
+   - Alacritty: Edit `alacritty.yml` `font.family`
+
+3. **Force ASCII Mode**:
+   ```bash
+   export CLAUDE_CODE_STATUSLINE_NO_EMOJI=1
+   ```
+
+### Issue: Performance Problems
+
+**Symptoms**: Laggy updates, slow response, high CPU usage
+
+**Diagnostic Steps**:
+```bash
+# Measure execution time
+start=$(($(date +%s%N)/1000000))
+echo '{"workspace":{"current_dir":"'"$PWD"'"},"model":{"display_name":"Test"}}' | /path/to/claude-statusline > /dev/null
+end=$(($(date +%s%N)/1000000))
+duration=$((end - start))
+echo "Execution time: ${duration}ms"
+
+# Check cache directory
+ls -la /tmp/.claude-statusline-cache/
+
+# Test with minimal features
+CLAUDE_CODE_STATUSLINE_NO_GITSTATUS=1 CLAUDE_CODE_STATUSLINE_NO_EMOJI=1 \
+  echo '{"workspace":{"current_dir":"'"$PWD"'"},"model":{"display_name":"Test"}}' | /path/to/claude-statusline
+```
+
+**Solutions**:
+1. **Clear Cache**:
+   ```bash
+   rm -rf /tmp/.claude-statusline-cache/
+   ```
+
+2. **Disable Features**:
+   ```bash
+   export CLAUDE_CODE_STATUSLINE_NO_GITSTATUS=1
+   export CLAUDE_CODE_STATUSLINE_NO_EMOJI=1
+   ```
+
+3. **Check Git Repository Status**:
+   ```bash
+   # Test git operations in current directory
+   git status --porcelain
+   git rev-list --count --left-right @{upstream}...HEAD
+   ```
+
+### Issue: Git Status Not Showing
+
+**Symptoms**: No git indicators despite being in a git repository
+
+**Diagnostic Steps**:
+```bash
+# Check if in git repository
+git status
+
+# Test git commands manually
+git branch --show-current
+git status --porcelain
+
+# Check if git status disabled
+echo $CLAUDE_CODE_STATUSLINE_NO_GITSTATUS
+```
+
+**Solutions**:
+1. **Enable git status**:
+   ```bash
+   unset CLAUDE_CODE_STATUSLINE_NO_GITSTATUS
+   ```
+
+2. **Check git repository**:
+   ```bash
+   # Ensure you're in a git repository
+   cd /path/to/git/repo
+   git status
+   ```
+
+3. **Check git configuration**:
+   ```bash
+   # Check if git is properly configured
+   git config --list
+   ```
+
+### Issue: Environment Context Not Showing
+
+**Symptoms**: Node.js, Python, or Docker versions not displayed despite enabling
+
+**Diagnostic Steps**:
+```bash
+# Check if tools are available
+command -v node && node --version
+command -v python3 && python3 --version
+command -v docker && docker --version
+
+# Check cache files
+ls -la /tmp/.claude-statusline-cache/*_version
+
+# Test environment context explicitly
+CLAUDE_CODE_STATUSLINE_ENV_CONTEXT=1 \
+  echo '{"workspace":{"current_dir":"'"$PWD"'"},"model":{"display_name":"Test"}}' | /path/to/claude-statusline
+```
+
+**Solutions**:
+1. **Install Missing Tools**:
+   ```bash
+   # Install Node.js
+   curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
+   sudo apt-get install -y nodejs
+   
+   # Install Python
+   sudo apt-get install python3
+   
+   # Install Docker
+   curl -fsSL https://get.docker.com -o get-docker.sh
+   sudo sh get-docker.sh
+   ```
+
+2. **Clear Tool Cache**:
+   ```bash
+   rm -f /tmp/.claude-statusline-cache/*_version
+   rm -f /tmp/.claude-statusline-cache/*_version.time
+   ```
+
+3. **Enable Environment Context**:
+   ```bash
+   export CLAUDE_CODE_STATUSLINE_ENV_CONTEXT=1
+   ```
+
+### Issue: Width Management Problems
+
+**Symptoms**: Text cutoff, improper wrapping, or overflow
+
+**Diagnostic Steps**:
+```bash
+# Check terminal width
+tput cols
+echo $COLUMNS
+
+# Test with width override
+export COLUMNS=80
+echo '{"workspace":{"current_dir":"'"$PWD"'"},"model":{"display_name":"Test"}}' | /path/to/claude-statusline
+
+# Test with smart truncation enabled
+CLAUDE_CODE_STATUSLINE_TRUNCATE=1 \
+  echo '{"workspace":{"current_dir":"'"$PWD"'"},"model":{"display_name":"Sonnet 4.5"}}' | /path/to/claude-statusline
+```
+
+**Solutions**:
+1. **Adjust Terminal Width**:
+   - Increase terminal width to 80+ characters for optimal experience
+   - Use 100+ characters for full feature display
+
+2. **Enable Smart Truncation**:
+   ```bash
+   export CLAUDE_CODE_STATUSLINE_TRUNCATE=1
+   ```
+
+3. **Check Terminal Settings**:
+   - Ensure terminal reports correct dimensions
+   - Check for custom terminal configurations
+
+## Debug Mode
+
+### Enabling Debug Logging
+
+**TypeScript v2.0 (Node.js/Bun)**:
+```bash
+# Enable debug logging
+DEBUG=claude-statusline:* claude-statusline
+
+# Or with verbose flag
+claude-statusline --verbose
+```
+
+**Bash v1.0 (Legacy)**:
+For debugging statusline behavior, use bash built-in debugging:
+```bash
+# Enable execution tracing for one run
+bash -x /path/to/claude-statusline <<< '{"workspace":{"current_dir":"'"$PWD"'"},"model":{"display_name":"Test"}}'
+
+# Or enable for session
+set -x; /path/to/claude-statusline <<< '{"workspace":{"current_dir":"'"$PWD"'"},"model":{"display_name":"Test"}}'; set +x
+```
+
+Use `bash -x` for execution tracing and `bash -n` for syntax validation.
+
+**Note**: Previous versions supported `CLAUDE_STATUSLINE_LOG_LEVEL` environment variable, but this has been removed in favor of standard bash debugging tools.
+
+**Debugging Script Issues**:
+```bash
+# Run with bash debugging
+bash -x /path/to/claude-statusline
+
+# Check for syntax errors
+bash -n /path/to/claude-statusline
+```
+
+## Performance Profiling
+
+### Detailed Performance Analysis
+
+```bash
+# Create performance test script
+cat > test_performance.sh << 'EOF'
+#!/bin/bash
+
+iterations=10
+total=0
+
+echo "Testing performance over $iterations iterations..."
+
+for i in $(seq 1 $iterations); do
+    start=$(($(date +%s%N)/1000000))
+    echo '{"workspace":{"current_dir":"'"$PWD"'"},"model":{"display_name":"Test"}}' | /path/to/claude-statusline > /dev/null
+    end=$(($(date +%s%N)/1000000))
+    duration=$((end - start))
+    total=$((total + duration))
+    echo "Iteration $i: ${duration}ms"
+done
+
+average=$((total / iterations))
+echo "Average: ${average}ms"
+echo "Min: $(echo $durations | tr ' ' '\n' | sort -n | head -1)ms"
+echo "Max: $(echo $durations | tr ' ' '\n' | sort -n | tail -1)ms"
+
+# Store durations for analysis
+echo $durations > performance_data.txt
+EOF
+
+chmod +x test_performance.sh
+./test_performance.sh
+```
+
+### Cache Performance Testing
+
+```bash
+# Test first run (cache miss)
+rm -rf /tmp/.claude-statusline-cache/
+echo "First run (cache miss):"
+time echo '{"workspace":{"current_dir":"'"$PWD"'"},"model":{"display_name":"Test"}}' | /path/to/claude-statusline > /dev/null
+
+# Test subsequent runs (cache hit)
+echo "Subsequent runs (cache hit):"
+for i in {1..5}; do
+    time echo '{"workspace":{"current_dir":"'"$PWD"'"},"model":{"display_name":"Test"}}' | /path/to/claude-statusline > /dev/null
+done
+```
+
+## Getting Help
+
+### Collect Debug Information
+
+```bash
+# Create debug report
+cat > debug_report.txt << EOF
+=== Claude Statusline Debug Report ===
+Date: $(date)
+User: $(whoami)
+System: $(uname -a)
+
+=== Script Information ===
+Path: $(which claude-statusline 2>/dev/null || echo "Not found")
+Version: $(claude-statusline --version 2>/dev/null || echo "Unknown")
+Permissions: $(ls -la /path/to/claude-statusline)
+
+=== Environment ===
+Shell: $SHELL
+Terminal: $TERM
+Claude Statusline Variables:
+  CLAUDE_CODE_STATUSLINE_NO_EMOJI: $CLAUDE_CODE_STATUSLINE_NO_EMOJI
+  CLAUDE_CODE_STATUSLINE_NO_GITSTATUS: $CLAUDE_CODE_STATUSLINE_NO_GITSTATUS
+  CLAUDE_CODE_STATUSLINE_ENV_CONTEXT: $CLAUDE_CODE_STATUSLINE_ENV_CONTEXT
+  CLAUDE_CODE_STATUSLINE_TRUNCATE: $CLAUDE_CODE_STATUSLINE_TRUNCATE
+  CLAUDE_STATUSLINE_LOG_LEVEL: $CLAUDE_STATUSLINE_LOG_LEVEL
+
+=== Git Status ===
+Current Directory: $(pwd)
+Git Repository: $(git rev-parse --git-dir 2>/dev/null || echo "Not a git repository")
+Git Branch: $(git branch --show-current 2>/dev/null || echo "N/A")
+Git Status: $(git status --porcelain 2>/dev/null | wc -l) changes
+
+=== Tool Availability ===
+Node.js: $(command -v node >/dev/null && node --version || echo "Not found")
+Python: $(command -v python3 >/dev/null && python3 --version || echo "Not found")
+Docker: $(command -v docker >/dev/null && docker --version || echo "Not found")
+
+=== Cache Status ===
+Cache Directory: /tmp/.claude-statusline-cache/
+Cache Contents: $(ls -la /tmp/.claude-statusline-cache/ 2>/dev/null || echo "No cache directory")
+
+=== Test Run ===
+Test Output:
+$(echo '{"workspace":{"current_dir":"'"$PWD"'"},"model":{"display_name":"Test"}}' | /path/to/claude-statusline 2>&1)
+EOF
+
+echo "Debug report saved to debug_report.txt"
+```
+
+### Reporting Issues
+
+When reporting issues, include:
+1. **Debug report** (from above)
+2. **Expected vs actual output**
+3. **Steps to reproduce**
+4. **Your environment** (OS, terminal, Claude Code version)
+
+### Community Support
+
+- **GitHub Issues**: https://github.com/yourusername/claude-statusline/issues
+- **Discussions**: https://github.com/yourusername/claude-statusline/discussions
+- **Documentation**: https://github.com/yourusername/claude-statusline/blob/main/docs/README.md
+
+---
+
+**Note**: This troubleshooting guide covers the most common issues. If you encounter problems not covered here, please create an issue on GitHub with your debug information.