Claude Code Enhanced Statusline

October 1, 2025 · View on GitHub

Enhanced statusline for Claude Code that provides accurate token usage, costs, burn rate metrics, and optional codeindex integration. Compatible with all Claude Code versions including v1.0.92+.

✨ Features

📊 Accurate token usage percentage - Real-time usage against block limits
💰 Complete cost tracking - Session, daily, and block costs
🔥 Token burn rate - Displayed in tokens/min with smart K/M/B formatting
⏱️ Time remaining - Precise time left in current billing block
🎯 Session detection - Automatic detection of current project session
🔍 Codeindex integration (optional) - Show active codebase indexing status
⚠️ Context limit warnings - Visual indicator when exceeding 200k tokens
🤖 Multiple model display - Shows comma-separated model names when using multiple models

🔄 Version Compatibility

This project provides two statusline scripts for different Claude Code versions:

Claude Code Version	Script	Features
v1.0.92+ (Latest)	`claude-statusline-v1092.py`	✅ Full v1.0.92+ JSON support ✅ Context limit warnings ✅ Enhanced error handling ✅ Multiple model display ✅ All cost tracking features
v1.0.88 and earlier	`claude-statusline.py`	✅ Legacy JSON support ✅ Basic cost tracking ✅ Codeindex integration ❌ No context warnings

The installer automatically selects the correct script for your Claude Code version. For v1.0.92+, it uses the enhanced v1092 script.

📋 Prerequisites

Install ccusage

Using Homebrew:

brew install ccusage

Or using npm:

npm install -g ccusage

Requirements

Python 3
Claude Code
curl (for optional codeindex integration)

Optional Dependencies

claude-codeindex - For codebase indexing status display
- If installed and running, shows active indexing status
- Gracefully falls back if unavailable
- No configuration needed - auto-detected

🚀 Quick Install

Option 1: Standard Installation (Recommended)

# Clone the repository
git clone https://github.com/WKassebaum/claude-statusline.git
cd claude-statusline

# Run the installer
./install.sh

Option 2: Binary Installation

Installs to ~/.local/bin for system-wide access:

# Clone the repository
git clone https://github.com/WKassebaum/claude-statusline.git
cd claude-statusline

# Run the binary installer
./install-bin.sh

The statusline will automatically update in Claude Code.

📊 Statusline Format

Standard format:

🤖 Opus 4.1 | 💰 \$3.25 session / \$81.14 today / \$77.30 block (1h 14m left) | 🔥 204K/min | 39.5M tokens | 40.4% used | ~1h14m left

With multiple models (v1.0.92+):

🤖 Opus 4.1, Sonnet 4 | 💰 \$99.52 session / \$52.95 today / \$78.06 block (1h 40m left) | 🔥 482K/min | 96.5M tokens | 98.8% used | ~1h40m left

With context limit warning (v1.0.92+):

🤖 Opus 4.1 ⚠️ Context limit | 💰 \$3.25 session / \$81.14 today / \$77.30 block (1h 14m left) | 🔥 204K/min | 39.5M tokens | 40.4% used | ~1h14m left

With codeindex integration (when available):

🤖 Opus 4.1 | 🔍 ✅ claude-codeindex | 💰 \$3.25 session / \$81.14 today / \$77.30 block (1h 14m left) | 🔥 204K/min | 39.5M tokens | 40.4% used | ~1h14m left

During active indexing:

🤖 Opus 4.1 | 🔍 🔄 (42%) my-project | 💰 \$3.25 session / \$81.14 today ...

What Each Field Shows

Model: Currently active Claude model (Opus 4.1)
Codeindex (optional): Current project indexing status
- 🔍 ✅ project-name - Project is fully indexed
- 🔍 ❌ project-name - Project not indexed
- 🔍 🔄 (42%) project-name - Currently indexing (42% complete)
- 🔍 ❌ service down - Service unavailable
- (not shown) - codeindex not installed (graceful fallback)
Session cost: Total cost for current working directory session
Today's cost: Total usage for today across all sessions
Block cost: Current 5-hour block usage and time remaining
Burn rate: Token consumption rate in tokens per minute
Token count: Current block tokens (matches ccusage display)
Usage %: Percentage of 97.6M token block limit used
Time left: Estimated time remaining based on burn rate

Components:

Model: Current Claude model
Costs: Session, daily, and current block costs
Burn rate: Token consumption rate per minute
Tokens: Total session tokens
Usage: Percentage of block limit consumed
Time: Estimated time remaining

🛠️ Manual Installation

For Claude Code v1.0.92+ (Recommended)

Copy the v1092 statusline script:

cp claude-statusline-v1092.py ~/.claude/claude-statusline.py
chmod +x ~/.claude/claude-statusline.py

Update ~/.claude/settings.json:

{
  "statusLine": {
    "type": "command",
    "command": "python3 /Users/YOUR_USERNAME/.claude/claude-statusline.py"
  }
}

For Claude Code v1.0.88 and Earlier

Copy the legacy statusline script:

cp claude-statusline.py ~/.claude/claude-statusline.py
chmod +x ~/.claude/claude-statusline.py

Update ~/.claude/settings.json (same as above)

Note: The automatic installer detects your Claude Code version and selects the appropriate script. Manual installation is only needed for custom setups.

🧪 Testing

Test the statusline output:

echo '{}' | python3 ~/.claude/claude-statusline.py

Testing Codeindex Integration

If you have claude-codeindex installed, you can test the integration:

# Check if codeindex service is running
curl -s http://localhost:3847/health

# Start codeindex in a project directory
/codeindex:start

# You should see the codeindex status in your statusline:
# 🤖 Opus 4.1 | 🔍 ●your-project-name | 💰 ...

🔍 Codeindex Integration

The statusline automatically detects and displays codeindex status when available.

Status Indicators

Indicator	Meaning	Description
`🔍 ✅ project-name`	Indexed	Project is fully indexed and ready
`🔍 ❌ project-name`	Not Indexed	Project not in the index
`🔍 🔄 (23%) project-name`	Indexing	Currently indexing, 23% complete
`🔍 🔄 (89%) project-name`	Almost Done	Indexing nearly complete
`🔍 ❌ service down`	Service Error	codeindex-service not running
(not shown)	Not Installed	codeindex not available (graceful fallback)