███████╗███╗   ██╗██╗  ██╗ █████╗ ███╗   ██╗ ██████╗███████╗██████╗ 
██╔════╝████╗  ██║██║  ██║██╔══██╗████╗  ██║██╔════╝██╔════╝██╔══██╗
█████╗  ██╔██╗ ██║███████║███████║██╔██╗ ██║██║     █████╗  ██║  ██║
██╔══╝  ██║╚██╗██║██╔══██║██╔══██║██║╚██╗██║██║     ██╔══╝  ██║  ██║
███████╗██║ ╚████║██║  ██║██║  ██║██║ ╚████║╚██████╗███████╗██████╔╝
╚══════╝╚═╝  ╚═══╝╚═╝  ╚═╝╚═╝  ╚═╝╚═╝  ╚═══╝ ╚═════╝╚══════╝╚═════╝ 

███████╗████████╗ █████╗ ████████╗██╗   ██╗███████╗██╗     ██╗███╗   ██╗███████╗
██╔════╝╚══██╔══╝██╔══██╗╚══██╔══╝██║   ██║██╔════╝██║     ██║████╗  ██║██╔════╝
███████╗   ██║   ███████║   ██║   ██║   ██║███████╗██║     ██║██╔██╗ ██║█████╗  
╚════██║   ██║   ██╔══██║   ██║   ██║   ██║╚════██║██║     ██║██║╚██╗██║██╔══╝  
███████║   ██║   ██║  ██║   ██║   ╚██████╔╝███████║███████╗██║██║ ╚████║███████╗
╚══════╝   ╚═╝   ╚═╝  ╚═╝   ╚═╝    ╚═════╝ ╚══════╝╚══════╝╚═╝╚═╝  ╚═══╝╚══════╝

🚀 Installation (2 minutes)

📋 Platform Requirements: 100% compatible across all major platforms

• macOS (12+): brew install jq curl
• Ubuntu/Debian: sudo apt install jq curl
• Arch Linux: sudo pacman -S jq curl
• Fedora/RHEL: sudo dnf install jq curl
• Alpine Linux: apk add jq curl
• Windows: WSL recommended with Ubuntu distribution

Choose your preferred installation method:

Option 1: Quick Install (Recommended)

# Download and inspect the installer (strongly recommended)
curl -fsSL https://raw.githubusercontent.com/rz1989s/claude-code-statusline/main/install.sh -o install.sh

# Review what it does - look for:
# ✓ Only creates files in ~/.claude/statusline/
# ✓ Downloads from this GitHub repo
# ✓ No sudo or system modifications
less install.sh  

# Run when you're satisfied it's safe
bash install.sh

🔍 Quick Security Check: Open install.sh and verify it only:

• Creates directories in ~/.claude/
• Downloads files from raw.githubusercontent.com/rz1989s/claude-code-statusline
• Doesn't use sudo or modify system files
• Uses curl with proper GitHub raw URLs
• No network calls to external domains

Option 1b: One-Line Install (Trust the Repo)

# Direct install without inspection (for trusted users)
curl -sSfL https://raw.githubusercontent.com/rz1989s/claude-code-statusline/main/install.sh | bash

🔍 Enhanced Installer Options

# Check all dependencies (shows 6 feature categories)
curl -sSfL https://raw.githubusercontent.com/rz1989s/claude-code-statusline/main/install.sh | bash -s -- --check-all-deps

# Interactive installation with user choices
curl -sSfL https://raw.githubusercontent.com/rz1989s/claude-code-statusline/main/install.sh | bash -s -- --interactive

# Comprehensive dependency analysis + interactive mode
curl -sSfL https://raw.githubusercontent.com/rz1989s/claude-code-statusline/main/install.sh | bash -s -- --check-all-deps --interactive

# Install from development branch
curl -sSfL https://raw.githubusercontent.com/rz1989s/claude-code-statusline/nightly/install.sh | bash -s -- --branch=nightly

# Debug installation issues
STATUSLINE_INSTALL_DEBUG=true curl -sSfL https://raw.githubusercontent.com/rz1989s/claude-code-statusline/main/install.sh | bash

Option 2: Manual Install (No script required)

# 1. Create directory structure
mkdir -p ~/.claude/statusline/{lib,examples}

# 2. Download core files
curl -fsSL https://raw.githubusercontent.com/rz1989s/claude-code-statusline/main/statusline.sh -o ~/.claude/statusline/statusline.sh
curl -fsSL https://raw.githubusercontent.com/rz1989s/claude-code-statusline/main/examples/Config.toml -o ~/.claude/statusline/Config.toml

