A beautiful, informative statusline for Claude Code

Real-time directory, git branch, model info, costs, and session time tracking

One command. Three questions. Custom statusline.

npx @chongdashu/cc-statusline@latest init

That's it! Answer a few simple questions, restart Claude Code, and enjoy your new statusline.

• Node.js 16+ - Required for the CLI tool
• Claude Code - The tool you're already using

• jq - JSON processor for advanced features (see installation guide below)
  • Required for: context tracking, token stats, session timer
  • Without jq: basic features still work with fallback parser

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)

brew install jq

# Ubuntu/Debian
sudo apt-get install jq

# CentOS/RHEL/Fedora
sudo yum install jq

# Arch Linux
sudo pacman -S jq

Option 1: Package Manager (Recommended)

# Chocolatey
choco install jq

# Scoop
scoop install jq

# Winget
winget install jqlang.jq

Option 2: Manual Download

1. Go to https://github.com/jqlang/jq/releases/latest
2. Download:
   • 64-bit: jq-windows-amd64.exe
   • 32-bit: jq-windows-i386.exe
3. Rename to jq.exe
4. Place in C:\Windows\System32\ (requires admin) or add to PATH
5. Test: jq --version

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

• git - For branch display (you probably have this)
• ccusage - For usage stats (works via npx - no install needed)

Enhance your Claude Code terminal with useful information:

• 📁 Directory Display - Current folder with ~ abbreviation
• 🌿 Git Integration - Current branch name
• 🤖 Model Info - Shows which Claude model you're using plus Claude Code version
• 🧠 Context Usage - Real-time context window usage with progress bars (requires jq)
• 💰 Cost Tracking - Live cost monitoring with burn rates via ccusage (partial without jq)
• ⌛ Session Timer - Time remaining until usage limit resets (requires jq)
• 📊 Token Analytics - Token consumption and burn rate metrics (requires jq)
• 🎨 Color Support - 256-color palette for Claude Code terminals
• ⚡ Fast Execution - Optimized bash script with <100ms execution time

• 🏠 Global Installation (~/.claude/) - Use across all your projects
• 📂 Project Installation (./.claude/) - Keep settings project-specific

New 3-Line Modern Layout (v1.2.2+):

📁 ~/Projects/cc-statusline  🌿 feature/context-usage-output-styles  🤖 Sonnet 4  📟 v1.0.85  🎨 default
🧠 Context Remaining: 83% [========--]  ⌛ 3h 7m until reset at 01:00 (37%) [===-------]
💰 $49.00 ($16.55/h)  📊 14638846 tok (279900 tpm)

Compact Mode:

📁 ~/my-app  🌿 main  🤖 Claude Sonnet  📟 v1.0.85
🧠 Context Remaining: 95% [=========-]
💰 $2.48 ($12.50/h)

Test your statusline before restarting Claude Code:

cc-statusline preview .claude/statusline.sh

What preview does:

1. 📄 Loads your actual statusline script
2. 🧪 Runs it with realistic mock data
3. 📊 Shows exactly what the output will look like
4. ⚡ Reports performance metrics and functionality

• 🔒 Safe Updates - Never overwrites existing statuslines without confirmation
• 🛡️ Settings Protection - Preserves your existing settings.json configurations
• ⚠️ Conflict Detection - Warns when other statuslines are configured
• ✅ Smart Defaults - Project-level installation by default for safety

# Generate to custom location
cc-statusline init --output ./my-statusline.sh

# Skip auto-installation (manual setup)
cc-statusline init --no-install

# Global installation for convenience
npm install -g @chongdashu/cc-statusline

1. 🎯 Configuration - Two questions configure your preferences
2. 🏗️ Generation - Creates optimized bash script tailored to your needs
3. ⚙️ Installation - Integrates with Claude Code settings
4. 🔄 Updates - Connects to ccusage for live usage statistics

• ⚡ Bash-First - Native shell execution for maximum speed
• 🎨 Claude Code Optimized - Forces colors for Claude Code terminals (respects NO_COLOR)
• 🌍 Environment Respect - Honors NO_COLOR and other terminal conventions
• 📦 Zero Dependencies - Self-contained script with graceful fallbacks
• 🔒 Secure - No network requests except ccusage integration

After installation, you'll have a clean setup:

.claude/
├── statusline.sh    # 🎯 Your generated statusline script
└── settings.json    # ⚙️ Auto-updated Claude Code configuration

If auto-configuration fails, simply add this to .claude/settings.json:

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

1. Restart Claude Code after installation
2. Verify settings - Check .claude/settings.json contains the configuration above
3. Check permissions - Ensure script is executable: chmod +x .claude/statusline.sh

• Test performance: cc-statusline preview .claude/statusline.sh
• Optimize features: Disable heavy features if execution > 500ms
• Disable ccusage: Remove usage tracking if not needed

• Install jq: See the jq installation guide below
• ccusage setup: Works automatically via npx ccusage@latest
• Git not found: Install git for branch display
• Context not showing: Ensure you're in an active Claude Code session with context usage
• Colors not working: Check that NO_COLOR environment variable is not set

Benchmarked on macOS with all features enabled

Contributions are welcome!

Quick Start:

git clone https://github.com/chongdashu/cc-statusline
cd cc-statusline
npm install && npm run build

Contribution Areas:

• 🐛 Bug Fixes - Help make it more robust
• ✨ New Features - Add support for more runtimes/features
• 📚 Documentation - Improve guides and examples
• 🧪 Testing - Add test coverage and edge cases

See our Contributing Guide for detailed information.

The ccusage integration includes a robust file-based locking mechanism to prevent concurrent process spawning. Test this functionality:

Single Test:

echo '{}' | ./test/test-statusline-with-lock.sh

Concurrent Test:

./test/test-concurrent-locking.sh

Manual Concurrent Test:

# Spawn 10 concurrent processes
for i in {1..10}; do 
  echo '{}' | ./test/test-statusline-with-lock.sh & 
done

Expected Behavior:

• ✅ Only 1 process runs ccusage at a time
• ✅ Other processes skip gracefully (no pile-up)
• ✅ Lock files are properly cleaned up
• ✅ No hanging processes remain

Verification Commands:

# Check for stale locks
ls /tmp/ccusage_statusline.* 2>/dev/null || echo "✅ No locks remain"

# Monitor running processes
ps aux | grep ccusage | grep -v grep

• ccusage - Claude Code usage analytics (would not be possible with it!)
• Claude Code - Official documentation

We're grateful for all contributions that make cc-statusline better!

• Jonathan Borgwing (@DevVig) - Critical performance fix for infinite ccusage process spawning (#4)

Want to see your name here? Check out our Contributing Guide and help make cc-statusline even better!

We welcome:

• 🐛 Bug fixes and performance improvements
• ✨ New features and enhancements
• 📚 Documentation improvements
• 🧪 Test coverage and quality assurance

See CHANGELOG.md for detailed release history.

MIT License - see LICENSE file for details.