Troubleshooting Guide

Quick Diagnostics

Before diving into specific issues, run these checks:

Verify Installation

ls -la .claude/statusline.sh
cat .claude/settings.json

Test Script Manually

echo '{}' | .claude/statusline.sh

Check Dependencies

jq --version
git --version
node --version

Preview Output

cc-statusline preview .claude/statusline.sh

Common Issues

Statusline Not Showing

From README.md:228-232, this is the most common issue.

1. Restart Claude Code

Symptom: Statusline doesn’t appear after installationSolution: Always restart Claude Code after installation

# Exit Claude Code completely and restart
# Changes only take effect on restart

Claude Code only reads settings.json on startup

2. Verify Settings

Symptom: Statusline still not showing after restartSolution: Check .claude/settings.json contains correct configuration

cat .claude/settings.json

Should contain:

{
  "statusLine": {
    "type": "command",
    "command": ".claude/statusline.sh",
    "padding": 0
  }
}

Ensure the command path matches your installation type (global vs project)

3. Check Permissions

Symptom: Script exists but doesn’t executeSolution: Ensure script is executable

chmod +x .claude/statusline.sh

Verify:

ls -la .claude/statusline.sh
# Should show: -rwxr-xr-x (executable)

4. Manual Configuration

Symptom: Auto-configuration failed during installationSolution: Manually add configuration to .claude/settings.jsonFrom README.md:217-224:

{
  "statusLine": {
    "type": "command",
    "command": ".claude/statusline.sh",
    "padding": 0
  }
}

Performance Issues

From README.md:234-237, slow statusline execution.

Test Performance

Symptom: Statusline is slow to updateDiagnostic:

cc-statusline preview .claude/statusline.sh

Look for execution time in output:

📊 Performance: 🚀 excellent (67ms)

Performance targets from README.md:246-253:

Excellent: <100ms ✅
Good: 100-500ms ⚠️
Slow: >500ms 🐌

Optimize Features

Solution: Disable expensive featuresHeavy features in order of impact:

ccusage integration - Network requests, spawns external process
Token statistics - Requires parsing large usage data
Session reset time - Complex time calculations
Burn rate - Multiple calculations

Minimal fast configuration:

cc-statusline init
# Select only:
# - 📁 Working Directory
# - 🌿 Git Branch  
# - 🤖 Model Name
# - 🧠 Context Remaining

Disable ccusage

Solution: If you don’t need cost trackingRegenerate without usage features:

cc-statusline init
# Deselect:
# - 💵 Usage & Cost
# - 📊 Token Statistics
# - ⚡ Burn Rate
# - ⌛ Session Reset Time

This eliminates the npx ccusage@latest call which can add 100-500ms.

Missing Features

From README.md:239-244, features not displaying.

Install jq

Symptom: Missing context percentage, tokens, or session timeCause: jq is not installedFrom README.md:38-42:

Without jq, your statusline will have LIMITED functionality:

❌ No context remaining percentage

❌ No token statistics from ccusage

❌ No session timer

⚠️ Basic fallback parser is used (less reliable)

Solution: Install jq for your platform

brew install jq

Verify installation:

jq --version
# Should output: jq-1.6 or higher

ccusage Setup

Symptom: No cost or usage statisticsSolution: ccusage works automatically via npxFrom README.md:92:

ccusage - For usage stats (works via npx - no install needed)

Verify ccusage works:

npx ccusage@latest

If this hangs or fails, check:

Network connectivity
npm/npx installation
Firewall settings

ccusage is called automatically when usage features are enabled. No manual setup required!

Git Not Found

Symptom: No branch name displayedSolution: Install git

brew install git

Verify:

git --version

Git branch feature gracefully falls back to showing nothing if git is not installed

Context Not Showing

Symptom: Context shows “TBD” or missingCauses:

jq not installed (see above)
Not in an active Claude Code session
No context usage data available yet

Solution:

# 1. Install jq
jq --version

# 2. Start a Claude Code session and send some messages
# Context data only appears after you've used some context

# 3. Check if context data is in input
# Enable debug logging and check .claude/statusline.log

Colors Not Working

Symptom: No colors or emojis in outputCause: NO_COLOR environment variable is setSolution:

# Check if NO_COLOR is set
echo $NO_COLOR

# Unset it if you want colors
unset NO_COLOR

# Or remove from shell profile (.bashrc, .zshrc, etc.)

From README.md:197: cc-statusline honors NO_COLOR environment variable

Installation Errors

Permission Denied During Install

Symptom:

Error: EACCES: permission denied, mkdir '/home/user/.claude'

Solution:

# Don't use sudo! Instead, fix ownership:
sudo chown -R $USER:$USER ~/.claude

# Then retry:
cc-statusline init

Node.js Version Too Old

Symptom:

Error: The engine "node" is incompatible with this module

Cause: Requires Node.js 16+Solution:

# Check current version
node --version

# Update Node.js (using nvm)
nvm install 20
nvm use 20

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

Settings Update Failed

Symptom:

Warning: Could not update settings.json

Cause: Invalid JSON in existing settings.jsonSolution:

# Validate JSON syntax
cat .claude/settings.json | jq .

# If invalid, fix syntax errors or recreate:
echo '{}' > .claude/settings.json

# Then manually add statusLine configuration

Debug Logging

Enable detailed logging to diagnose issues:

Enable Logging

During cc-statusline init, select “Yes” for debug logging.Or regenerate with logging:

cc-statusline init
# Select: 📝 Enable debug logging to .claude/statusline.log?
# Choose: Yes

