claude-statusline 2.0.1

Real-time session tracking and analytics for Claude Code

Claude Statusline

Real-time session tracking and analytics for Claude Code with 100+ powerline themes and comprehensive analytics.

Features

Core Features

• 📊 Real-time Monitoring - Track active sessions with live updates
• 💰 Cost Tracking - Accurate cost calculation based on official pricing
• 🤖 Multi-Model Support - Track Opus 4.6, Sonnet 4.5, Haiku and all Claude models
• 📁 Git Integration - Shows branch info and repository status
• 💻 System Info - CPU, memory, and folder information
• ⚡ Lightweight - Minimal dependencies (psutil + colorama)
• 📦 Easy Installation - Available as a Python package

Powerline Themes

• 🎨 100 Professional Themes - Carefully designed powerline themes with logical widget grouping
• 🌈 Advanced RGB Colors - True color output with soft, pleasant color schemes
• 🔧 Interactive Theme Browser - Navigate themes with live preview and search
• 🎯 Custom Theme Builder - Create and save your own powerline designs
• ⚡ Real-time Data - Live token counts, cache efficiency, and session metrics
• 📱 Smart Widget Organization - Related widgets grouped together (tokens, time, etc.)
• 📊 Two-Line Display - Progress bar on second line showing session completion (◼◻)
• ⧂ Visual Enhancements - Refined Unicode characters for softer appearance

Analytics & Reporting

• 📈 Advanced Usage Analytics - Comprehensive productivity metrics and insights
• 📊 Trend Analysis - Usage trends, productivity patterns, and optimization recommendations
• 🏥 Health Monitoring - System health diagnostics and performance monitoring
• 💹 Budget Management - Set spending limits and track budget compliance
• 📊 Usage Patterns Analysis - Behavioral insights and optimization recommendations
• 📉 Cost Forecasting - Predict future costs based on usage trends
• 📋 Export Reports - Generate detailed reports for external analysis
• 🚨 Smart Alerts - Budget warnings and usage anomaly detection
• 🎯 Unified CLI - Single command interface for all features

Quick Start

Install from PyPI

pip install claude-statusline
claude-statusline init

One-Line Setup (from source)

Linux / macOS:

git clone https://github.com/ersinkoc/claude-statusline.git && cd claude-statusline && bash setup.sh

Windows (PowerShell):

git clone https://github.com/ersinkoc/claude-statusline.git; cd claude-statusline; powershell -ExecutionPolicy Bypass -File setup_windows.ps1

The setup scripts handle everything: pip install, PATH configuration, default configs, database rebuild, and daemon start.

Commands Overview

claude-statusline status          # Show current session status
claude-statusline theme           # Browse 100 themes interactively
claude-statusline daemon --start  # Start background daemon
claude-statusline analytics       # View usage analytics

All Commands

# Setup & Core
claude-statusline init            # First-run setup (auto-runs on first use)
claude-statusline status          # Show current session status
claude-statusline daemon --start  # Start background monitoring
claude-statusline theme           # Interactive theme browser
claude-statusline rebuild         # Rebuild database from logs

# Analytics
claude-statusline analytics       # Advanced usage analytics
claude-statusline sessions        # Session analysis
claude-statusline model-sessions  # Model-specific session statistics
claude-statusline costs           # Cost analysis
claude-statusline daily           # Daily reports
claude-statusline heatmap         # Activity heatmaps
claude-statusline summary         # Summary statistics
claude-statusline trends          # Usage trends and patterns
claude-statusline health          # System health monitoring
claude-statusline budget          # Budget management

# Utilities
claude-statusline update-prices   # Update model pricing
claude-statusline verify          # Verify cost calculations
claude-statusline rotate          # Theme rotation settings

Theme System

The powerline theme system provides 100 professionally designed themes with:

