@sponzig/cc-statusline

cc-statusline

🚀 Transform your Claude Code experience with a beautiful, informative statusline

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

⚡ Quick Start

One command. Two questions. Beautiful statusline. ✨

npx @sponzig/cc-statusline init

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

🎯 Setup with just 1 command

✨ What You Get

Transform your bland Claude Code terminal into an information-rich powerhouse:

• 📁 Smart Directory Display - Current folder with ~ abbreviation
• 🌿 Git Integration - Current branch name with clean styling
• 🤖 Model Intelligence - Shows which Claude model you're using
• 💵 Real-Time Cost Tracking - Live cost monitoring via ccusage integration
• ⌛ Session Management - Time remaining until usage limit resets with progress bars
• 🔄 Cache Efficiency - Track prompt caching performance and cost savings
• 📏 Context Usage - Monitor context window utilization with smart alerts
• 📊 Advanced Analytics - Token consumption, burn rate, and cost projections
• 💻 System Monitoring - CPU, RAM, and load averages with smart thresholds
• 🎨 Beautiful Colors - TTY-aware colors that respect your terminal theme
• ⚡ Lightning Fast - Multi-level caching with <100ms execution time
• 🔧 Auto-Optimization - Smart compact mode and configurable thresholds

🎛️ Features Overview

🔥 Default Features (Pre-selected)

Feature	Description	Example
📁 Directory	Current working directory	~/my-project
🌿 Git Branch	Active git branch	main
🤖 Model	Claude model name & version	Opus 4.1
💵 Usage & Cost	Real-time costs with hourly rate	$2.48 ($12.50/h)
⌛ Session Time	Time until reset with progress	2h 15m until reset (68%)
🔄 Cache Efficiency	Prompt caching performance	85% (saved 12k tok)
📏 Context Usage	Context window utilization	45% (90k/200k)

🚀 Optional Power Features

Feature	Description	Example
📊 Token Stats	Total tokens consumed	45,230 tok
🔥 Burn Rate	Tokens per minute	847 tpm
📈 Cost Projections	Estimated session cost	→$12.50 (2h left)
⚠️ Efficiency Alerts	Performance warnings	⚠$15.2/h ⚠85%ctx
💻 CPU Usage	System CPU monitoring	15%✓
🧠 RAM Usage	Memory utilization	8.2G/16G
⚡ System Load	Load averages with trends	1.2↘✓

🎨 Example Outputs

Minimal Setup:

📁 ~/my-app  🌿 main  🤖 Claude Sonnet

Full Power Mode:

📁 ~/projects/ai-tools  🌿 feature/statusline  🤖 Opus 4.1  ⌛ 2h 15m until reset (68%)  💵 $16.40→$24.50  🔄 87%  📏 65%  💻 15%✓  🧠 8.2G/16G  ⚡ 1.2↘✓

Smart Compact Mode (auto-activates with 6+ features):

📁 ~/ai-tools   🌿 test/vite  🤖 Sonnet 4  💻 6%⚠  🧠 1G/31G (3%)  ⚡ 1.1✓ (8c: 1.08/1.10/1.73)  ⌛ 1h20m  💰 $66→$91  ⚡94%  📏76%  🔥259840

🛠️ Advanced Usage

Preview Your Statusline

Test your statusline before restarting Claude Code:

cc-statusline preview .claude/statusline.sh

What preview does:

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

Custom Installation

# 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 @sponzig/cc-statusline

🔧 How It Works

The Magic Behind The Scenes

• 🎯 Smart Configuration - Two intuitive questions configure everything
• 🏗️ Intelligent Generation - Creates optimized bash script tailored to your needs
• ⚙️ Auto-Installation - Seamlessly integrates with Claude Code settings
• 🔄 Real-Time Updates - Connects to ccusage for live usage statistics

Technical Architecture

• ⚡ Bash-First - Native shell execution for maximum speed
• 🎨 TTY-Aware - Automatically detects terminal capabilities
• 🌍 Environment Respect - Honors NO_COLOR and other conventions
• 📦 Zero Dependencies - Self-contained script with graceful fallbacks
• 🔒 Secure - No network requests except ccusage integration

📋 Requirements

✅ Required (You Already Have These!)

• Claude Code - The tool you're already using
• jq - JSON processing (pre-installed on most systems)

🎁 Optional Enhancements

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

Quick Compatibility Check

command -v jq && echo "✅ Ready to go!"

📂 File Structure

After installation, you'll have a clean setup:

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

Manual Configuration (Backup Plan)

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

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

🔧 Troubleshooting

🚫 Statusline Not Showing

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

🐌 Performance Issues

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

🧩 Missing Features

• Install jq: brew install jq (macOS) or apt install jq (Ubuntu)
• ccusage setup: Works automatically via npx ccusage@latest
• Git not found: Install git for branch display

🚀 Performance

Metric	Target	Typical
Execution Time	<100ms	45-80ms
Memory Usage	<5MB	~2MB
CPU Impact	Negligible	<1%
Dependencies	Minimal	jq only

Benchmarked on macOS with all features enabled

🤝 Contributing

We love contributions! 🎉

Quick Start:

git clone https://github.com/Sponzig/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.

📊 Stats

🔗 Related Projects

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

📝 Changelog

See CHANGELOG.md for detailed release history.

📄 License

MIT License - see LICENSE file for details.

Made by Sponzig