cc-statusline

A beautiful, informative statusline for Claude Code

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

⚡ Quick Start

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.

📋 Prerequisites

Required

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

Strongly Recommended

• 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)

macOS

brew install jq

Linux

# Ubuntu/Debian
sudo apt-get install jq

# CentOS/RHEL/Fedora
sudo yum install jq

# Arch Linux
sudo pacman -S jq

Windows 10/11

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

Verify Installation

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

Optional

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

🎯 Simple Setup

✨ What You Get

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 500ms
• Disable ccusage: Remove usage tracking if not needed

🧩 Missing Features

• 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

🚀 Performance

Metric	Target	Typical
Execution Time	/dev/null

Monitor running processes

ps aux | grep ccusage | grep -v grep

## 📊 Stats



![GitHub stars](https://img.shields.io/github/stars/chongdashu/cc-statusline?style=social)
![GitHub forks](https://img.shields.io/github/forks/chongdashu/cc-statusline?style=social)
![npm downloads](https://img.shields.io/npm/dm/@chongdashu/cc-statusline)





## 🔗 Related Projects

- **[ccusage](https://github.com/ryoppippi/ccusage)** - Claude Code usage analytics (would not be possible with it!)
- **[Claude Code](https://docs.anthropic.com/en/docs/claude-code)** - Official documentation

## 👥 Contributors

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

- **[Jonathan Borgwing (@DevVig)](https://github.com/DevVig)** - Critical performance fix for infinite ccusage process spawning ([#4](https://github.com/chongdashu/cc-statusline/pull/4))

### How to Contribute

Want to see your name here? Check out our [Contributing Guide](CONTRIBUTING.md) 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

## 📝 Changelog

See [CHANGELOG.md](CHANGELOG.md) for detailed release history.

## 📄 License

MIT License - see [LICENSE](LICENSE) file for details.

---



**Made by [Chong-U](https://github.com/chongdashu) @ [AIOriented](https://aioriented.dev)**