• Smart Widget Grouping - Related widgets (tokens, time, etc.) are consecutive
• Pleasant Color Schemes - Soft, eye-friendly RGB colors instead of harsh tones
• Nerd Font Icons - Creative, diverse icons for each widget type
• Live Preview - See real data in themes before applying
• Custom Themes - Build and save your own designs
• Interactive Browser - Navigate with simple commands (n/p for next/previous)

Theme Browser Commands

n/j = Next theme        p/k = Previous theme     ENTER = Apply theme
r   = Random theme      g   = Go to number       q     = Quit
+10 = Jump forward     -10 = Jump back           /     = Search
b   = Theme builder

Analytics Features

Model Session Analytics

• Session-by-Session Breakdown - Detailed statistics for each model per session
• Token-Level Analysis - Input, output, cache creation, and cache read tokens
• Accurate Cost Calculation - Precise cost tracking based on official model pricing
• Model Filtering - Focus on specific Claude models (Sonnet, Opus, Haiku)
• Performance Metrics - Session duration, message count, and most active hours

Trend Analysis

• Usage patterns over time
• Productivity insights
• Model efficiency analysis
• Peak usage hours identification
• Seasonal trends detection

Health Monitoring

• System performance metrics
• Database health checks
• Daemon status monitoring
• Performance bottleneck detection

Budget Management

• Set monthly/weekly spending limits
• Real-time budget tracking
• Overspend warnings
• Cost projection alerts

Installation

From PyPI (Recommended)

pip install claude-statusline
claude-statusline init    # First-run setup (auto-runs on first use)

From Source (with setup script)

git clone https://github.com/ersinkoc/claude-statusline.git
cd claude-statusline

# Linux / macOS
bash setup.sh

# Windows (PowerShell)
powershell -ExecutionPolicy Bypass -File setup_windows.ps1

Manual Source Install

git clone https://github.com/ersinkoc/claude-statusline.git
cd claude-statusline
pip install -e .
claude-statusline init

Configuration

The tool automatically creates configuration in ~/.claude/data-statusline/:

• smart_sessions_db.json - Session database
• theme_config.json - Current theme settings
• daemon_status.json - Background daemon status
• config.json - General configuration
• prices.json - Model pricing data

Requirements

• Python 3.8+
• Claude Code (for session data)
• psutil (automatically installed)

Architecture

Claude Code → JSONL Logs → Database Builder → Analytics Tools
                    ↓
               Session Database ← Background Daemon
                    ↓
            Statusline Display ← Theme System

Data Privacy

• All data stays local on your machine
• No network requests except for price updates
• Session data derived only from Claude Code logs
• No telemetry or tracking

Contributing

1. Fork the repository
2. Create a feature branch
3. Make changes
4. Add tests if applicable
5. Submit a pull request

License

MIT License - see LICENSE file for details.

Changelog

v2.0.0 (Latest) - Major Quality & Reliability Release

• NEW: Claude Opus 4.6 model support (claude-opus-4-6-20260205, $5/M input, $25/M output)
• NEW: Centralized price loading with module-level caching for better performance
• NEW: Centralized timezone utility with DST-safe implementation
• SECURITY: Fixed all 36 bare except: clauses with proper exception types across 14 files
• FIXED: CLI sessions command crash from incorrect method name references
• FIXED: Fallback pricing updated from legacy $15/$75 to current $5/$25
• FIXED: Windows PID detection using psutil with exact-match tasklist fallback
• FIXED: Timezone DST bug in activity heatmap (was using buggy time.altzone approach)
• IMPROVED: Daemon sleep loop optimized (60x1s → 12x5s chunks) for faster shutdown
• IMPROVED: Database rebuild returns proper boolean status
• IMPROVED: Windows path traversal validation for system directories
• IMPROVED: Python 3.13 and 3.14 classifiers added

v1.9.9 - Claude Opus 4.5 & Security Fixes