# 3. Download library modules (automated)
curl -sSfL https://raw.githubusercontent.com/rz1989s/claude-code-statusline/main/install.sh | bash -s -- --modules-only

# 4. Make executable and test
chmod +x ~/.claude/statusline/statusline.sh
~/.claude/statusline/statusline.sh --version

✅ Verify Installation Success

# Confirm installation success
~/.claude/statusline/statusline.sh --version
ls -la ~/.claude/statusline/lib/  # Should show 10+ module files

# Test with sample input
echo '{"workspace": {"current_dir": "'"$(pwd)"'"}, "model": {"display_name": "Test"}}' | ~/.claude/statusline/statusline.sh

What Does This Install?

🔍 Transparency First - Here's exactly what happens:

✅ Creates one directory: ~/.claude/statusline/ (in your home folder only)
✅ Downloads 31 text files: Shell scripts from this GitHub repository
✅ Creates one config file: Config.toml with default settings you can edit
✅ No system changes: Everything stays in your home folder

❌ Does NOT:

• Modify any system files or PATH
• Install packages globally or change your OS
• Require admin/sudo permissions
• Send data anywhere or phone home
• Modify your shell config (.bashrc, .zshrc, etc.)

🔐 Security: All files are downloaded from this public GitHub repository - you can inspect every line of code before running.

📚 Table of Contents

• Installation
• Recent Updates
• Features
• Theme Gallery
• Screenshot Showcase
• Advanced Setup
• Configuration
• What Each Line Shows
• System Requirements
• Documentation
• Contributing
  • Development Setup
  • Testing
• License
• Acknowledgments

🆕 Recent Updates

v2.10.0 - Advanced Block Metrics Integration 🔥📊 LATEST

🚀 REVOLUTIONARY BLOCK METRICS SYSTEM

• 4 NEW Block Metrics Components - 100% native cost calculation with 75% resource reduction
• Unified Data Collection - Single API call feeds all metrics (burn rate, tokens, cache efficiency, projections)
• Burn Rate Monitoring - Critical token consumption tracking (🔥3.5k/min $2.10/hr)
• Cache Efficiency - Performance optimization insights (Cache: 94% hit)
• Cost Projections - Budget planning and limit avoidance (Est: $16.48)
• Resource Optimized - Minimal background processes, smart 30s caching

v2.9.0 - Revolutionary 3-Tier Download System 🚀⚡

🚀 REVOLUTIONARY INSTALLER OVERHAUL

• 3-Tier Download Architecture - Complete installer architectural overhaul eliminates GitHub rate limits forever
• Tier 1: Direct Raw URLs - Unlimited requests, no API usage, fastest installation method (handles 99% of cases)
• Tier 2: GitHub API Fallback - Optional token support increases limits from 60/hour to 5,000/hour
• Tier 3: Comprehensive Retry - Exponential backoff and intelligent verification with detailed troubleshooting
• 100% Download Guarantee - Either all modules download successfully or clear failure with actionable guidance
• Zero Intervention Required - Primary method handles installations automatically without user interaction

⚡ INSTALLATION IMPROVEMENTS

• Eliminates GitHub Rate Limits - Direct raw URLs bypass API limitations completely
• Enhanced Error Handling - Exponential backoff and comprehensive retry mechanisms
• Performance Benefits - Fastest installation method using direct raw URLs
• Backward Compatible - All existing installation methods preserved and enhanced

🐛 ADDITIONAL FIXES

• Fixed Prayer Time Calculation - Resolved "24h 0m" display bug, now shows "(0m)" for exact matches
• Enhanced Test Coverage - Added comprehensive test cases for prayer time edge scenarios

📈 IMPACT: Bulletproof installation system - Reliable, fast installation regardless of GitHub API availability, with 100% download guarantee and zero user intervention required.

v2.8.0 - Single Source Configuration Revolution 🧹🎯

🎯 REVOLUTIONARY SIMPLIFICATION: SINGLE SOURCE OF TRUTH ARCHITECTURE

Transform your configuration experience with the most significant architectural simplification ever:

• 🧹 Configuration Breakthrough - Eliminated triple redundancy system:

  • ❌ Before: 13 example configs + hardcoded defaults + jq fallbacks = chaos
  • ✅ After: ONE comprehensive Config.toml with all 227 settings = clarity

• 🎯 Zero Hunting - All parameters pre-filled in Config.toml, just edit values

• 🔧 Zero Code Defaults - No more DEFAULT_CONFIG_* constants scattered in lib/config.sh

