cc-statusline

⚡ Quick Start

One command. Three questions. Custom statusline.

``bash
npx @chongdashu/cc-statusline@latest init
`

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

📋 Prerequisites

$3

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

$3

- 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
`bash
brew install jq
`

#### Linux
`bash


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)
`bash


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

$3


`bash
jq --version

Should output: jq-1.6 or higher

`

$3

- 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 <100ms execution time

🎛️ Features Overview

$3


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

$3

| Feature | Description | Example |
|---------|-------------|---------|
| 📁 Directory | Current working directory | ~/my-project |
| 🌿 Git Branch | Active git branch | feature/statusline |
| 🤖 Model | Claude model name & version | Sonnet 4 |
| 📟 Claude Code | Claude Code version | v1.0.85 |
| 🎨 Output Style | Current output style setting | default |
| 🧠 Context | Remaining context with progress bar | 83% [========--] |
| 💰 Cost | Live costs with highlighted burn rate | $49.00 ($16.55/h) |
| ⌛ Session | Time until reset with progress | 3h 7m until reset at 01:00 (37%) [===-------] |

$3

| Feature | Description | Example |
|---------|-------------|---------|
| 📊 Tokens | Token consumption with burn rate | 14638846 tok (279900 tpm) |

$3

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

🛠️ Advanced Usage

$3

Test your statusline before restarting Claude Code:

`bash
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

$3

- 🔒 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

$3

`bash

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
`

🔧 How It Works

$3

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

$3

- ⚡ 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

📂 File Structure

After installation, you'll have a clean setup:

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

$3

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

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

🔧 Troubleshooting

$3


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

$3

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

$3

- 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 | <100ms | 45-80ms |
| Memory Usage | <5MB | ~2MB |
| CPU Impact | Negligible | <1% |
| Dependencies | Minimal | jq only |

Benchmarked on macOS with all features enabled

🤝 Contributing

Contributions are welcome!

Quick Start:
`bash
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.

🧪 Testing

$3

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

Single Test:
`bash
echo '{}' | ./test/test-statusline-with-lock.sh
`

Concurrent Test:
`bash
./test/test-concurrent-locking.sh
`

Manual Concurrent Test:
`bash


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:
`bash


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
``

📊 Stats

🔗 Related Projects

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

👥 Contributors

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

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

$3

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

📝 Changelog

See CHANGELOG.md for detailed release history.

📄 License

MIT License - see LICENSE file for details.

---