• NEW: Added support for claude-opus-4-5-20251101 model ($5/M input, $25/M output)
• SECURITY: Fixed command injection vulnerability in Windows cleanup code
• FIXED: Missing return statement in safe_json_read() preventing silent failures
• FIXED: Timezone inconsistency in daemon timestamps (now uses UTC)
• FIXED: Obsolete entry points in setup.py synchronized with pyproject.toml
• IMPROVED: Better error handling with specific exception types

v1.9.8 - Rebuild Function Bug Fix (HOTFIX)

• FIXED: Database rebuild command now correctly returns success/failure status
• FIXED: CLI shows "[OK] Database rebuild completed" on successful rebuild
• FIXED: Missing return value in rebuild_database() method resolved

v1.9.7 - Architecture Improvement - Centralized Model Management

• NEW: Centralized model_utils.py with unified model display functions
• NEW: Dynamic model names loaded from prices.json with tier-based emojis (🧠🎭⚡🔮)
• IMPROVED: Consistent model display across all analytics and statusline modules
• IMPROVED: Smart model classification (flagship, balanced, fast, special)
• TECHNICAL: Eliminated duplicate code across 8+ files using DRY principles
• TECHNICAL: Enhanced extensibility for adding new models without multiple updates

v1.9.6 - CLI Version Display Fix (HOTFIX)

• FIXED: CLI --version command now shows correct version instead of hard-coded v1.9.0
• FIXED: Version output now dynamically reads from version variable
• IMPROVED: Automatic synchronization between CLI version and package version

v1.9.5 - Version Synchronization Fix

• FIXED: Version display inconsistency between CLI output and package version
• FIXED: Synchronized version numbers across all package files
• IMPROVED: Package consistency for clean PyPI publishing
• TECHNICAL: Version coordination and metadata accuracy

v1.9.4 - Model Session Analytics (Fixed)

• NEW: model-sessions command for detailed session-by-session statistics
• NEW: Model-specific cost calculation with accurate pricing data
• NEW: Token-level breakdown (input, output, cache creation, cache read)
• NEW: Performance metrics per session (duration, messages, active hours)
• NEW: Model filtering - focus only on Claude models (excludes GLM)
• IMPROVED: Accurate cost calculation using official model pricing
• FIXED: Removed non-Claude models from analytics for cleaner data
• FIXED: Correct cost calculation using official model pricing database
• FIXED: Proper model filtering showing only Claude models (Sonnet, Opus, Haiku)

v1.9.3 - Model Session Analytics

• NEW: Initial model session statistics implementation
• NEW: Session-by-session breakdown for each model

v1.9.2 - Model Filtering Enhancement

• IMPROVED: Exclusive Claude model support in data processing
• IMPROVED: Comprehensive filtering at all levels of data processing
• IMPROVED: Clean data integrity with only Claude model usage

v1.9.1 - Visual Enhancements

• NEW: Two-line powerline display with progress bar
• NEW: Session progress tracking with visual indicators
• IMPROVED: Enhanced visual presentation

v1.9.0 - Powerline Theme System

• NEW: 100 professional powerline themes with smart widget grouping
• NEW: Interactive theme browser with live preview and search
• NEW: Custom theme builder for creating personalized designs
• NEW: Advanced RGB color system with soft, pleasant color schemes
• NEW: Comprehensive trend analysis and productivity insights
• NEW: System health monitoring and diagnostics
• IMPROVED: Unified powerline system replaces all previous theme systems
• IMPROVED: Token widgets now grouped together logically
• IMPROVED: Cleaned up codebase by removing 16 obsolete files
• FIXED: Better Unicode and nerd font support across platforms
• FIXED: Improved theme organization and consistency

v1.8.0

• Advanced analytics and budget management
• Multi-model cost tracking improvements
• Enhanced session detection
• Performance optimizations

Support

For issues, feature requests, or questions:

• Create an issue on GitHub
• Check the documentation in the /docs folder
• Review the CLI help with claude-statusline --help