• ⚡ Pure Extraction - No jq fallbacks (// "default"), reads directly from TOML

• 📁 Simplified Structure - Only examples/Config.toml + README.md (no confusion)

🎯 USER EXPERIENCE TRANSFORMATION

# BEFORE: Hunt for parameter names across 13 config files
# ~/.claude/statusline/examples/Config.modular-compact.toml
# ~/.claude/statusline/examples/Config.modular-atomic.toml
# ... 11 more files to choose from

# AFTER: Edit ONE comprehensive file with ALL settings
# ~/.claude/statusline/Config.toml (227 settings included!)
theme.name = "catppuccin"              # Theme selection
display.lines = 5                      # Line count (1-9)
display.line1.components = ["repo_info", "commits", "version_info"]
labels.commits = "Commits:"            # Display labels
# ... ALL 227 settings right here!

v2.7.0 - Atomic Component System ⚛️🎯

🎯 ULTIMATE CUSTOMIZATION: ATOMIC COMPONENT BREAKTHROUGH

Transform your statusline with 28 atomic components that eliminate separator issues and provide maximum control:

• 🔬 Atomic Components - Single-purpose units for maximum control:

  • commits - Shows ONLY commit count (pure atomic)
  • submodules - Shows ONLY submodule status (pure atomic)
  • cost_monthly - Shows ONLY 30-day costs (pure atomic)
  • cost_weekly - Shows ONLY 7-day costs (pure atomic)
  • cost_daily - Shows ONLY daily costs (pure atomic)

• 🎨 Clean Visual Separation - No more 30DAY $660.87 7DAY $9.31 DAY $36.10! Now: 30DAY $660.87 │ 7DAY $9.31 │ DAY $36.10

• 🧩 Maximum Control - Want only commits without submodules? Use commits component only

• ⚙️ Pure Atomic Architecture - No legacy bundled components, each component shows unique data only

• 📋 8 Example Configs - Including new Config.modular-atomic.toml showcase

⚛️ ATOMIC CONFIGURATION EXAMPLES

# Show only specific git info
display.line1.components = ["repo_info", "commits", "version_info"]

# Custom cost tracking - pick exactly what you need
display.line2.components = ["cost_monthly", "cost_daily"]

# Pure atomic components
display.line3.components = ["commits", "cost_weekly", "mcp_status"]

v2.6.0 - Modular Component System & Configurable 1-9 Line Statusline 🧩🎯

🎯 MAJOR ARCHITECTURAL BREAKTHROUGH: MODULAR COMPONENT SYSTEM

• Complete Component Architecture - 18 individual component modules with standardized interfaces (collect_data(), render(), get_config())
• Configurable 1-9 Line Display - Flexible line layouts from minimal 1-line to comprehensive 9-line configurations
• Component Registry System - Advanced component management with dependency tracking and enablement states
• Mix & Match Flexibility - Arrange any component on any line position (MCP on line 1, prayer times on line 2, etc.)
• Backward Compatibility - Legacy 5-line system preserved as fallback with seamless migration path

🧩 INDIVIDUAL COMPONENT MODULES

• repo_info.sh - Repository directory and git status display
• commits.sh - Commit count (pure atomic)
• submodules.sh - Submodule tracking (pure atomic)
• version_info.sh - Claude Code version with intelligent caching
• time_display.sh - Current time formatting and display
• model_info.sh - Claude model identification with emoji indicators
• cost_repo.sh - Repository session cost tracking
• cost_monthly.sh - 30-day costs (pure atomic)
• cost_weekly.sh - 7-day costs (pure atomic)
• cost_daily.sh - Daily costs (pure atomic)
• cost_live.sh - Live billing block cost monitoring
• mcp_status.sh - MCP server health and connection status
• reset_timer.sh - Block reset countdown and timer management
• prayer_times.sh - Islamic prayer times integration

⚙️ FLEXIBLE TOML CONFIGURATION SYSTEM

# Compact 3-line layout
display.lines = 3
display.line1.components = ["repo_info", "commits", "submodules"]
display.line2.components = ["model_info", "cost_repo"] 
display.line3.components = ["mcp_status"]

# Custom reordering - prioritize what matters to you!
display.line1.components = ["mcp_status", "prayer_times"]
display.line2.components = ["repo_info", "version_info"]

🏗️ ENHANCED MODULAR ARCHITECTURE

• 91.5% Code Reduction - Main orchestrator reduced from monolithic script to clean 368-line module loader
• Component-Based Data Flow - Standardized interfaces enable consistent behavior and easy testing
• Advanced Configuration Parsing - Modular line configuration with component arrangement flexibility
• Enhanced Maintainability - Individual components can be developed, tested, and maintained independently

📈 IMPACT: Revolutionary transformation from fixed 5-line display to fully configurable 1-9 line modular system, enabling personalized statusline layouts that adapt to any workflow preference.

v2.2.0 - Islamic Prayer Times & Hijri Calendar Integration 🕌📅

🕌 MAJOR NEW FEATURE: ISLAMIC PRAYER TIMES

• Complete Prayer Times Display - All 5 daily Islamic prayers (Fajr, Dhuhr, Asr, Maghrib, Isha) with real-time status indicators
• AlAdhan API Integration - Accurate prayer time calculations using the trusted AlAdhan API with multiple calculation methods (ISNA, MWL, Makkah, etc.)
• Visual Status Indicators - ✓ for completed prayers, time remaining display (e.g., "3h 29m") with green highlighting for upcoming prayers, elegant formatting with 🕌 Islamic indicator
• Intelligent Caching - 1-hour cache duration for optimal performance, location-aware cache keys, automatic refresh

🌙 HIJRI CALENDAR WITH AUTHENTIC ISLAMIC TIMEKEEPING

• Maghrib-Based Day Changes - Proper Islamic calendar where Hijri date changes at Maghrib (sunset), not midnight - authentic to Islamic tradition
• Real-Time Hijri Date Display - Current Islamic date with Arabic month names (e.g., "2 Jumādá al-ūlá 1452")
• Moon Phase Indicator - 🌙 symbol when Islamic day changes at Maghrib time
• Multiple Calculation Standards - Support for Umm Al-Qura and other Hijri calculation methods

🔧 COMPREHENSIVE CONFIGURATION SYSTEM

• Full Prayer Customization - Calculation methods (ISNA/MWL/Makkah), Madhab selection (Shafi/Hanafi), manual/auto location modes
• Location Intelligence - Auto-detection or manual coordinates, timezone override support
• Display Preferences - 12h/24h time formats, completed indicators, next prayer highlighting, countdown timers
• Hijri Calendar Options - Arabic month names, weekday display, Maghrib change indicators, manual adjustments

🏗️ ENHANCED ARCHITECTURE

• New Prayer Module - lib/prayer.sh with 400+ lines of Islamic timekeeping logic following existing modular patterns
• Modular Display System - Configurable 1-9 line statusline with flexible component arrangement and dedicated Islamic prayer times
• Comprehensive Testing - Complete unit test suite in tests/unit/test_prayer_functions.bats with edge case coverage
• Performance Optimized - < 2s execution with intelligent caching, graceful API fallbacks, minimal external dependencies

📈 IMPACT: Muslim developers now have accurate Islamic timekeeping integrated seamlessly into their development workflow with authentic religious observance support.

v2.0.6 - Enhanced Reliability & Timeout Improvements 🚀⚡

🐛 CRITICAL BUG FIXES

• Fixed DAY $0.00 display issue - Resolved timeout-related failure in daily cost calculations
• Enhanced configuration fallback logic - Improved handling of empty string values in TOML config parsing

⚡ PERFORMANCE & RELIABILITY IMPROVEMENTS

• Standardized all timeouts to 10s minimum - Increased reliability for external command execution
  • DEFAULT_VERSION_TIMEOUT: 2s → 10s
  • CACHE_CONFIG_ATOMIC_TIMEOUT: 5s → 10s
• Updated all configuration examples - Ensures consistent timeout values across all TOML templates

📚 DOCUMENTATION ENHANCEMENTS

• Streamlined CLAUDE.md - Enhanced developer experience with clearer quick reference section
• Updated cache timing documentation - Improved accuracy of cache behavior explanations
• Better configuration guidance - Updated examples to reflect new timeout standards

📈 IMPACT: Eliminated DAY cost display bug, improved system reliability, and enhanced timeout handling

v1.8.0 - Enterprise-Grade Security & Performance Enhancement 🛡️✨

• 🔒 XDG-Compliant Cache Security - Migrated from /tmp to secure user-isolated directories following XDG Base Directory specification
• 🔐 SHA-256 Integrity Protection - Advanced checksum validation with automatic corruption detection and recovery
• 🌍 Enhanced Git Branch Validation - Unicode and emoji support using git check-ref-format for authentic validation
• 🧹 Comprehensive Resource Cleanup - Signal traps (EXIT/INT/TERM/HUP) prevent resource leaks under any termination scenario
• ⚙️ Advanced TOML Configuration - Expanded cache configuration with 40+ settings for fine-tuned performance control
• 🔧 Intelligent Error Handling - Context-aware error messages with actionable recovery suggestions and automatic fallback systems
• 📊 Real-Time Performance Analytics - Hit/miss ratios, response times, efficiency classification, and memory usage monitoring
• 🔍 Cache Integrity Auditing - Built-in tools for cache health monitoring, corruption detection, and migration recommendations
• 🧪 77+ Comprehensive Tests - Unit, integration, and performance regression test coverage with multi-instance validation
• 📈 Performance Classification - EXCELLENT/GOOD/MODERATE/POOR ratings with optimization recommendations

v1.7.0 - Ultra-Comprehensive Universal Caching Revolution 🎆

• 🌍 Universal Operation Caching - Optimizes ALL external commands, not just API calls
• 🚀 70-90% Performance Improvement - Dramatic reduction in external command execution
• 🔍 Command Existence Caching - Session-wide caching eliminates repeated PATH lookups
• 🔧 Git Operations Caching - Intelligent duration-based caching for all git commands
• 🌐 Enhanced External Commands - Improved claude --version and claude mcp list caching
• 🖥️ System Information Caching - Permanent caching for OS type, architecture
• ⚡ Sub-50ms Responses - Lightning-fast statusline execution (from 200-500ms)
• 🛡️ Universal Multi-Instance Safety - Zero race conditions across all operations
• 🕰️ Smart Duration Strategy - From session-wide to real-time based on change frequency
• 🧠 Intelligent Startup Detection - Force refresh on first startup across all cached operations

v1.6.0 - Intelligent Multi-Tier Caching System 🧠

v1.5.2 - Enhanced Installation & Bug Fixes 🔧

• 🛠️ Enhanced Installer - Fixed curl failure by ensuring directory creation before download
• 📁 Improved Path Management - Enhanced installation path handling for better compatibility
• 🎯 Streamlined Architecture - Simplified version management for easier maintenance
• 🐛 Bug Fixes - Resolved missing model emojis in statusline display
• 📋 Updated Documentation - Comprehensive documentation enhancements and project organization
• ✅ Contributor Ready - Finalized CONTRIBUTING.md with complete development guidelines

v1.5.0 - Simplified Version Management Architecture 🎯

• 📍 Single Source of Truth - Introduced version.txt as master version file for entire codebase
• 🛠️ Version Management Scripts - Automated tools for version synchronization and consistency checks
• 🔄 Dynamic Version Reading - All components now read version from centralized source
• 📦 Automated Package Sync - Scripts maintain package.json synchronization with version.txt
• ✅ System Verification - Comprehensive testing tools for version consistency
• 📚 Complete Documentation - Full guide for centralized version management workflow

v1.3.1 - Enhanced Error Messages & Documentation 🔧

• 📝 Improved Error Messages - Enhanced module loading error messages with specific troubleshooting guidance
• 📚 Function Documentation - Added comprehensive documentation to core.sh functions
• 🧪 Enhanced Testing - New test coverage for module loading functionality
• 🔍 Better Diagnostics - Clearer error messages help users resolve issues faster

v1.3.0 - Modular Architecture Implementation 🏗️

Contains internal v2.0.6-refactored architecture while maintaining v1.3.x compatibility

• 🏗️ Modular Architecture - Complete refactor from 3930-line monolithic script to clean modular system
• 📦 9 Specialized Modules - Core, security, config, themes, git, MCP, cost, display, and cache modules
• 🎯 91.4% Code Reduction - Main orchestrator reduced to 338 lines with preserved functionality
• 🔧 Enhanced Maintainability - Clear separation of concerns and dependency management
• ⚡ Improved Performance - Optimized module loading and reduced complexity
• 🔄 100% Backward Compatible - All existing functionality and configuration preserved

v1.2 - Enhanced Timeout Validation & Configuration Improvements 🚀

• ✅ Comprehensive Timeout Validation - Enhanced bounds checking with contextual suggestions
• 🔧 Smart Configuration Validation - Prevents dangerous timeout values (0s, >60s)
• 📖 Enhanced CLI Documentation - Detailed timeout configuration guidance
• 🛠️ New Helper Functions - parse_timeout_to_seconds() and validate_timeout_bounds()
• 💡 Contextual Error Messages - Specific suggestions for optimal timeout ranges
• 🔄 Backward Compatible - All existing configurations continue to work

v1.1 - Enhanced Directory Structure & TOML Configuration

• 📋 TOML Configuration Files - Modern, structured configuration with Config.toml
• 🔧 Rich CLI Interface - Generate, test, validate, and manage configurations
• 📁 Single Config Location - `~/.claude/statusline/Config.t