# ccusage-byobu Troubleshooting Guide

A comprehensive troubleshooting reference for the ccusage-byobu project. This guide covers common error scenarios, integration issues, and solutions for optimal performance.

## Table of Contents

1. [Quick Diagnostics](#quick-diagnostics)
2. [Installation Issues](#installation-issues)
3. [Configuration Problems](#configuration-problems)
4. [Runtime Errors](#runtime-errors)
5. [Display Issues](#display-issues)
6. [Performance Issues](#performance-issues)
7. [Claude Integration](#claude-integration)
8. [Environment Issues](#environment-issues)
9. [Debug and Logging](#debug-and-logging)
10. [Advanced Troubleshooting](#advanced-troubleshooting)

---

## Quick Diagnostics

**Run these commands first to quickly identify issues:**

```bash
# Test complete installation
ccusage-byobu --test

# Show current configuration
ccusage-byobu --config

# Check raw output
ccusage-byobu

# Enable debug mode for detailed info
CCUSAGE_BYOBU_DEBUG=1 ccusage-byobu
```

---

## Installation Issues

### Missing Dependencies

**Symptoms:**

- `ccusage command not found`
- `ccusage-byobu: command not found`
- `Node.js not found in PATH`

**Diagnostic Commands:**

```bash
# Check prerequisites
which node && node --version
which npm && npm --version
which ccusage && ccusage --version
which ccusage-byobu && ccusage-byobu --version
which byobu && byobu --version
```

**Solutions:**

1. **Install Node.js (version 18+):**

   ```bash
   # Using nvm (recommended)
   curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
   nvm install 18
   nvm use 18

   # Or download from https://nodejs.org/
   ```

2. **Install ccusage:**

   ```bash
   npm install -g ccusage

   # Verify installation
   ccusage --version
   ```

3. **Install ccusage-byobu:**

   ```bash
   npm install -g ccusage-byobu

   # Or from source
   git clone https://github.com/adawalli/ccusage-byobu.git
   cd ccusage-byobu
   npm install && npm link
   ```

4. **Install byobu:**

   ```bash
   # Ubuntu/Debian
   sudo apt-get install byobu

   # macOS
   brew install byobu

   # CentOS/RHEL
   sudo yum install byobu
   ```

### Permission Errors

**Symptoms:**

- `EACCES: permission denied`
- `EPERM: operation not permitted`
- `Permission denied creating byobu bin directory`

**Solutions:**

1. **Fix npm global permissions:**

   ```bash
   mkdir ~/.npm-global
   npm config set prefix '~/.npm-global'
   echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
   source ~/.bashrc
   npm install -g ccusage-byobu
   ```

2. **Manual byobu directory creation:**

   ```bash
   mkdir -p ~/.byobu/bin
   chmod 755 ~/.byobu/bin
   ```

3. **Fix script permissions:**

   ```bash
   # Make scripts executable
   chmod +x ~/.byobu/bin/*_ccusage

   # Check permissions
   ls -la ~/.byobu/bin/
   ```

### Version Compatibility

**Symptoms:**

- `SyntaxError: Unexpected token 'import'`
- `ReferenceError: fetch is not defined`

**Solutions:**

1. **Update Node.js to version 18+:**

   ```bash
   node --version  # Should be 18.0.0 or higher

   # Update if needed
   nvm install 18 && nvm use 18
   ```

2. **Clear npm cache if needed:**
   ```bash
   npm cache clean --force
   npm install -g ccusage-byobu
   ```

---

## Configuration Problems

### Invalid Environment Variables

**Symptoms:**

- `Invalid value for CCUSAGE_BYOBU_THRESHOLD`
- `Invalid refresh interval`
- `Invalid plan type`

**Diagnostic Commands:**

```bash
# Check all ccusage-related variables
env | grep -E "CLAUDE|CCUSAGE"

# View configuration errors
ccusage-byobu --config
```

**Solutions:**

1. **Valid threshold values (0-100):**

   ```bash
   export CCUSAGE_BYOBU_THRESHOLD="80"  # Valid
   unset CCUSAGE_BYOBU_THRESHOLD="abc"  # Invalid
   ```

2. **Valid refresh intervals (5-3600 seconds):**

   ```bash
   export CCUSAGE_BYOBU_REFRESH="60"    # Valid
   unset CCUSAGE_BYOBU_REFRESH="0"      # Invalid (too low)
   unset CCUSAGE_BYOBU_REFRESH="5000"   # Invalid (too high)
   ```

3. **Valid plan types:**

   ```bash
   # Current valid plan types
   export CLAUDE_PLAN_TYPE="free"       # Valid
   export CLAUDE_PLAN_TYPE="pro"        # Valid
   export CLAUDE_PLAN_TYPE="max_5x"     # Valid
   export CLAUDE_PLAN_TYPE="max_20x"    # Valid
   export CLAUDE_PLAN_TYPE="enterprise" # Valid

   # Legacy plan migration
   unset CLAUDE_PLAN_TYPE="team"        # Legacy - use migration tool
   ```

### Legacy Plan Type Migration

**Symptoms:**

- `Legacy plan type detected: "team"`
- Plan migration warnings

**Solutions:**

1. **Use migration tool:**

   ```bash
   ./install-ccusage-byobu.sh --migrate
   ```

2. **Manual migration:**

   ```bash
   # Replace legacy 'team' plan
   unset CLAUDE_PLAN_TYPE
   export CLAUDE_PLAN_TYPE="max_5x"  # or "max_20x" for high usage

   # Update shell profile
   sed -i 's/CLAUDE_PLAN_TYPE="team"/CLAUDE_PLAN_TYPE="max_5x"/' ~/.bashrc
   source ~/.bashrc
   ```

### Configuration File Issues

**Symptoms:**

- `Configuration file not found`
- `Invalid JSON in configuration file`
- `Configuration validation errors`

**Solutions:**

1. **Fix JSON syntax:**

   ```bash
   # Validate JSON file
   cat ~/.ccusage-byobu.json | jq .

   # Example valid JSON
   cat > ~/.ccusage-byobu.json << 'EOF'
   {
     "CLAUDE_PLAN_TYPE": "pro",
     "CCUSAGE_BYOBU_FORMAT": "full",
     "CCUSAGE_BYOBU_COLORS": "true",
     "CCUSAGE_BYOBU_THRESHOLD": "80"
   }
   EOF
   ```

2. **Check file permissions:**

   ```bash
   chmod 644 ~/.ccusage-byobu.json
   ```

3. **Environment file format:**
   ```bash
   # Example .env format
   cat > ~/.ccusage.env << 'EOF'
   CLAUDE_PLAN_TYPE="pro"
   CCUSAGE_BYOBU_FORMAT="full"
   CCUSAGE_BYOBU_COLORS="true"
   CCUSAGE_BYOBU_THRESHOLD="80"
   EOF
   ```

---

## Runtime Errors

### ccusage Command Execution Failures

**Symptoms:**

- `Failed to execute ccusage command`
- `ccusage command timed out`
- `ccusage command failed with exit code N`

**Diagnostic Commands:**

```bash
# Test ccusage directly
ccusage blocks --json --offline

# Check ccusage configuration
ccusage --help

# Test with timeout
timeout 30s ccusage blocks --json --offline
```

**Solutions:**

1. **Command not found (ENOENT):**

   ```bash
   # Reinstall ccusage
   npm install -g ccusage

   # Check PATH
   echo $PATH | grep npm
   ```

2. **Permission denied (EACCES):**

   ```bash
   # Check ccusage permissions
   ls -la $(which ccusage)

   # Fix if needed
   chmod +x $(which ccusage)
   ```

3. **Timeout issues:**

   ```bash
   # Check network connectivity
   ping api.anthropic.com

   # Test offline mode
   ccusage blocks --json --offline

   # Increase timeout (30s default)
   # Code automatically handles timeouts
   ```

4. **API authentication issues:**

   ```bash
   # Check Claude credentials
   ccusage auth status

   # Re-authenticate if needed
   ccusage auth login
   ```

### JSON Parsing Errors

**Symptoms:**

- `Failed to parse ccusage JSON output`
- `Invalid ccusage output: expected JSON object`
- `Unexpected token in JSON`

**Diagnostic Commands:**

```bash
# Check raw ccusage output
ccusage blocks --json --offline > /tmp/ccusage-output.json
cat /tmp/ccusage-output.json

# Validate JSON
jq . /tmp/ccusage-output.json
```

**Solutions:**

1. **Corrupted output:**

   ```bash
   # Clear any cached data
   ccusage cache clear

   # Test fresh output
   ccusage blocks --json --offline
   ```

2. **Unexpected output format:**

   ```bash
   # Check ccusage version compatibility
   ccusage --version

   # Update if needed
   npm update -g ccusage
   ```

3. **Debug JSON parsing:**
   ```bash
   CCUSAGE_BYOBU_DEBUG=1 ccusage-byobu
   # Look for "JSON Parse Error" details
   ```

### Process and Memory Issues

**Symptoms:**

- `Process killed by signal SIGTERM`
- High memory usage
- Hanging processes

**Solutions:**

1. **Process cleanup:**

   ```bash
   # Kill hanging ccusage processes
   pkill -f ccusage

   # Restart byobu
   byobu kill-server && byobu
   ```

2. **Memory optimization:**

   ```bash
   # Disable debug mode
   unset CCUSAGE_BYOBU_DEBUG

   # Use compact format
   export CCUSAGE_BYOBU_FORMAT="compact"

   # Increase refresh interval
   export CCUSAGE_BYOBU_REFRESH="120"
   ```

---

## Display Issues

### Byobu Status Not Updating

**Symptoms:**

- Status bar shows old data
- No ccusage information in byobu
- Empty status bar section

**Diagnostic Commands:**

```bash
# Check installed scripts
ls -la ~/.byobu/bin/*ccusage*

# Test script manually
~/.byobu/bin/60_ccusage

# Check byobu status configuration
byobu-status --list
```

**Solutions:**

1. **Script not installed:**

   ```bash
   ccusage-byobu --install

   # Or reinstall with specific interval
   ccusage-byobu --uninstall
   ccusage-byobu --install --refresh=60
   ```

2. **Script not executable:**

   ```bash
   chmod +x ~/.byobu/bin/*_ccusage
   ```

3. **Byobu configuration:**

   ```bash
   # Restart byobu server
   byobu kill-server
   byobu

   # Check byobu status
   byobu-status
   ```

4. **Multiple script conflicts:**

   ```bash
   # List all installed scripts
   ls ~/.byobu/bin/*_ccusage

   # Remove conflicting scripts
   ccusage-byobu --uninstall-all
   ccusage-byobu --install --refresh=60
   ```

### Color and Formatting Issues

**Symptoms:**

- No colors in output
- Malformed progress bars
- Incorrect text formatting

**Solutions:**

1. **Terminal color support:**

   ```bash
   # Test color support
   echo $TERM

   # Force colors
   export CCUSAGE_BYOBU_COLORS="true"

   # Or disable colors
   export CCUSAGE_BYOBU_COLORS="false"
   ```

2. **Progress bar formatting:**

   ```bash
   # Switch to compact format if full format has issues
   export CCUSAGE_BYOBU_FORMAT="compact"

   # Test output
   ccusage-byobu
   ```

3. **Font and encoding issues:**

   ```bash
   # Check locale
   locale

   # Set UTF-8 if needed
   export LC_ALL=en_US.UTF-8
   export LANG=en_US.UTF-8
   ```

### Incorrect Usage Data

**Symptoms:**

- Wrong time remaining
- Incorrect cost calculations
- Missing session data

**Solutions:**

1. **Session synchronization:**

   ```bash
   # Refresh ccusage data
   ccusage sync

   # Clear cache
   ccusage cache clear
   ```

2. **Plan type mismatch:**

   ```bash
   # Verify plan type
   ccusage account info

   # Update environment
   export CLAUDE_PLAN_TYPE="your_actual_plan"
   ```

---

## Performance Issues

### Slow Response Times

**Symptoms:**

- Long delays before status updates
- High CPU usage
- Frequent timeouts

**Diagnostic Commands:**

```bash
# Benchmark performance
ccusage-byobu-benchmark

# Check with debug info
CCUSAGE_BYOBU_DEBUG=1 ccusage-byobu
```

**Solutions:**

1. **Enable caching:**

   ```bash
   # Enable caching for interactive use
   export CCUSAGE_ENABLE_CACHE="1"

   # Adjust cache settings
   export CCUSAGE_BYOBU_CACHE_CLEANUP_INTERVAL="30000"
   export CCUSAGE_BYOBU_CACHE_MAX_KEYS="100"
   ```

2. **Optimize refresh interval:**

   ```bash
   # Increase refresh interval
   ccusage-byobu --uninstall
   ccusage-byobu --install --refresh=120
   ```

3. **Reduce processing overhead:**
   ```bash
   export CCUSAGE_BYOBU_FORMAT="compact"
   export CCUSAGE_BYOBU_COLORS="false"
   unset CCUSAGE_BYOBU_DEBUG
   ```

### Memory Usage Problems

**Symptoms:**

- High memory consumption
- Memory leaks
- System slowdown

**Solutions:**

1. **Monitor memory usage:**

   ```bash
   # Check memory usage
   CCUSAGE_BYOBU_DEBUG=1 ccusage-byobu --test

   # Look for memory growth patterns
   ```

2. **Cache optimization:**

   ```bash
   # Limit cache size
   export CCUSAGE_BYOBU_CACHE_MAX_KEYS="50"
   export CCUSAGE_BYOBU_CACHE_CLEANUP_INTERVAL="15000"

   # Or disable caching entirely
   unset CCUSAGE_ENABLE_CACHE
   ```

3. **Process management:**

   ```bash
   # Kill old processes
   pkill -f ccusage-byobu

   # Restart byobu
   byobu kill-server && byobu
   ```

### Cache Performance Issues

**Symptoms:**

- Cache misses despite enabled caching
- Inconsistent performance
- Cache-related errors

**Solutions:**

1. **Cache configuration:**

   ```bash
   # Enable cache explicitly
   export CCUSAGE_ENABLE_CACHE="1"

   # Check cache stats
   CCUSAGE_BYOBU_DEBUG=1 ccusage-byobu --test | grep -A 10 "Cache Statistics"
   ```

2. **Cache troubleshooting:**

   ```bash
   # Clear cache
   rm -rf ~/.cache/ccusage* 2>/dev/null

   # Restart with fresh cache
   ccusage-byobu
   ```

---

## Claude Integration

### API Key and Authentication Issues

**Symptoms:**

- `Authentication failed`
- `API key not found`
- `Unauthorized` errors

**Solutions:**

1. **Check Claude authentication:**

   ```bash
   # Check auth status
   ccusage auth status

   # Re-authenticate
   ccusage auth login
   ```

2. **API key configuration:**

   ```bash
   # Check if API key is set
   echo $CLAUDE_API_KEY

   # Or check ccusage config
   ccusage config list
   ```

3. **Configuration directory:**

   ```bash
   # Check Claude config directory
   echo $CLAUDE_CONFIG_DIR
   ls -la ~/.claude/

   # Set if needed
   export CLAUDE_CONFIG_DIR="$HOME/.claude"
   ```

### Plan Type and Limit Issues

**Symptoms:**

- Wrong usage limits displayed
- Incorrect plan type warnings
- Usage calculations don't match Claude Code

**Solutions:**

1. **Verify actual plan:**

   ```bash
   # Check your actual Claude plan
   ccusage account info

   # Update environment variable
   export CLAUDE_PLAN_TYPE="your_actual_plan_type"
   ```

2. **Plan type validation:**

   ```bash
   # Valid plan types (2024)
   export CLAUDE_PLAN_TYPE="free"       # Free tier
   export CLAUDE_PLAN_TYPE="pro"        # Pro plan
   export CLAUDE_PLAN_TYPE="max_5x"     # Max 5x plan
   export CLAUDE_PLAN_TYPE="max_20x"    # Max 20x plan
   export CLAUDE_PLAN_TYPE="enterprise" # Enterprise
   ```

3. **Usage sync issues:**

   ```bash
   # Force usage sync
   ccusage sync --force

   # Clear local cache
   ccusage cache clear
   ```

### Rate Limiting

**Symptoms:**

- `Rate limit exceeded`
- Frequent request failures
- Slow API responses

**Solutions:**

1. **Increase refresh interval:**

   ```bash
   # Reduce API call frequency
   ccusage-byobu --uninstall
   ccusage-byobu --install --refresh=300  # 5 minutes
   ```

2. **Enable caching:**

   ```bash
   export CCUSAGE_ENABLE_CACHE="1"
   ```

3. **Optimize usage:**
   ```bash
   # Use offline mode when possible
   ccusage blocks --json --offline
   ```

---

## Environment Issues

### Operating System Compatibility

**macOS Issues:**

```bash
# Install dependencies via Homebrew
brew install node npm byobu

# Fix PATH issues
echo 'export PATH="/opt/homebrew/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
```

**Linux Distribution Issues:**

```bash
# Ubuntu/Debian
sudo apt-get update
sudo apt-get install nodejs npm byobu

# CentOS/RHEL
sudo yum install nodejs npm
sudo yum install byobu

# Arch Linux
sudo pacman -S nodejs npm byobu
```

**Windows (WSL) Issues:**

```bash
# Install Node.js in WSL
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs

# Install byobu
sudo apt-get install byobu
```

### Shell Compatibility

**Bash Configuration (`~/.bashrc`):**

```bash
# Add to ~/.bashrc
export CLAUDE_PLAN_TYPE="pro"
export CCUSAGE_BYOBU_FORMAT="full"
export CCUSAGE_BYOBU_REFRESH="60"
export PATH="$HOME/.npm-global/bin:$PATH"
```

**Zsh Configuration (`~/.zshrc`):**

```bash
# Add to ~/.zshrc
export CLAUDE_PLAN_TYPE="pro"
export CCUSAGE_BYOBU_FORMAT="full"
export CCUSAGE_BYOBU_REFRESH="60"
export PATH="$HOME/.npm-global/bin:$PATH"
```

**Fish Configuration (`~/.config/fish/config.fish`):**

```fish
# Add to config.fish
set -x CLAUDE_PLAN_TYPE "pro"
set -x CCUSAGE_BYOBU_FORMAT "full"
set -x CCUSAGE_BYOBU_REFRESH "60"
set -x PATH "$HOME/.npm-global/bin" $PATH
```

### tmux vs byobu Compatibility

**tmux Integration:**

```bash
# Add to ~/.tmux.conf
set -g status-right '#(ccusage-byobu 2>/dev/null) | %Y-%m-%d %H:%M'
set -g status-interval 60

# Reload config
tmux source-file ~/.tmux.conf
```

**byobu-tmux Backend:**

```bash
# Check byobu backend
byobu-launcher-install

# Switch to tmux backend if needed
byobu-select-backend tmux
```

---

## Debug and Logging

### Enable Debug Mode

```bash
# Enable comprehensive debugging
export CCUSAGE_BYOBU_DEBUG="1"

# Run with debug output
ccusage-byobu 2>&1 | tee debug.log

# Test with debug info
ccusage-byobu --test 2>&1 | tee test-debug.log
```

### Performance Debugging

```bash
# Run performance benchmark
ccusage-byobu-benchmark all --iterations=20

# Check startup performance
CCUSAGE_BYOBU_DEBUG=1 ccusage-byobu

# Monitor memory usage
CCUSAGE_BYOBU_DEBUG=1 ccusage-byobu --test | grep -A 20 "Memory Profiling"
```

### Log Analysis

**Common Debug Output Patterns:**

1. **Cache Performance:**

   ```
   Cache hit - retrieved cached result in 0.123ms
   Cache miss - executed ccusage command in 95.23ms
   ```

2. **JSON Parsing:**

   ```
   JSON parsed in 2.15ms
   JSON size: 1.23KB
   Parse throughput: 572.09KB/ms
   ```

3. **Memory Usage:**

   ```
   Startup memory: RSS 25MB, Heap 15MB
   Memory growth: 3MB RSS, 1.2MB Heap
   ```

4. **Performance Summary:**
   ```
   Performance Summary:
     Session duration: 12.3s
     Memory: Current 25MB RSS, Peak 28MB RSS
   ```

### Log File Locations

```bash
# Check common log locations
ls -la ~/.byobu/
ls -la ~/.cache/ccusage*
ls -la /tmp/ccusage*

# Byobu logs
ls -la ~/.byobu/.tmux.conf
cat ~/.byobu/status
```

---

## Advanced Troubleshooting

### Network and Connectivity

**Test connectivity:**

```bash
# Test API connectivity
curl -I https://api.anthropic.com

# Test ccusage API calls
ccusage auth status

# Test with different timeouts
timeout 10s ccusage blocks --json --offline
```

**Proxy configuration:**

```bash
# Set proxy if needed
export HTTP_PROXY="http://proxy.company.com:8080"
export HTTPS_PROXY="http://proxy.company.com:8080"

# Test with proxy
ccusage blocks --json --offline
```

### Process Debugging

**Check running processes:**

```bash
# Find ccusage processes
ps aux | grep ccusage

# Check byobu processes
ps aux | grep byobu

# Monitor process lifecycle
strace -e trace=process ccusage-byobu
```

**Resource monitoring:**

```bash
# Monitor during execution
top -p $(pgrep ccusage)

# Check file descriptors
lsof -p $(pgrep ccusage)

# Monitor system calls
strace -c ccusage-byobu
```

### File System Issues

**Permission debugging:**

```bash
# Check file permissions
ls -la ~/.byobu/bin/
ls -la $(which ccusage)
ls -la $(which ccusage-byobu)

# Check directory permissions
ls -ld ~/.byobu/
ls -ld ~/.npm-global/

# Test file access
test -r ~/.byobu/bin/60_ccusage && echo "readable" || echo "not readable"
test -x ~/.byobu/bin/60_ccusage && echo "executable" || echo "not executable"
```

**Disk space issues:**

```bash
# Check disk space
df -h ~
df -h /tmp

# Check for large cache files
du -sh ~/.cache/
du -sh ~/.npm/
```

### Recovery Procedures

**Complete reset:**

```bash
# 1. Remove all ccusage-byobu components
ccusage-byobu --uninstall-all
npm uninstall -g ccusage-byobu

# 2. Clear caches
rm -rf ~/.cache/ccusage* 2>/dev/null
npm cache clean --force

# 3. Remove configuration
rm -f ~/.ccusage-byobu.json ~/.ccusage.env

# 4. Reinstall
npm install -g ccusage-byobu
ccusage-byobu --test
```

**Byobu reset:**

```bash
# Reset byobu configuration
mv ~/.byobu ~/.byobu.backup
byobu-config

# Reinstall ccusage integration
ccusage-byobu --install
```

**Environment reset:**

```bash
# Clear all ccusage environment variables
unset $(env | grep -E "^(CLAUDE|CCUSAGE)" | cut -d= -f1)

# Reload shell configuration
source ~/.bashrc  # or ~/.zshrc
```

---

## Getting Help

### Support Resources

1. **Built-in diagnostics:**

   ```bash
   ccusage-byobu --help
   ccusage-byobu --test
   ccusage-byobu --config
   ```

2. **Community support:**
   - GitHub Issues: [ccusage-byobu/issues](https://github.com/adawalli/ccusage-byobu/issues)
   - Documentation: [USAGE_EXAMPLES.md](USAGE_EXAMPLES.md)

3. **Upstream tools:**
   - ccusage: [anthropics/ccusage](https://github.com/anthropics/ccusage)
   - byobu: [byobu.org](https://byobu.org/)

### Creating Bug Reports

**Gather information:**

```bash
# System information
uname -a
node --version
npm --version
ccusage --version
ccusage-byobu --version 2>/dev/null || echo "not installed"

# Configuration
ccusage-byobu --config

# Test results
ccusage-byobu --test

# Debug output
CCUSAGE_BYOBU_DEBUG=1 ccusage-byobu 2>&1 | head -50
```

**Include in bug report:**

- Operating system and version
- Node.js and npm versions
- Complete error messages
- Steps to reproduce
- Configuration settings
- Debug output (if applicable)

---

_This troubleshooting guide covers the most common issues. For additional help, run `ccusage-byobu --test` to diagnose your specific setup._