Trigger Statusline

Use Claude Code normally or run preview:

cc-statusline preview .claude/statusline.sh

Read Logs

cat .claude/statusline.log

Look for:

Input JSON from Claude Code
Whether jq is being used
Extracted values for each feature

Example log output: From bash-generator.ts:65-83:

[2026-03-04 10:30:15] Status line triggered (cc-statusline v1.4.0)
[2026-03-04 10:30:15] Input:
{
  "workspace": {
    "current_dir": "/home/user/project"
  },
  "model": {
    "display_name": "Sonnet 4"
  }
}
[2026-03-04 10:30:15] Using jq for JSON parsing
---
[2026-03-04 10:30:15] Extracted: dir=~/project, model=Sonnet 4, version=, git=main, context=83%, cost=, cost_ph=, tokens=, tpm=, session_pct=
[2026-03-04 10:30:15] Note: Context, tokens, and session info require jq for full functionality

Empty values in “Extracted” line indicate missing data or disabled features

Platform-Specific Issues

Windows

Bash Not Found

Symptom:

'bash' is not recognized as an internal or external command

Solution: Install Git for Windows (includes bash)

winget install Git.Git

Or install WSL:

wsl --install

Path Separators

Symptom: Paths show with backslashes instead of forward slashesSolution: The statusline automatically converts backslashesFrom bash-generator.ts:103-106:

// Convert escaped backslashes to forward slashes for Windows paths
if [ -n "$value" ]; then
  value=$(echo "$value" | sed 's/\\\\/\//g')
fi

This is handled automatically - no action needed.

macOS

Command Not Found: cc-statusline

Symptom: cc-statusline: command not foundSolution: Use npx instead of global install

npx @chongdashu/cc-statusline@latest init

Or install globally:

npm install -g @chongdashu/cc-statusline

Linux

jq Not in PATH

Symptom: jq installed but not foundSolution:

# Find jq location
which jq

# Add to PATH in ~/.bashrc or ~/.zshrc
export PATH="$PATH:/usr/local/bin"

# Reload shell
source ~/.bashrc

Advanced Troubleshooting

Inspect Generated Script

Manually review the generated bash script:

less .claude/statusline.sh

Check for:

Shebang line: #!/bin/bash
Version: STATUSLINE_VERSION="1.4.0"
Feature flags: Verify selected features are included
Syntax errors: Run bash -n .claude/statusline.sh

Test JSON Parsing

Test the JSON extraction manually:

# Create test input
echo '{
  "workspace": {"current_dir": "/home/user/test"},
  "model": {"display_name": "Claude Sonnet"}
}' | .claude/statusline.sh

Should output statusline with test data.

Check for Conflicting Statuslines

From installer.ts:72-90, cc-statusline detects conflicts:

# Check for other statusline commands
grep -r "statusLine" ~/.claude/settings.json .claude/settings.json 2>/dev/null

If you see a different command, you may need to replace it.

Getting Help

If you’re still stuck:

Gather Information

# System info
uname -a
node --version
jq --version
git --version

# Installation check
ls -la .claude/
cat .claude/settings.json

# Preview output
cc-statusline preview .claude/statusline.sh

Check Debug Logs

cat .claude/statusline.log

Report Issue

Open an issue at: https://github.com/chongdashu/cc-statusline/issuesInclude:

Operating system and version
Node.js version
Complete error message
Output of preview command
Debug logs (if enabled)

Common Error Messages

USER_CANCELLED_OVERWRITE

Meaning: You declined to overwrite existing statusline.shAction: Run cc-statusline init again and confirm overwrite, or manually edit the existing file

SETTINGS_UPDATE_FAILED

Meaning: Could not automatically update settings.jsonAction: Manually add statusLine configuration (see README.md:217-224)

oldString not found in content

Meaning: Internal error during script generationAction: Delete .claude/statusline.sh and regenerate

Prevention Tips

Best practices to avoid issues:

Always restart Claude Code after installation or changes
Install jq first before running init for full functionality
Use preview command before installing to catch issues early
Keep backups of working configurations
Enable debug logging during initial setup
Start minimal - add features gradually if you have issues

Getting Started

Features

Guides

Quick Diagnostics

Common Issues

Statusline Not Showing

Performance Issues

Missing Features

Installation Errors

Debug Logging

Platform-Specific Issues

Windows

macOS

Linux

Advanced Troubleshooting

Inspect Generated Script

Test JSON Parsing

Check for Conflicting Statuslines

Getting Help

Common Error Messages

Prevention Tips

Next Steps

Performance Guide

Configuration Guide

Build docs developers (and LLMs) love

Getting Started

Features

Guides

​Quick Diagnostics

​Common Issues

​Statusline Not Showing

​Performance Issues

​Missing Features

​Installation Errors

​Debug Logging

​Platform-Specific Issues

​Windows

​macOS

​Linux

​Advanced Troubleshooting

​Inspect Generated Script

​Test JSON Parsing

​Check for Conflicting Statuslines

​Getting Help

​Common Error Messages

​Prevention Tips

​Next Steps

Performance Guide

Configuration Guide

Build docs developers (and LLMs) love

Quick Diagnostics

Common Issues

Statusline Not Showing

Performance Issues

Missing Features

Installation Errors

Debug Logging

Platform-Specific Issues

Windows

macOS

Linux

Advanced Troubleshooting

Inspect Generated Script

Test JSON Parsing

Check for Conflicting Statuslines

Getting Help

Common Error Messages

Prevention Tips

Next Steps