{"id":30811848,"url":"https://github.com/rz1989s/claude-code-statusline","last_synced_at":"2026-06-27T03:03:21.801Z","repository":{"id":331180581,"uuid":"1039979190","full_name":"rz1989s/claude-code-statusline","owner":"rz1989s","description":"Transform your Claude Code terminal with atomic precision statusline. Features flexible layouts, real-time cost tracking, MCP monitoring, prayer times, and beautiful themes.","archived":false,"fork":false,"pushed_at":"2026-06-25T03:49:44.000Z","size":19372,"stargazers_count":457,"open_issues_count":3,"forks_count":32,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-25T04:03:14.511Z","etag":null,"topics":["ai-tools","bash","caching","claude-code","cli-tool","cost-tracking","cross-platform","developer-tools","git-integration","islamic-prayer-times","modular-architecture","productivity","shell-script","statusline","terminal","toml"],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rz1989s.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"docs/security/SECURITY_HARDENING.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-08-18T09:21:05.000Z","updated_at":"2026-06-25T02:07:33.000Z","dependencies_parsed_at":null,"dependency_job_id":"f0235137-6522-4e25-8ae4-cee18adec74e","html_url":"https://github.com/rz1989s/claude-code-statusline","commit_stats":null,"previous_names":["rz1989s/claude-code-statusline"],"tags_count":74,"template":false,"template_full_name":null,"purl":"pkg:github/rz1989s/claude-code-statusline","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rz1989s%2Fclaude-code-statusline","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rz1989s%2Fclaude-code-statusline/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rz1989s%2Fclaude-code-statusline/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rz1989s%2Fclaude-code-statusline/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rz1989s","download_url":"https://codeload.github.com/rz1989s/claude-code-statusline/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rz1989s%2Fclaude-code-statusline/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34839888,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-27T02:00:06.362Z","response_time":126,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-tools","bash","caching","claude-code","cli-tool","cost-tracking","cross-platform","developer-tools","git-integration","islamic-prayer-times","modular-architecture","productivity","shell-script","statusline","terminal","toml"],"created_at":"2025-09-06T07:00:41.190Z","updated_at":"2026-06-27T03:03:21.768Z","avatar_url":"https://github.com/rz1989s.png","language":"Shell","funding_links":[],"categories":["Status Lines 📊","📚 Projects (1974 total)","Shell","Claude Code","Monitoring and Cost Tracking","MCP Servers \u0026 Protocol","状态栏 📊"],"sub_categories":["General","MCP Servers","Laravel","MCP Frameworks and Tooling","通用"],"readme":"\u003cdiv align=\"center\"\u003e\n\n\u003cpre\u003e\n███████╗███╗   ██╗██╗  ██╗ █████╗ ███╗   ██╗ ██████╗███████╗██████╗ \n██╔════╝████╗  ██║██║  ██║██╔══██╗████╗  ██║██╔════╝██╔════╝██╔══██╗\n█████╗  ██╔██╗ ██║███████║███████║██╔██╗ ██║██║     █████╗  ██║  ██║\n██╔══╝  ██║╚██╗██║██╔══██║██╔══██║██║╚██╗██║██║     ██╔══╝  ██║  ██║\n███████╗██║ ╚████║██║  ██║██║  ██║██║ ╚████║╚██████╗███████╗██████╔╝\n╚══════╝╚═╝  ╚═══╝╚═╝  ╚═╝╚═╝  ╚═╝╚═╝  ╚═══╝ ╚═════╝╚══════╝╚═════╝ \n\n███████╗████████╗ █████╗ ████████╗██╗   ██╗███████╗██╗     ██╗███╗   ██╗███████╗\n██╔════╝╚══██╔══╝██╔══██╗╚══██╔══╝██║   ██║██╔════╝██║     ██║████╗  ██║██╔════╝\n███████╗   ██║   ███████║   ██║   ██║   ██║███████╗██║     ██║██╔██╗ ██║█████╗  \n╚════██║   ██║   ██╔══██║   ██║   ██║   ██║╚════██║██║     ██║██║╚██╗██║██╔══╝  \n███████║   ██║   ██║  ██║   ██║   ╚██████╔╝███████║███████╗██║██║ ╚████║███████╗\n╚══════╝   ╚═╝   ╚═╝  ╚═╝   ╚═╝    ╚═════╝ ╚══════╝╚══════╝╚═╝╚═╝  ╚═══╝╚══════╝\n\u003c/pre\u003e\n\n# Claude Code Enhanced Statusline\n\n**🎨 Transform your terminal with 28 atomic components across 1-9 configurable lines**  \n*Block metrics • Burn rate monitoring • Cache efficiency • Cost projections • Atomic precision • Clean separators • Rich information display • Stunning themes • Real-time monitoring • MCP integration • Islamic prayer times • Ultimate customization*\n\n[![CI](https://github.com/rz1989s/claude-code-statusline/actions/workflows/ci.yml/badge.svg)](https://github.com/rz1989s/claude-code-statusline/actions/workflows/ci.yml)\n[![MIT License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n[![Platform Support](https://img.shields.io/badge/Platform-macOS%20%7C%20Linux%20%7C%20WSL-green.svg)](#-system-requirements)\n[![Shell](https://img.shields.io/badge/Shell-Bash-lightgrey.svg)]()\n[![Made for Claude Code](https://img.shields.io/badge/Made%20for-Claude%20Code-9333EA.svg)](https://claude.ai/code)\n[![Mentioned in Awesome Claude Code](https://awesome.re/mentioned-badge.svg)](https://github.com/hesreallyhim/awesome-claude-code)\n[![GitHub stars](https://img.shields.io/github/stars/rz1989s/claude-code-statusline?style=social)](https://github.com/rz1989s/claude-code-statusline/stargazers)\n\n## 🎥 Live Demo \u0026 Screenshots\n\n![Statusline Demo](assets/screenshots/statusline-demo.gif)\n\n**🎨 Catppuccin Mocha Theme in VS Code Terminal**\n\n![Beautiful Terminal](assets/screenshots/catppuccin-mocha-theme.png)\n\n\u003c/div\u003e\n\n## 🚀 Installation (2 minutes)\n\n**📋 Platform Requirements**: 100% compatible across all major platforms\n- **macOS** (12+): `brew install jq curl`\n- **Ubuntu/Debian**: `sudo apt install jq curl`\n- **Arch Linux**: `sudo pacman -S jq curl`\n- **Fedora/RHEL**: `sudo dnf install jq curl`\n- **Alpine Linux**: `apk add jq curl`\n- **Windows**: WSL recommended with Ubuntu distribution\n\n**Choose your preferred installation method:**\n\n### Option 1: Quick Install (Recommended)\n```bash\n# Download and inspect the installer (strongly recommended)\ncurl -fsSL https://raw.githubusercontent.com/rz1989s/claude-code-statusline/main/install.sh -o install.sh\n\n# Review what it does - look for:\n# ✓ Only creates files in ~/.claude/statusline/\n# ✓ Downloads from this GitHub repo\n# ✓ No sudo or system modifications\nless install.sh  \n\n# Run when you're satisfied it's safe\nbash install.sh\n```\n\n**🔍 Quick Security Check**: Open `install.sh` and verify it only:\n- Creates directories in `~/.claude/`\n- Downloads files from `raw.githubusercontent.com/rz1989s/claude-code-statusline`\n- Doesn't use `sudo` or modify system files\n- Uses `curl` with proper GitHub raw URLs\n- No network calls to external domains\n\n### Option 1b: One-Line Install (Trust the Repo)\n```bash\n# Direct install without inspection (for trusted users)\ncurl -sSfL https://raw.githubusercontent.com/rz1989s/claude-code-statusline/main/install.sh | bash\n```\n\n### 🔍 Enhanced Installer Options\n```bash\n# Check all dependencies (shows 6 feature categories)\ncurl -sSfL https://raw.githubusercontent.com/rz1989s/claude-code-statusline/main/install.sh | bash -s -- --check-all-deps\n\n# Interactive installation with user choices\ncurl -sSfL https://raw.githubusercontent.com/rz1989s/claude-code-statusline/main/install.sh | bash -s -- --interactive\n\n# Comprehensive dependency analysis + interactive mode\ncurl -sSfL https://raw.githubusercontent.com/rz1989s/claude-code-statusline/main/install.sh | bash -s -- --check-all-deps --interactive\n\n# Install from development branch\ncurl -sSfL https://raw.githubusercontent.com/rz1989s/claude-code-statusline/nightly/install.sh | bash -s -- --branch=nightly\n\n# Debug installation issues\nSTATUSLINE_INSTALL_DEBUG=true curl -sSfL https://raw.githubusercontent.com/rz1989s/claude-code-statusline/main/install.sh | bash\n```\n\n### Option 2: Manual Install (No script required)\n```bash\n# 1. Create directory structure\nmkdir -p ~/.claude/statusline/{lib,examples}\n\n# 2. Download core files\ncurl -fsSL https://raw.githubusercontent.com/rz1989s/claude-code-statusline/main/statusline.sh -o ~/.claude/statusline/statusline.sh\ncurl -fsSL https://raw.githubusercontent.com/rz1989s/claude-code-statusline/main/examples/Config.toml -o ~/.claude/statusline/Config.toml\n\n# 3. Download library modules (automated)\ncurl -sSfL https://raw.githubusercontent.com/rz1989s/claude-code-statusline/main/install.sh | bash -s -- --modules-only\n\n# 4. Make executable and test\nchmod +x ~/.claude/statusline/statusline.sh\n~/.claude/statusline/statusline.sh --version\n```\n\n### ✅ Verify Installation Success\n```bash\n# Confirm installation success\n~/.claude/statusline/statusline.sh --version\nls -la ~/.claude/statusline/lib/  # Should show 10+ module files\n\n# Test with sample input\necho '{\"workspace\": {\"current_dir\": \"'\"$(pwd)\"'\"}, \"model\": {\"display_name\": \"Test\"}}' | ~/.claude/statusline/statusline.sh\n```\n\n### What Does This Install?\n**🔍 Transparency First - Here's exactly what happens:**\n\n✅ **Creates one directory**: `~/.claude/statusline/` (in your home folder only)  \n✅ **Downloads 31 text files**: Shell scripts from this GitHub repository  \n✅ **Creates one config file**: `Config.toml` with default settings you can edit  \n✅ **No system changes**: Everything stays in your home folder  \n\n❌ **Does NOT**: \n- Modify any system files or PATH  \n- Install packages globally or change your OS  \n- Require admin/sudo permissions  \n- Send data anywhere or phone home  \n- Modify your shell config (.bashrc, .zshrc, etc.)  \n\n**🔐 Security**: All files are downloaded from this public GitHub repository - you can inspect every line of code before running.\n\n---\n\n## 📚 Table of Contents\n\n- [Installation](#-installation-2-minutes)\n- [Recent Updates](#-recent-updates)\n- [Features](#-features)\n- [Theme Gallery](#-theme-gallery)\n- [Screenshot Showcase](#-screenshot-showcase)\n- [Advanced Setup](#-advanced-setup)\n- [Configuration](#️-configuration)\n- [What Each Line Shows](#-what-each-line-shows)\n- [System Requirements](#-system-requirements)\n- [Documentation](#-documentation)\n- [Contributing](#-contributing)\n  - [Development Setup](#-development-setup)\n  - [Testing](#testing-information)\n- [License](#-license)\n- [Acknowledgments](#-acknowledgments)\n\n---\n\n## 🆕 Recent Updates\n\n### v2.10.0 - Advanced Block Metrics Integration 🔥📊 **LATEST**\n\n**🚀 REVOLUTIONARY BLOCK METRICS SYSTEM**\n- **4 NEW Block Metrics Components** - 100% native cost calculation with 75% resource reduction\n- **Unified Data Collection** - Single API call feeds all metrics (burn rate, tokens, cache efficiency, projections)  \n- **Burn Rate Monitoring** - Critical token consumption tracking (🔥3.5k/min $2.10/hr)\n- **Cache Efficiency** - Performance optimization insights (Cache: 94% hit)\n- **Cost Projections** - Budget planning and limit avoidance (Est: $16.48)\n- **Resource Optimized** - Minimal background processes, smart 30s caching\n\n---\n\n### v2.9.0 - Revolutionary 3-Tier Download System 🚀⚡\n\n**🚀 REVOLUTIONARY INSTALLER OVERHAUL**\n\n- **3-Tier Download Architecture** - Complete installer architectural overhaul eliminates GitHub rate limits forever\n- **Tier 1: Direct Raw URLs** - Unlimited requests, no API usage, fastest installation method (handles 99% of cases)\n- **Tier 2: GitHub API Fallback** - Optional token support increases limits from 60/hour to 5,000/hour\n- **Tier 3: Comprehensive Retry** - Exponential backoff and intelligent verification with detailed troubleshooting\n- **100% Download Guarantee** - Either all modules download successfully or clear failure with actionable guidance\n- **Zero Intervention Required** - Primary method handles installations automatically without user interaction\n\n**⚡ INSTALLATION IMPROVEMENTS**\n\n- **Eliminates GitHub Rate Limits** - Direct raw URLs bypass API limitations completely\n- **Enhanced Error Handling** - Exponential backoff and comprehensive retry mechanisms\n- **Performance Benefits** - Fastest installation method using direct raw URLs\n- **Backward Compatible** - All existing installation methods preserved and enhanced\n\n**🐛 ADDITIONAL FIXES**\n\n- **Fixed Prayer Time Calculation** - Resolved \"24h 0m\" display bug, now shows \"(0m)\" for exact matches\n- **Enhanced Test Coverage** - Added comprehensive test cases for prayer time edge scenarios\n\n**📈 IMPACT**: **Bulletproof installation system** - Reliable, fast installation regardless of GitHub API availability, with 100% download guarantee and zero user intervention required.\n\n---\n\n### v2.8.0 - Single Source Configuration Revolution 🧹🎯\n\n**🎯 REVOLUTIONARY SIMPLIFICATION: SINGLE SOURCE OF TRUTH ARCHITECTURE**\n\nTransform your configuration experience with the **most significant architectural simplification** ever:\n\n- **🧹 Configuration Breakthrough** - Eliminated triple redundancy system:\n  - ❌ **Before**: 13 example configs + hardcoded defaults + jq fallbacks = chaos\n  - ✅ **After**: ONE comprehensive Config.toml with all 227 settings = clarity\n  \n- **🎯 Zero Hunting** - All parameters pre-filled in Config.toml, just edit values\n- **🔧 Zero Code Defaults** - No more DEFAULT_CONFIG_* constants scattered in lib/config.sh\n- **⚡ Pure Extraction** - No jq fallbacks (`// \"default\"`), reads directly from TOML\n- **📁 Simplified Structure** - Only examples/Config.toml + README.md (no confusion)\n\n**🎯 USER EXPERIENCE TRANSFORMATION**\n```toml\n# BEFORE: Hunt for parameter names across 13 config files\n# ~/.claude/statusline/examples/Config.modular-compact.toml\n# ~/.claude/statusline/examples/Config.modular-atomic.toml\n# ... 11 more files to choose from\n\n# AFTER: Edit ONE comprehensive file with ALL settings\n# ~/.claude/statusline/Config.toml (227 settings included!)\ntheme.name = \"catppuccin\"              # Theme selection\ndisplay.lines = 5                      # Line count (1-9)\ndisplay.line1.components = [\"repo_info\", \"commits\", \"version_info\"]\nlabels.commits = \"Commits:\"            # Display labels\n# ... ALL 227 settings right here!\n```\n\n---\n\n### v2.7.0 - Atomic Component System ⚛️🎯\n\n**🎯 ULTIMATE CUSTOMIZATION: ATOMIC COMPONENT BREAKTHROUGH**\n\nTransform your statusline with **28 atomic components** that eliminate separator issues and provide maximum control:\n\n- **🔬 Atomic Components** - Single-purpose units for maximum control:\n  - `commits` - Shows ONLY commit count (pure atomic)\n  - `submodules` - Shows ONLY submodule status (pure atomic)\n  - `cost_monthly` - Shows ONLY 30-day costs (pure atomic)\n  - `cost_weekly` - Shows ONLY 7-day costs (pure atomic)\n  - `cost_daily` - Shows ONLY daily costs (pure atomic)\n\n- **🎨 Clean Visual Separation** - No more `30DAY $660.87 7DAY $9.31 DAY $36.10`! Now: `30DAY $660.87 │ 7DAY $9.31 │ DAY $36.10`\n- **🧩 Maximum Control** - Want only commits without submodules? Use `commits` component only\n- **⚙️ Pure Atomic Architecture** - No legacy bundled components, each component shows unique data only\n- **📋 8 Example Configs** - Including new `Config.modular-atomic.toml` showcase\n\n**⚛️ ATOMIC CONFIGURATION EXAMPLES**\n```toml\n# Show only specific git info\ndisplay.line1.components = [\"repo_info\", \"commits\", \"version_info\"]\n\n# Custom cost tracking - pick exactly what you need\ndisplay.line2.components = [\"cost_monthly\", \"cost_daily\"]\n\n# Pure atomic components\ndisplay.line3.components = [\"commits\", \"cost_weekly\", \"mcp_status\"]\n```\n\n---\n\n### v2.6.0 - Modular Component System \u0026 Configurable 1-9 Line Statusline 🧩🎯\n\n**🎯 MAJOR ARCHITECTURAL BREAKTHROUGH: MODULAR COMPONENT SYSTEM**\n\n- **Complete Component Architecture** - 18 individual component modules with standardized interfaces (`collect_data()`, `render()`, `get_config()`)\n- **Configurable 1-9 Line Display** - Flexible line layouts from minimal 1-line to comprehensive 9-line configurations\n- **Component Registry System** - Advanced component management with dependency tracking and enablement states\n- **Mix \u0026 Match Flexibility** - Arrange any component on any line position (MCP on line 1, prayer times on line 2, etc.)\n- **Backward Compatibility** - Legacy 5-line system preserved as fallback with seamless migration path\n\n**🧩 INDIVIDUAL COMPONENT MODULES**\n\n- **`repo_info.sh`** - Repository directory and git status display\n- **`commits.sh`** - Commit count (pure atomic)\n- **`submodules.sh`** - Submodule tracking (pure atomic)\n- **`version_info.sh`** - Claude Code version with intelligent caching\n- **`time_display.sh`** - Current time formatting and display\n- **`model_info.sh`** - Claude model identification with emoji indicators\n- **`cost_repo.sh`** - Repository session cost tracking\n- **`cost_monthly.sh`** - 30-day costs (pure atomic)\n- **`cost_weekly.sh`** - 7-day costs (pure atomic)\n- **`cost_daily.sh`** - Daily costs (pure atomic)\n- **`cost_live.sh`** - Live billing block cost monitoring\n- **`mcp_status.sh`** - MCP server health and connection status\n- **`reset_timer.sh`** - Block reset countdown and timer management\n- **`prayer_times.sh`** - Islamic prayer times integration\n\n**⚙️ FLEXIBLE TOML CONFIGURATION SYSTEM**\n\n```toml\n# Compact 3-line layout\ndisplay.lines = 3\ndisplay.line1.components = [\"repo_info\", \"commits\", \"submodules\"]\ndisplay.line2.components = [\"model_info\", \"cost_repo\"] \ndisplay.line3.components = [\"mcp_status\"]\n\n# Custom reordering - prioritize what matters to you!\ndisplay.line1.components = [\"mcp_status\", \"prayer_times\"]\ndisplay.line2.components = [\"repo_info\", \"version_info\"]\n```\n\n**🏗️ ENHANCED MODULAR ARCHITECTURE**\n\n- **91.5% Code Reduction** - Main orchestrator reduced from monolithic script to clean 368-line module loader\n- **Component-Based Data Flow** - Standardized interfaces enable consistent behavior and easy testing\n- **Advanced Configuration Parsing** - Modular line configuration with component arrangement flexibility\n- **Enhanced Maintainability** - Individual components can be developed, tested, and maintained independently\n\n**📈 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.\n\n---\n\n### v2.2.0 - Islamic Prayer Times \u0026 Hijri Calendar Integration 🕌📅\n\n**🕌 MAJOR NEW FEATURE: ISLAMIC PRAYER TIMES**\n\n- **Complete Prayer Times Display** - All 5 daily Islamic prayers (Fajr, Dhuhr, Asr, Maghrib, Isha) with real-time status indicators\n- **AlAdhan API Integration** - Accurate prayer time calculations using the trusted AlAdhan API with multiple calculation methods (ISNA, MWL, Makkah, etc.)\n- **Visual Status Indicators** - ✓ for completed prayers, time remaining display (e.g., \"3h 29m\") with green highlighting for upcoming prayers, elegant formatting with 🕌 Islamic indicator\n- **Intelligent Caching** - 1-hour cache duration for optimal performance, location-aware cache keys, automatic refresh\n\n**🌙 HIJRI CALENDAR WITH AUTHENTIC ISLAMIC TIMEKEEPING**\n\n- **Maghrib-Based Day Changes** - Proper Islamic calendar where Hijri date changes at Maghrib (sunset), not midnight - authentic to Islamic tradition\n- **Real-Time Hijri Date Display** - Current Islamic date with Arabic month names (e.g., \"2 Jumādá al-ūlá 1452\")\n- **Moon Phase Indicator** - 🌙 symbol when Islamic day changes at Maghrib time\n- **Multiple Calculation Standards** - Support for Umm Al-Qura and other Hijri calculation methods\n\n**🔧 COMPREHENSIVE CONFIGURATION SYSTEM**\n\n- **Full Prayer Customization** - Calculation methods (ISNA/MWL/Makkah), Madhab selection (Shafi/Hanafi), manual/auto location modes\n- **Location Intelligence** - Auto-detection or manual coordinates, timezone override support\n- **Display Preferences** - 12h/24h time formats, completed indicators, next prayer highlighting, countdown timers\n- **Hijri Calendar Options** - Arabic month names, weekday display, Maghrib change indicators, manual adjustments\n\n**🏗️ ENHANCED ARCHITECTURE**\n\n- **New Prayer Module** - `lib/prayer.sh` with 400+ lines of Islamic timekeeping logic following existing modular patterns\n- **Modular Display System** - **Configurable 1-9 line statusline** with flexible component arrangement and dedicated Islamic prayer times\n- **Comprehensive Testing** - Complete unit test suite in `tests/unit/test_prayer_functions.bats` with edge case coverage\n- **Performance Optimized** - \u003c 2s execution with intelligent caching, graceful API fallbacks, minimal external dependencies\n\n**📈 IMPACT**: Muslim developers now have accurate Islamic timekeeping integrated seamlessly into their development workflow with authentic religious observance support.\n\n---\n\n### v2.0.6 - Enhanced Reliability \u0026 Timeout Improvements 🚀⚡\n\n**🐛 CRITICAL BUG FIXES**\n\n- **Fixed DAY $0.00 display issue** - Resolved timeout-related failure in daily cost calculations\n- **Enhanced configuration fallback logic** - Improved handling of empty string values in TOML config parsing\n\n**⚡ PERFORMANCE \u0026 RELIABILITY IMPROVEMENTS** \n\n- **Standardized all timeouts to 10s minimum** - Increased reliability for external command execution\n  - `DEFAULT_VERSION_TIMEOUT`: 2s → 10s\n  - `CACHE_CONFIG_ATOMIC_TIMEOUT`: 5s → 10s\n- **Updated all configuration examples** - Ensures consistent timeout values across all TOML templates\n\n**📚 DOCUMENTATION ENHANCEMENTS**\n\n- **Streamlined CLAUDE.md** - Enhanced developer experience with clearer quick reference section\n- **Updated cache timing documentation** - Improved accuracy of cache behavior explanations\n- **Better configuration guidance** - Updated examples to reflect new timeout standards\n\n**📈 IMPACT**: Eliminated DAY cost display bug, improved system reliability, and enhanced timeout handling\n\n---\n\n### v1.8.0 - Enterprise-Grade Security \u0026 Performance Enhancement 🛡️✨\n\n- **🔒 XDG-Compliant Cache Security** - Migrated from `/tmp` to secure user-isolated directories following XDG Base Directory specification\n- **🔐 SHA-256 Integrity Protection** - Advanced checksum validation with automatic corruption detection and recovery\n- **🌍 Enhanced Git Branch Validation** - Unicode and emoji support using `git check-ref-format` for authentic validation\n- **🧹 Comprehensive Resource Cleanup** - Signal traps (EXIT/INT/TERM/HUP) prevent resource leaks under any termination scenario\n- **⚙️ Advanced TOML Configuration** - Expanded cache configuration with 40+ settings for fine-tuned performance control\n- **🔧 Intelligent Error Handling** - Context-aware error messages with actionable recovery suggestions and automatic fallback systems\n- **📊 Real-Time Performance Analytics** - Hit/miss ratios, response times, efficiency classification, and memory usage monitoring\n- **🔍 Cache Integrity Auditing** - Built-in tools for cache health monitoring, corruption detection, and migration recommendations\n- **🧪 77+ Comprehensive Tests** - Unit, integration, and performance regression test coverage with multi-instance validation\n- **📈 Performance Classification** - EXCELLENT/GOOD/MODERATE/POOR ratings with optimization recommendations\n\n### v1.7.0 - Ultra-Comprehensive Universal Caching Revolution 🎆\n\n- **🌍 Universal Operation Caching** - Optimizes ALL external commands, not just API calls\n- **🚀 70-90% Performance Improvement** - Dramatic reduction in external command execution\n- **🔍 Command Existence Caching** - Session-wide caching eliminates repeated PATH lookups  \n- **🔧 Git Operations Caching** - Intelligent duration-based caching for all git commands\n- **🌐 Enhanced External Commands** - Improved `claude --version` and `claude mcp list` caching\n- **🖥️ System Information Caching** - Permanent caching for OS type, architecture\n- **⚡ Sub-50ms Responses** - Lightning-fast statusline execution (from 200-500ms)\n- **🛡️ Universal Multi-Instance Safety** - Zero race conditions across all operations\n- **🕰️ Smart Duration Strategy** - From session-wide to real-time based on change frequency\n- **🧠 Intelligent Startup Detection** - Force refresh on first startup across all cached operations\n\n### v1.6.0 - Intelligent Multi-Tier Caching System 🧠\n\n### v1.5.2 - Enhanced Installation \u0026 Bug Fixes 🔧\n\n- **🛠️ Enhanced Installer** - Fixed curl failure by ensuring directory creation before download\n- **📁 Improved Path Management** - Enhanced installation path handling for better compatibility\n- **🎯 Streamlined Architecture** - Simplified version management for easier maintenance\n- **🐛 Bug Fixes** - Resolved missing model emojis in statusline display\n- **📋 Updated Documentation** - Comprehensive documentation enhancements and project organization\n- **✅ Contributor Ready** - Finalized CONTRIBUTING.md with complete development guidelines\n\n### v1.5.0 - Simplified Version Management Architecture 🎯\n\n- **📍 Single Source of Truth** - Introduced `version.txt` as master version file for entire codebase\n- **🛠️ Version Management Scripts** - Automated tools for version synchronization and consistency checks\n- **🔄 Dynamic Version Reading** - All components now read version from centralized source\n- **📦 Automated Package Sync** - Scripts maintain package.json synchronization with version.txt\n- **✅ System Verification** - Comprehensive testing tools for version consistency\n- **📚 Complete Documentation** - Full guide for centralized version management workflow\n\n### v1.3.1 - Enhanced Error Messages \u0026 Documentation 🔧\n\n- **📝 Improved Error Messages** - Enhanced module loading error messages with specific troubleshooting guidance  \n- **📚 Function Documentation** - Added comprehensive documentation to core.sh functions\n- **🧪 Enhanced Testing** - New test coverage for module loading functionality\n- **🔍 Better Diagnostics** - Clearer error messages help users resolve issues faster\n\n### v1.3.0 - Modular Architecture Implementation 🏗️ \n\n*Contains internal v2.0.6-refactored architecture while maintaining v1.3.x compatibility*\n\n- **🏗️ Modular Architecture** - Complete refactor from 3930-line monolithic script to clean modular system\n- **📦 9 Specialized Modules** - Core, security, config, themes, git, MCP, cost, display, and cache modules  \n- **🎯 91.4% Code Reduction** - Main orchestrator reduced to 338 lines with preserved functionality\n- **🔧 Enhanced Maintainability** - Clear separation of concerns and dependency management\n- **⚡ Improved Performance** - Optimized module loading and reduced complexity\n- **🔄 100% Backward Compatible** - All existing functionality and configuration preserved\n\n### v1.2 - Enhanced Timeout Validation \u0026 Configuration Improvements 🚀\n\n- **✅ Comprehensive Timeout Validation** - Enhanced bounds checking with contextual suggestions\n- **🔧 Smart Configuration Validation** - Prevents dangerous timeout values (0s, \u003e60s)\n- **📖 Enhanced CLI Documentation** - Detailed timeout configuration guidance\n- **🛠️ New Helper Functions** - `parse_timeout_to_seconds()` and `validate_timeout_bounds()`\n- **💡 Contextual Error Messages** - Specific suggestions for optimal timeout ranges\n- **🔄 Backward Compatible** - All existing configurations continue to work\n\n### v1.1 - Enhanced Directory Structure \u0026 TOML Configuration\n\n- **📋 TOML Configuration Files** - Modern, structured configuration with `Config.toml`\n- **🔧 Rich CLI Interface** - Generate, test, validate, and manage configurations\n- **📁 Single Config Location** - `~/.claude/statusline/Config.toml` (simple and consistent)\n- **🌐 Environment Overrides** - `ENV_CONFIG_*` variables override all settings\n- **🔄 Live Reload** - Hot configuration reloading with `--watch-config`\n- **🎨 Theme System** - Built-in themes with full custom color support\n- **✅ Configuration Validation** - Built-in testing and error checking with auto-fix suggestions\n- **📦 Migration Tools** - Seamless migration from inline configuration\n- **⚡ 100% Backwards Compatible** - Existing inline configuration continues to work\n\n### v1.0 - Enhanced Statusline Foundation\n\n- **🎨 Three Stunning Themes** - Classic, Garden (pastels), and Catppuccin Mocha\n- **💰 Real-time Cost Tracking** - 100% native JSONL-based cost calculation\n- **🔌 MCP Server Monitoring** - Live status of Model Context Protocol servers\n- **⏰ Block Reset Timer** - Track your 5-hour conversation blocks with countdown\n- **📊 Git Integration** - Repository status, commit counting, and branch information\n- **⚡ Performance Optimized** - Smart caching and configurable timeouts\n\n---\n\n## ✨ Features\n\n### 🎨 **Stunning Visual Interface**\n\nExperience three beautifully crafted themes that transform your terminal into a work of art:\n\n- **🌙 Catppuccin Mocha** - Rich, warm colors with excellent contrast\n- **🌿 Garden Theme** - Soft pastels for a gentle, soothing aesthetic  \n- **⚡ Classic Theme** - Traditional terminal colors with modern polish\n- **🎨 Custom Themes** - Full RGB/256-color/ANSI color customization\n\n### 🧩 **Revolutionary Modular Component System (v2.6.0)**\n\n![Repository Information](assets/screenshots/basic-repo-info.png)\n\n**🎯 BREAKTHROUGH: Fully Configurable 1-9 Line Display System**\n\nTransform your statusline from a fixed layout to a completely personalized information dashboard! The revolutionary modular system gives you **complete control** over what information appears where.\n\n**🌟 Key Modular Features:**\n- **📐 1-9 Line Flexibility** - From ultra-minimal 1-line to comprehensive 9-line displays\n- **🧩 18 Individual Components** - Mix, match, and reorder any component on any line\n- **🎛️ Component Registry** - Advanced management with dependency tracking\n- **⚡ Real-time Reconfiguration** - Change layouts instantly with environment variables\n- **🔄 Backward Compatible** - Legacy 5-line system preserved as fallback\n\n**📋 Example Layout Transformations:**\n\n**Ultra-Minimal (2-line):**\n```toml\ndisplay.lines = 2\ndisplay.line1.components = [\"repo_info\", \"model_info\"]\ndisplay.line2.components = [\"cost_repo\"]\n```\n\n**Creative Reordering (6-line):**\n```toml  \ndisplay.lines = 6\ndisplay.line1.components = [\"mcp_status\", \"version_info\"]      # MCP first!\ndisplay.line2.components = [\"prayer_times\", \"time_display\"]    # Prayer times priority\ndisplay.line3.components = [\"repo_info\", \"model_info\"]         # Repository info\ndisplay.line4.components = [\"commits\", \"submodules\"]               # Atomic git stats\ndisplay.line5.components = [\"cost_repo\", \"cost_monthly\", \"cost_live\"]  # All costs together\ndisplay.line6.components = [\"reset_timer\"]                     # Timer when active\n```\n\n**📋 Default 5-Line Layout (Customizable):**\n\n**Line 1: Repository \u0026 Environment** *(Components: `repo_info`, `commits`, `submodules`, `version_info`, `time_display`)*\n- Working directory with elegant `~` notation\n- Git branch with clean/dirty status indicators  \n- Today's commit count tracking\n- Claude Code version (intelligently cached)\n- Git submodule count\n- Current time display\n\n**Line 2: Model \u0026 Cost Tracking** *(Components: `model_info`, `cost_repo`, `cost_monthly`, `cost_weekly`, `cost_daily`, `cost_live`)*\n- Current Claude model with emoji indicators\n- Repository session costs\n- 30-day, 7-day, and daily spending totals\n- Live billing block costs with native JSONL calculation\n- Real-time financial monitoring\n\n![MCP Server Monitoring](assets/screenshots/mcp-info.png)\n\n**Line 3: MCP Server Health** *(Component: `mcp_status`)*\n- Connected vs total server count\n- Server names with connection status\n- Color-coded indicators (🟢 connected, 🔴 disconnected)\n- Real-time health monitoring\n\n**Line 4: Block Reset Timer** *(Component: `reset_timer`)*\n- Next reset time display\n- Countdown to block expiration\n- Smart detection and tracking\n\n**Line 5: Islamic Prayer Times** *(Component: `prayer_times`)*\n- All 5 daily Islamic prayers (Fajr, Dhuhr, Asr, Maghrib, Isha) with accurate timing\n- Real-time Hijri date with authentic Maghrib-based day changes\n- Visual prayer status indicators (✓ completed, time remaining with green highlighting for upcoming)\n- AlAdhan API integration with multiple calculation methods\n- 🕌 Islamic formatting with moon phase indicators 🌙\n\n### 🧩 **Modular Component System (v2.6.0)**\n\n**Available Components:**\n- `repo_info` - Directory path and git status\n- `commits` - Commit count (atomic)\n- `submodules` - Submodule status (atomic)\n- `version_info` - Claude Code version\n- `time_display` - Current time\n- `model_info` - Claude model with emoji\n- `cost_repo` - Repository session cost\n- `cost_monthly` - 30-day costs (atomic)\n- `cost_weekly` - 7-day costs (atomic)\n- `cost_daily` - Daily costs (atomic)\n- `cost_live` - Live block cost\n- `mcp_status` - MCP server health\n- `reset_timer` - Block reset countdown\n- `prayer_times` - Islamic prayer times\n\n**Configuration Examples:**\n```toml\n# Compact 3-line layout\ndisplay.lines = 3\ndisplay.line1.components = [\"repo_info\", \"commits\", \"submodules\"]\ndisplay.line2.components = [\"model_info\", \"cost_repo\"] \ndisplay.line3.components = [\"mcp_status\"]\n\n# Custom reordering - MCP first!\ndisplay.line1.components = [\"mcp_status\", \"version_info\"]\ndisplay.line2.components = [\"prayer_times\", \"time_display\"]\ndisplay.line3.components = [\"repo_info\", \"model_info\"]\n```\n\n### 🌍 **Intelligent Worldwide Auto-Location Detection**\n\n**🎯 ZERO CONFIGURATION: Works automatically for 2+ billion Muslims worldwide!**\n\nOur breakthrough auto-detection system automatically determines your location and selects the correct Islamic prayer calculation method, covering 98% of the global Muslim population with no manual setup required.\n\n#### **🚀 Multi-Tier Auto-Detection Process**\n\n**🌐 Tier 1: IP Geolocation (Online)**\n- Uses free ip-api.com service (45 requests/min, no API key required)\n- Detects country, city, precise coordinates, and timezone\n- Maps country → appropriate prayer calculation method automatically\n- Results cached for 7 days for offline reliability\n\n**💾 Tier 2: Cached Location (Offline)**\n- Uses cached IP geolocation data (7-day expiry)\n- Zero network requirements - works completely offline\n- Maintains user privacy with local storage only\n\n**🕐 Tier 3: System Timezone Mapping (Offline)**  \n- Maps system timezone → country → prayer method\n- **Covers 98% of global Muslim population** with 100+ timezone mappings\n- Provides region-specific coordinates for major Islamic cities\n- Lightning-fast offline operation (microsecond response times)\n\n**🌏 Tier 4: System Locale Fallback**\n- Uses system locale as location hint\n- Safe fallback for unknown regions with Muslim World League (MWL) method\n\n#### **🌟 Comprehensive Global Coverage**\n\n**📊 Automatic Support For:**\n- **🕌 28 Major Islamic Countries** - Indonesia, Pakistan, Saudi Arabia, Egypt, Turkey, etc.\n- **🌍 All Middle Eastern Countries** - Complete Gulf region coverage\n- **🏙️ Major Muslim Communities** - Europe, Americas, Australia, Russia\n- **⏰ 100+ Timezone Mappings** - Every Islamic region worldwide\n- **🏳️ 80+ Country Codes** - IP geolocation covers all countries\n\n**📈 Regional Coverage:**\n- **Southeast Asia (450M Muslims)** - Indonesia → KEMENAG, Malaysia → JAKIM, Singapore → MUIS\n- **South Asia (620M Muslims)** - Pakistan/India/Bangladesh → Karachi University\n- **Middle East \u0026 Gulf (120M Muslims)** - Saudi → Umm al-Qura, UAE → Dubai, Iran → Tehran\n- **North Africa (280M Muslims)** - Egypt → Egyptian Authority, Morocco → Morocco method\n- **Europe (60M Muslims)** - Russia → Spiritual Admin, France → UOIF, UK → MWL\n- **Americas \u0026 Oceania (15M Muslims)** - USA/Canada → ISNA, Australia → MWL\n\n#### **⚙️ Location Detection Modes**\n\n```toml\n# In your Config.toml file\nprayer.location_mode = \"auto\"        # ⭐ RECOMMENDED: Comprehensive auto-detection\nprayer.location_mode = \"ip_based\"    # Force IP geolocation only (requires internet)  \nprayer.location_mode = \"manual\"      # Use manual coordinates (disable auto-detection)\n```\n\n#### **🔒 Privacy \u0026 Performance**\n\n- **Privacy-First Design** - Location data cached locally, no tracking or data collection\n- **IP Geolocation Transparency** - When using auto-detection, your IP address is sent to ip-api.com for location lookup (can be disabled)\n- **Local Data Storage** - All location and prayer data stored locally in `~/.cache/claude-code-statusline/` \n- **No Personal Information** - Only coordinates and prayer calculation method are stored, no personal data\n- **Manual Override Available** - Set `prayer.location_mode = \"manual\"` to completely disable IP-based detection\n- **Graceful Degradation** - Works offline with timezone/locale fallbacks when internet unavailable\n- **Intelligent Caching** - 7-day cache prevents repeated API calls, reduces external requests\n- **Ultra-Fast Offline** - Timezone mapping completes in microseconds using local data structures\n- **Zero Dependencies** - No external libraries required for offline operation\n\n#### **🎯 Example Auto-Detection Results**\n\n```bash\n# Indonesia User\n# Timezone: Asia/Jakarta → Method: KEMENAG (20) → Coordinates: Jakarta\n🕌 12 Jumādá al-ūlá 1453 │ Fajr 04:35 ✓ │ Dhuhr 11:53 (2h 18m) │ Asr 15:10 │ Maghrib 17:52 │ Isha 19:02\n\n# USA User  \n# Timezone: America/New_York → Method: ISNA (2) → Coordinates: New York\n🕌 12 Jumādá al-ūlá 1453 │ Fajr 05:42 ✓ │ Dhuhr 12:15 (3h 25m) │ Asr 15:28 │ Maghrib 18:05 │ Isha 19:35\n\n# Saudi User\n# Timezone: Asia/Riyadh → Method: Umm al-Qura (4) → Coordinates: Riyadh  \n🕌 12 Jumādá al-ūlá 1453 │ Fajr 04:18 ✓ │ Dhuhr 11:47 (1h 52m) │ Asr 15:02 │ Maghrib 17:41 │ Isha 19:11\n```\n\n**💡 The statusline works perfectly out-of-the-box for Muslims anywhere in the world - no configuration needed!**\n\n### 🏗️ **Modular Architecture**\n\n- **📦 11 Specialized Modules** - Clean separation of concerns with dedicated modules for each feature\n  - `core.sh` - Base utilities, module loading, and performance timing\n  - `security.sh` - Input sanitization and secure file operations  \n  - `config.sh` - TOML configuration parsing and modular line management\n  - `themes.sh` - Color theme system with inheritance support\n  - `components.sh` - **NEW** Component registry and modular display system\n  - `git.sh` - Repository status, branch detection, and commit tracking\n  - `mcp.sh` - MCP server monitoring and health checking\n  - `cost.sh` - Native cost tracking from JSONL files\n  - `prayer.sh` - Islamic prayer times and Hijri calendar with AlAdhan API integration\n  - `display.sh` - Modular output formatting and 1-9 line statusline generation\n  - `cache.sh` - Universal intelligent caching system with enterprise-grade features\n  - `lib/components/` - **NEW** Individual component modules for flexible arrangement\n- **🎯 91.4% Code Reduction** - Main orchestrator script reduced from 3930 to 338 lines\n- **🔧 Enhanced Maintainability** - Modular design enables easier testing, debugging, and feature development\n- **⚡ Improved Performance** - Optimized module loading and reduced script complexity\n\n### 🚀 **Ultra-Comprehensive Universal Caching System (v1.8.0)**\n\nRevolutionary performance enhancement system that transforms statusline response times from seconds to milliseconds:\n\n#### **⚡ Performance Achievements**\n- **95% Performance Improvement** - Statusline response time from 2-6 seconds to **sub-50ms**\n- **70-90% Command Reduction** - Intelligent session-wide caching eliminates redundant operations\n- **Multi-Tier Duration Strategy** - Optimized cache lifetimes (2s to 24h) based on data volatility\n\n#### **🛡️ Enterprise-Grade Security Features**\n- **XDG-Compliant Cache Location** - Follows XDG Base Directory specification for secure, user-isolated storage\n- **SHA-256 Integrity Protection** - Advanced checksum validation prevents cache corruption\n- **Intelligent Migration System** - Seamlessly migrates from legacy `/tmp` location to secure directories\n- **Multi-Instance Safety** - Atomic operations with random backoff prevent race conditions under concurrent access\n\n#### **📊 Advanced Performance Analytics** \n- **Real-Time Statistics** - Cache hit/miss ratios, response times, and efficiency metrics\n- **Performance Classification** - EXCELLENT (≥80%), GOOD (60-79%), MODERATE (40-59%), POOR (\u003c40%)\n- **Memory Usage Monitoring** - Track cache storage consumption and optimize resource usage\n- **Detailed Reporting** - Per-operation analytics with comprehensive performance insights\n\n#### **🔧 Intelligent Error Handling \u0026 Recovery**\n- **Actionable Error Messages** - Context-aware warnings with specific recovery suggestions\n- **Automatic Corruption Detection** - Advanced validation removes invalid cache files automatically  \n- **Smart Fallback Systems** - Graceful degradation ensures reliability even when caching fails\n- **Resource Cleanup** - Comprehensive cleanup traps prevent resource leaks on interruption\n\n#### **⚙️ Comprehensive TOML Configuration**\n```toml\ncache.base_directory = \"auto\"              # XDG-compliant auto-selection\ncache.enable_universal_caching = true      # Master cache toggle\ncache.enable_statistics = true             # Performance analytics\ncache.enable_corruption_detection = true   # SHA-256 integrity validation\n\ncache.durations.command_exists = \"session\"           # Session-wide command caching\ncache.durations.claude_version = 900              # 15 minutes for CLI version\ncache.durations.git_status = 10                     # 10 seconds for git working directory\ncache.durations.mcp_server_list = 120               # 2 minutes for MCP connections\n\ncache.security.enable_checksums = true             # SHA-256 integrity protection\ncache.security.validate_on_read = true             # Real-time corruption detection\ncache.security.directory_permissions = \"700\"        # Secure directory access\ncache.security.file_permissions = \"600\"            # Owner-only file access\n```\n\n#### **🧪 Validation \u0026 Testing**\n- **100% Multi-Instance Success Rate** - Verified across 5 concurrent instances with zero race conditions\n- **77+ Comprehensive Tests** - Unit, integration, and performance regression test coverage\n- **Cache Integrity Auditing** - Built-in tools for cache health monitoring and validation\n- **Performance Benchmarking** - Continuous monitoring prevents performance regressions\n\n### ⚡ **Smart Performance \u0026 Advanced Caching System**\n\n- **🧠 Intelligent Multi-Tier Caching** - Differentiated cache durations by data type for optimal performance\n- **🚀 Startup Detection** - Forces fresh data on first Claude Code launch, then uses smart caching\n- **⚡ 98% API Call Reduction** - 7DAY data cached for 1 hour, 30DAY for 2 hours (vs 30 seconds)\n- **🔄 Multi-Instance Safe** - Race condition protection for multiple Claude Code sessions\n- **🔒 Enhanced Locking** - Atomic writes, retry logic, and stale lock cleanup\n- **📦 Cache Validation** - JSON integrity checking and corrupted cache recovery\n- **⏱️ Configurable Timeouts** - Prevents hanging on slow networks  \n- **📊 Real-time Live Data** - Active blocks still update every 30 seconds\n- **🌍 Cross-Platform** - Works seamlessly on macOS, Linux, and WSL\n- **💾 Memory Efficient** - Minimal resource usage with maximum information\n\n### 🔧 **Enterprise-Grade Configuration**\n\n- **📋 TOML Configuration System** - Modern structured configuration files\n- **🔧 Rich CLI Tools** - Generate, test, validate, and manage configurations\n- **🎛️ Feature Toggles** - Enable/disable any display section via TOML\n- **🌐 Environment Overrides** - `ENV_CONFIG_*` variables for dynamic settings\n- **🎨 Advanced Theme System** - Theme inheritance, profiles, and custom color schemes\n- **🔄 Live Configuration Reload** - Hot reload with file watching capabilities\n- **⏲️ Enhanced Timeout Controls** - Comprehensive validation with contextual bounds checking\n- **🏷️ Label Customization** - Modify all display text and formats via TOML\n- **😊 Emoji Customization** - Personalize status indicators\n- **✅ Configuration Validation** - Built-in testing with auto-fix suggestions\n\n---\n\n## 🧠 **Ultra-Comprehensive Intelligent Caching System**\n\nThe statusline features a **revolutionary universal caching system** that optimizes ALL external operations - not just API calls. This comprehensive system achieves **70-90% reduction** in external command execution while maintaining real-time responsiveness for all operations.\n\n### 🎯 **Universal Operation Caching**\n\n#### **🔍 Command Existence Checks** - Session-Wide Caching\n| Operation | Before | After | Reduction |\n|-----------|--------|-------|----------|\n| `command -v git` | Every execution | **Session-wide cache** | **🚀 100%** |\n| `command -v claude` | Every execution | **Session-wide cache** | **🚀 100%** |\n| `command -v jq` | Multiple calls per execution | **Session-wide cache** | **🚀 100%** |\n| `command -v bunx` | Multiple calls per execution | **Session-wide cache** | **🚀 100%** |\n\n#### **🔧 Git Operations** - Intelligent Duration-Based Caching\n| Operation | Before | Cache Duration | Reduction |\n|-----------|--------|---------------|----------|\n| `is_git_repository()` | Every call | **30 seconds** | **🚀 95%+** |\n| `get_git_branch()` | Every call | **10 seconds** | **🚀 90%+** |\n| `get_git_status()` | Every call | **5 seconds** | **🚀 80%+** |\n| `git config --get` | Every call | **1 hour** | **🚀 98%+** |\n| `git submodule status` | Every call | **5 minutes** | **🚀 95%+** |\n\n#### **🌐 External Commands** - Enhanced Caching\n| Command | Before | Cache Duration | Reduction |\n|---------|--------|---------------|----------|\n| `claude --version` | 1 hour | **15 minutes** | **🚀 83%** |\n| `claude mcp list` | 30 seconds | **2 minutes** | **🚀 75%** |\n\n#### **🖥️ System Information** - Permanent Caching\n| Operation | Before | After | Reduction |\n|-----------|--------|-------|----------|\n| `uname -s` (OS Type) | Every call | **Session-wide cache** | **🚀 100%** |\n| `uname -m` (Architecture) | Every call | **Session-wide cache** | **🚀 100%** |\n| `pwd` results | Every call | **5 seconds per directory** | **🚀 80%+** |\n\n### 🚀 **Universal Startup Detection**\n\nThe system intelligently detects when Claude Code starts for the first time and forces a complete refresh of ALL cached operations. Subsequent statusline calls use the optimized cache durations for maximum performance.\n\n```bash\n# First startup: Forces refresh of ALL operations\n[INFO] Universal cache module initialized\n[INFO] Cache instance ID: 1001\n[INFO] First startup detected for cache instance 1001\n[INFO] Force refresh triggered for cache: cmd_exists_git\n[INFO] Force refresh triggered for cache: git_is_repo\n[INFO] Force refresh triggered for cache: claude_version\n\n# Subsequent calls: Smart caching across all operations\n[INFO] Using cached result: cmd_exists_git          # Session-wide cache\n[INFO] Using cached result: git_branch_main         # 10-second cache\n[INFO] Using cached result: claude_mcp_list        # 2-minute cache\n[INFO] Using cached result: external_claude_version # 6-hour cache\n```\n\n### 🏆 **Overall Performance Impact**\n\n**Revolutionary Results:**\n- **70-90% reduction** in total external command execution\n- **Sub-50ms statusline responses** (from 200-500ms)\n- **100% reduction** in command existence checks after first execution\n- **95%+ reduction** in git operations through intelligent caching\n- **Dramatically improved battery life** on laptops\n- **Consistent performance** regardless of system speed or network conditions\n\n**Before vs After:**\n```bash\n# Before: Every statusline call\n✗ command -v git        # Expensive PATH lookup\n✗ command -v claude      # Expensive PATH lookup  \n✗ command -v jq          # Expensive PATH lookup\n✗ git rev-parse --is-inside-work-tree  # File system check\n✗ git branch             # Git command execution\n✗ claude --version       # External command\n✗ claude mcp list        # Network-dependent command\n\n# After: Intelligent caching\n✓ Cached results used for 70-90% of operations\n✓ Only refresh when actually needed\n✓ Multi-instance safe with no race conditions\n```\n\n### 🔒 **Multi-Instance Race Protection**\n\nWhen running multiple Claude Code instances simultaneously, the system prevents race conditions with:\n\n- **🏷️ Instance-Specific Markers**: Each Claude Code instance gets its own session marker\n  - `CLAUDE_INSTANCE_ID=DEV_001` → `/tmp/.claude_statusline_session_DEV_001`\n  - `CLAUDE_INSTANCE_ID=PROD_002` → `/tmp/.claude_statusline_session_PROD_002`\n\n- **🔐 Enhanced Locking**: Cache files protected with:\n  - Atomic writes (temp file → rename)\n  - Retry logic with random backoff\n  - JSON integrity validation\n  - Orphaned lock cleanup\n\n### 🛠️ **Cache Management**\n\nAll cache files are stored in `/tmp/.claude_statusline_cache/` with automatic cleanup:\n\n```bash\n# Universal cache directory structure\n/tmp/.claude_statusline_cache/\n├── cmd_exists_git_12345.cache         # Command existence (session-wide)\n├── cmd_exists_claude_12345.cache      # Command existence (session-wide)\n├── git_is_repo_path_hash_12345.cache  # Git repository check (30s cache)\n├── git_branch_repo_hash_12345.cache   # Git branch name (10s cache)\n├── git_status_repo_hash_12345.cache   # Git status (5s cache)\n├── external_claude_version_12345.cache # Claude version (6h cache)\n├── external_claude_mcp_list_12345.cache # MCP server list (2m cache)\n├── system_os_shared.cache             # OS type (permanent)\n└── system_arch_shared.cache           # Architecture (permanent)\n```\n\n- **🧹 Automatic Cleanup**: Old cache files and dead process locks removed\n- **🔍 Integrity Validation**: Corrupted cache files automatically regenerated\n- **♾️ Graceful Degradation**: Falls back to existing cache during high contention\n\n### 📋 **Cache File Management**\n\n**Intelligent Organization:**\n- **Instance-specific** cache files prevent cross-contamination\n- **Shared system info** cached once for all instances\n- **Automatic cleanup** of old and orphaned cache files\n- **Path-based hashing** ensures unique cache keys per directory\n\n**Cache File Types:**\n- **Session-wide**: Command existence, system info (never expire during session)\n- **Long-term**: Version info, configuration (hours)\n- **Medium-term**: Git repository data, MCP servers (minutes)\n- **Short-term**: Git status, current directory (seconds)\n\n### 🔧 **Advanced Cache Control**\n\n**Environment Variables:**\n```bash\n# Control cache instance ID\nCACHE_INSTANCE_ID=MY_DEV_SESSION ./statusline.sh\n\n# Debug comprehensive caching behavior\nSTATUSLINE_DEBUG_MODE=true ./statusline.sh\n\n# Monitor cache performance\n./statusline.sh --cache-stats  # View cache statistics\n```\n\n**Cache Management Commands:**\n```bash\n# Clear all cache files\nrm -rf /tmp/.claude_statusline_cache/\n\n# View cache files created\nls -la /tmp/.claude_statusline_cache/*.cache\n\n# Monitor cache efficiency\nSTATUSLINE_DEBUG_MODE=true ./statusline.sh 2\u003e\u00261 | grep \"Using cached\"\n```\n\n### 🎆 **Revolutionary Performance Results**\n\nThe ultra-comprehensive caching system transforms statusline performance:\n\n- **🚀 70-90% reduction** in external command execution\n- **⚡ Sub-50ms responses** (from 200-500ms)\n- **🔋 Zero command existence lookups** after first execution\n- **🛡️ Bulletproof multi-instance** operation with no race conditions\n- **🔋 Universal optimization** covering ALL external operations\n\nThis system automatically adapts to your usage patterns while maintaining the responsiveness you expect from a real-time statusline.\n\nThe caching system automatically adapts to your usage patterns while maintaining the responsiveness you expect from a real-time statusline.\n\n---\n\n## 🎨 Theme Gallery\n\nTransform your terminal aesthetic with our carefully crafted theme collection. Each theme is optimized for readability and visual appeal across different terminal environments.\n\n### 🌙 Catppuccin Mocha Theme\n\nRich, warm colors inspired by the beloved [Catppuccin](https://catppuccin.com/) palette. Perfect for dark mode enthusiasts.\n\n![Catppuccin Mocha Theme](assets/screenshots/catppuccin-mocha-theme.png)\n\n**TOML Configuration (Recommended):**\n```toml\n# In your Config.toml file\ntheme.name = \"catppuccin\"\n```\n\n**Environment Override:**\n```bash\n# Temporary theme change\nENV_CONFIG_THEME=catppuccin ~/.claude/statusline.sh\n```\n\n**CLI Generation:**\n```bash\n# Generate Config.toml with catppuccin theme\n~/.claude/statusline.sh --generate-config\n# Then edit ~/.claude/statusline/Config.toml to set theme.name = \"catppuccin\"\n```\n\n### 🌿 Garden Theme  \n\nSoft, pastel colors that create a gentle and soothing terminal environment. Ideal for extended coding sessions.\n\n![Garden Theme](assets/screenshots/garden-theme.png)\n\n**TOML Configuration (Recommended):**\n```toml\n# In your Config.toml file\ntheme.name = \"garden\"\n```\n\n**Environment Override:**\n```bash\n# Temporary theme change\nENV_CONFIG_THEME=garden ~/.claude/statusline.sh\n```\n\n### ⚡ Classic Theme\n\nTraditional terminal colors with modern polish. ANSI-compatible and universally readable.\n\n![Classic Theme](assets/screenshots/classic-theme.png)\n\n**TOML Configuration (Recommended):**\n```toml\n# In your Config.toml file\ntheme.name = \"classic\"\n```\n\n**Environment Override:**\n```bash\n# Temporary theme change\nENV_CONFIG_THEME=classic ~/.claude/statusline.sh\n```\n\n### 🎨 Custom Theme\n\nComplete creative control with full RGB/256-color/ANSI color customization capabilities.\n\n**TOML Configuration (Recommended):**\n```toml\n# In your Config.toml file\ntheme.name = \"custom\"\n\n# Define your custom color palette\ncolors.basic.red = \"\\\\033[38;2;255;182;193m\"    # Soft pink\ncolors.basic.blue = \"\\\\033[38;2;173;216;230m\"   # Light blue\ncolors.basic.green = \"\\\\033[38;2;144;238;144m\"  # Light green\ncolors.basic.yellow = \"\\\\033[38;2;255;165;0m\"   # Orange\ncolors.basic.magenta = \"\\\\033[38;2;221;160;221m\" # Plum\ncolors.basic.cyan = \"\\\\033[38;2;175;238;238m\"    # Pale turquoise\n\ncolors.extended.orange = \"\\\\033[38;2;255;140;0m\"\ncolors.extended.light_gray = \"\\\\033[38;2;211;211;211m\"\ncolors.extended.purple = \"\\\\033[38;2;147;112;219m\"\n```\n\n**Advanced Custom Configuration:**\n```bash\n# Generate base config then customize\n~/.claude/statusline.sh --generate-config MyTheme.toml\n# Edit MyTheme.toml with your custom colors\n~/.claude/statusline.sh --test-config MyTheme.toml\n```\n\n---\n\n## 📸 Screenshot Showcase\n\n### Git Status Monitoring\n\n![Git Clean Status](assets/screenshots/git-info-clean.png)\n\nClean repository with detailed branch and status information.\n\n---\n\n## 🚀 Advanced Setup\n\nFor users who want additional installation options, development features, or specific configuration control.\n\n### 📋 Prerequisites\n\nChoose your platform and install the required dependencies:\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e🍎 macOS\u003c/strong\u003e\u003c/summary\u003e\n\n```bash\n# Install dependencies via Homebrew\nbrew install jq coreutils\n\n# Cost tracking is 100% native - no external tools needed\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e🐧 Linux (Ubuntu/Debian)\u003c/strong\u003e\u003c/summary\u003e\n\n```bash\n# Install required dependencies\nsudo apt update \u0026\u0026 sudo apt install jq\n\n# Cost tracking is 100% native - no external tools needed\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e🪟 Windows (WSL)\u003c/strong\u003e\u003c/summary\u003e\n\n```bash\n# Install required dependencies\nsudo apt update \u0026\u0026 sudo apt install jq\n\n# Cost tracking is 100% native - no external tools needed\n```\n\u003c/details\u003e\n\n### 📦 Installation Methods\n\n#### Method 1: Revolutionary 3-Tier Download System (Recommended) 🚀\n\nOur breakthrough v2.9.0 installer **eliminates GitHub rate limits forever** with intelligent 3-tier architecture and provides **100% download guarantee**:\n\n##### 🎯 **Choose Your Experience Level:**\n```bash\n# 📦 PRODUCTION (Recommended for Most Users)\ncurl -sSfL https://raw.githubusercontent.com/rz1989s/claude-code-statusline/main/install.sh | bash\n\n# 🛠️ DEVELOPMENT (Stable Development Features)\ncurl -sSfL https://raw.githubusercontent.com/rz1989s/claude-code-statusline/dev/install.sh | bash -s -- --branch=dev\n\n# 🚀 DEV6 (Current Development - Settings.json Enhancement)\ncurl -sSfL https://raw.githubusercontent.com/rz1989s/claude-code-statusline/dev6/install.sh | bash -s -- --branch=dev6\ncurl -sSfL https://raw.githubusercontent.com/rz1989s/claude-code-statusline/dev6/install.sh | bash -s -- --branch=dev6 --preserve-statusline\n\n# 🌙 NIGHTLY (⚠️ Experimental - Advanced Users Only)\ncurl -sSfL https://raw.githubusercontent.com/rz1989s/claude-code-statusline/nightly/install.sh | bash -s -- --branch=nightly\n```\n\n**🔍 Branch Descriptions:**\n- **📦 main**: Stable releases (v2.9.0) - Perfect for production use\n- **🛠️ dev**: Stable development features - Early access to tested improvements\n- **🚀 dev6**: Enhanced settings.json handling with unified backup strategy and `--preserve-statusline` option\n- **🌙 nightly**: Bleeding-edge experimental features (v2.9.0-nightly-YYYYMMDD) - Community testing platform\n\n⚠️ **Nightly Warning**: Use only if you want access to experimental features before they become stable. Perfect for contributors and power users who want to help test upcoming improvements.\n\n##### 🚀 **Enhanced Installation Options:**\n```bash\n# Enhanced dependency analysis\ncurl -sSfL https://raw.githubusercontent.com/rz1989s/claude-code-statusline/main/install.sh | bash -s -- --check-all-deps\n\n# Interactive installation menu\ncurl -sSfL https://raw.githubusercontent.com/rz1989s/claude-code-statusline/main/install.sh | bash -s -- --interactive\n\n# Full analysis with user menu\ncurl -sSfL https://raw.githubusercontent.com/rz1989s/claude-code-statusline/main/install.sh | bash -s -- --check-all-deps --interactive\n\n# Skip settings.json configuration (dev6 feature)\ncurl -sSfL https://raw.githubusercontent.com/rz1989s/claude-code-statusline/dev6/install.sh | bash -s -- --branch=dev6 --preserve-statusline\n```\n\n#### Method 2: Homebrew (macOS)\n\n```bash\n# Add the tap and install\nbrew tap rz1989s/tap\nbrew install claude-code-statusline\n\n# Verify installation\nclaude-statusline --help\n```\n\n\u003e **Note**: The curl installer is still recommended for full automatic setup. Homebrew provides the formula but requires manual settings.json configuration.\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e🚀 Revolutionary 3-Tier Download System Features\u003c/strong\u003e\u003c/summary\u003e\n\n**🎯 3-Tier Architecture (v2.9.0):**\n- **Tier 1: Direct Raw URLs** → Unlimited requests, no API usage, fastest method (99% success rate)\n- **Tier 2: GitHub API Fallback** → Optional token support (5,000/hour vs 60/hour)  \n- **Tier 3: Comprehensive Retry** → Exponential backoff with intelligent verification\n\n**🛡️ 100% Download Guarantee:**\n- Either all modules download successfully or clear failure with troubleshooting\n- Zero intervention required for normal installations\n- Enhanced error handling with actionable guidance\n\n**⚡ Smart System Detection:**\n- Automatically detects your OS and package manager (brew, apt, yum, dnf, pacman)\n- Provides platform-specific installation commands\n\n**📊 Comprehensive Dependency Analysis:**\n- `curl` + `jq` → Core installation and configuration\n- 100% native → No external dependencies for cost tracking  \n- `bc` → Precise cost calculations\n- `python3` → Advanced TOML features and date parsing\n- `timeout/gtimeout` → Network operation protection\n\n**User-Friendly Options:**\n- **Install now, upgrade later** - Get 67-100% functionality immediately\n- **Show commands only** - Copy-paste exact commands for your system\n- **Exit to install manually** - For users who prefer full control\n\n**No Package Manager? No Problem:**\n- Homebrew installation guidance for macOS users\n- Manual installation instructions for restricted environments\n\n\u003c/details\u003e\n\n**Quick Download \u0026 Inspect:**\n```bash\n# Download and inspect before running\ncurl -fsSL https://raw.githubusercontent.com/rz1989s/claude-code-statusline/main/install.sh -o install.sh\nchmod +x install.sh\n\n# See all available options\n./install.sh --help\n\n# Run with your preferred mode\n./install.sh --check-all-deps --interactive\n```\n\n#### Method 2: GNU Stow Integration\n\nPerfect for dotfiles management with [GNU Stow](https://www.gnu.org/software/stow/):\n\n```bash\n# Place in your dotfiles structure\nmkdir -p ~/.dotfiles/claude/.claude/\nmkdir -p ~/.dotfiles/claude/.claude/lib/\n\n# Download main script and all modules\ncurl -fsSL https://raw.githubusercontent.com/rz1989s/claude-code-statusline/main/statusline.sh -o ~/.dotfiles/claude/.claude/statusline.sh\nchmod +x ~/.dotfiles/claude/.claude/statusline.sh\n\ncurl -fsSL https://raw.githubusercontent.com/rz1989s/claude-code-statusline/main/lib/core.sh -o ~/.dotfiles/claude/.claude/lib/core.sh\ncurl -fsSL https://raw.githubusercontent.com/rz1989s/claude-code-statusline/main/lib/security.sh -o ~/.dotfiles/claude/.claude/lib/security.sh\ncurl -fsSL https://raw.githubusercontent.com/rz1989s/claude-code-statusline/main/lib/config.sh -o ~/.dotfiles/claude/.claude/lib/config.sh\ncurl -fsSL https://raw.githubusercontent.com/rz1989s/claude-code-statusline/main/lib/themes.sh -o ~/.dotfiles/claude/.claude/lib/themes.sh\ncurl -fsSL https://raw.githubusercontent.com/rz1989s/claude-code-statusline/main/lib/git.sh -o ~/.dotfiles/claude/.claude/lib/git.sh\ncurl -fsSL https://raw.githubusercontent.com/rz1989s/claude-code-statusline/main/lib/mcp.sh -o ~/.dotfiles/claude/.claude/lib/mcp.sh\ncurl -fsSL https://raw.githubusercontent.com/rz1989s/claude-code-statusline/main/lib/cost.sh -o ~/.dotfiles/claude/.claude/lib/cost.sh\ncurl -fsSL https://raw.githubusercontent.com/rz1989s/claude-code-statusline/main/lib/display.sh -o ~/.dotfiles/claude/.claude/lib/display.sh\n\n# Deploy with Stow\ncd ~/.dotfiles \u0026\u0026 stow claude\n\n# Configure Claude Code (manual JSON editing)\n# Add to ~/.claude/settings.json:\n# \"statusLine\": {\"type\": \"command\", \"command\": \"bash ~/.claude/statusline.sh\"}\n```\n\n#### Method 3: Manual Installation\n\n```bash\n# Create Claude directory if it doesn't exist\nmkdir -p ~/.claude/\n\n# Download the main orchestrator script\ncurl -L https://raw.githubusercontent.com/rz1989s/claude-code-statusline/main/statusline.sh -o ~/.claude/statusline.sh\nchmod +x ~/.claude/statusline.sh\n\n# Create lib directory and download all modules\nmkdir -p ~/.claude/lib/\ncurl -L https://raw.githubusercontent.com/rz1989s/claude-code-statusline/main/lib/core.sh -o ~/.claude/lib/core.sh\ncurl -L https://raw.githubusercontent.com/rz1989s/claude-code-statusline/main/lib/security.sh -o ~/.claude/lib/security.sh\ncurl -L https://raw.githubusercontent.com/rz1989s/claude-code-statusline/main/lib/config.sh -o ~/.claude/lib/config.sh\ncurl -L https://raw.githubusercontent.com/rz1989s/claude-code-statusline/main/lib/themes.sh -o ~/.claude/lib/themes.sh\ncurl -L https://raw.githubusercontent.com/rz1989s/claude-code-statusline/main/lib/git.sh -o ~/.claude/lib/git.sh\ncurl -L https://raw.githubusercontent.com/rz1989s/claude-code-statusline/main/lib/mcp.sh -o ~/.claude/lib/mcp.sh\ncurl -L https://raw.githubusercontent.com/rz1989s/claude-code-statusline/main/lib/cost.sh -o ~/.claude/lib/cost.sh\ncurl -L https://raw.githubusercontent.com/rz1989s/claude-code-statusline/main/lib/display.sh -o ~/.claude/lib/display.sh\n\n# Configure Claude Code (manual JSON editing)\n# Add to ~/.claude/settings.json:\n# \"statusLine\": {\"type\": \"command\", \"command\": \"bash ~/.claude/statusline.sh\"}\n```\n\n\u003e 💡 **Why use the Enhanced Installer?** \n\u003e - **Smart dependency analysis** - Know exactly what features you'll get\n\u003e - **Platform-aware guidance** - Tailored commands for your system  \n\u003e - **Zero manual JSON editing** - Automatic settings.json configuration\n\u003e - **User choice** - Install now or install dependencies first\n\u003e - **Backward compatible** - Existing workflow unchanged\n\n### ✅ Verification\n\nTest your installation:\n\n```bash\n# Check if the statusline script and lib directory are present\nls -la ~/.claude/statusline.sh ~/.claude/lib/\n\n# Verify Claude Code configuration (check settings.json)\ncat ~/.claude/settings.json | jq '.statusLine'\n\n# Test the statusline directly\n~/.claude/statusline.sh --help\n```\n\n### 🎨 **Configuration Setup (TOML System)**\n\n**Skip this step if you want to use defaults** - the statusline works immediately with beautiful built-in themes!\n\n#### Generate Your Configuration File (Recommended)\n\n```bash\n# Navigate to your preferred location\ncd ~/  # or any project directory\n\n# Generate Config.toml with current settings\n~/.claude/statusline.sh --generate-config\n\n# Customize your configuration\nvim ~/.claude/statusline/Config.toml\n\n# Test your new configuration  \n~/.claude/statusline.sh --test-config\n```\n\n#### Quick Theme Change\n\n```bash\n# Change theme temporarily (no file needed)\nENV_CONFIG_THEME=garden ~/.claude/statusline.sh\n\n# Or create a simple config file\ncat \u003e ~/.claude/statusline/Config.toml \u003c\u003c 'EOF'\ntheme.name = \"catppuccin\"\n\nfeatures.show_commits = true\nfeatures.show_cost_tracking = true\nEOF\n\n# Test your theme\n~/.claude/statusline.sh --test-config\n```\n\n#### 🎯 **Single Source Quick Start (v2.9.0)**\n\n**Edit your comprehensive Config.toml directly - ALL settings included:**\n\n```bash\n# Open your comprehensive configuration file (227 settings pre-filled!)\nnano ~/.claude/statusline/Config.toml\n\n# OR use your preferred editor\ncode ~/.claude/statusline/Config.toml\nvim ~/.claude/statusline/Config.toml\n\n# Edit any settings you want:\n# - Change display.lines = 5 to any number 1-9\n# - Edit display.line1.components array\n# - Modify theme.name = \"catppuccin\" to \"garden\" or \"classic\"\n# - Update any of the 227 settings!\n\n# Test your configuration instantly\n~/.claude/statusline.sh\n```\n\n**Quick Component Arrangement Testing:**\n```bash\n# Test different line counts instantly\nENV_CONFIG_DISPLAY_LINES=2 ~/.claude/statusline.sh  # Minimal 2-line\nENV_CONFIG_DISPLAY_LINES=5 ~/.claude/statusline.sh  # Standard 5-line  \nENV_CONFIG_DISPLAY_LINES=7 ~/.claude/statusline.sh  # Comprehensive 7-line\n\n# Custom component arrangement on-the-fly\nENV_CONFIG_LINE1_COMPONENTS=\"mcp_status,prayer_times\" \\\nENV_CONFIG_LINE2_COMPONENTS=\"repo_info,model_info\" \\\n~/.claude/statusline.sh\n```\n\n#### Configuration Location\n\nYour configuration is stored in a single, consistent location:\n- **`~/.claude/statusline/Config.toml`** - Your configuration file (automatically created during installation)\n\n\u003e 💡 **Pro Tip**: Start with `~/.claude/statusline.sh --generate-config` to create your base configuration, then customize from there!\n\n### 🚀 **Ready to Use!**\n\nStart a new Claude Code session to see your enhanced statusline in action! Your configuration will be automatically detected and applied.\n\n---\n\n## 📁 Single Source Configuration (v2.9.0)\n\nEdit your **ONE comprehensive Config.toml** file to create any layout you want! No more confusion from 13 different example files. Bismillah!\n\n### 🎯 **Edit ONE File - All Layouts Possible**\n\n**Revolutionary Single Source System** - All 227 settings in ONE place:\n\n#### **Edit Your Config.toml Directly**\n```bash\n# Open your comprehensive configuration file (ALL settings included!)\nnano ~/.claude/statusline/Config.toml\n\n# OR use your favorite editor\ncode ~/.claude/statusline/Config.toml\nvim ~/.claude/statusline/Config.toml\n```\n\n#### **Quick Layout Changes (Environment Overrides)**\n```bash\n# Ultra-Minimal (1-line) - Just the essentials\nENV_CONFIG_DISPLAY_LINES=1 \\\nENV_CONFIG_LINE1_COMPONENTS=\"repo_info,model_info\" ./statusline.sh\n\n# Essential Compact (3-line) - Clean and focused\nENV_CONFIG_DISPLAY_LINES=3 \\\nENV_CONFIG_LINE1_COMPONENTS=\"repo_info,commits,version_info\" \\\nENV_CONFIG_LINE2_COMPONENTS=\"model_info,cost_repo,cost_live\" \\\nENV_CONFIG_LINE3_COMPONENTS=\"mcp_status\" ./statusline.sh\n\n# Standard Familiar (5-line) - Default comprehensive layout\nENV_CONFIG_DISPLAY_LINES=5 \\\nENV_CONFIG_LINE1_COMPONENTS=\"repo_info,commits,submodules,version_info,time_display\" \\\nENV_CONFIG_LINE2_COMPONENTS=\"model_info,cost_repo,cost_monthly,cost_live\" \\\nENV_CONFIG_LINE3_COMPONENTS=\"mcp_status\" \\\nENV_CONFIG_LINE4_COMPONENTS=\"reset_timer\" \\\nENV_CONFIG_LINE5_COMPONENTS=\"prayer_times\" ./statusline.sh\n\n# Atomic Components (separate git data)\nENV_CONFIG_LINE1_COMPONENTS=\"repo_info,commits,submodules,version_info\" \\\nENV_CONFIG_LINE2_COMPONENTS=\"model_info,cost_monthly,cost_weekly,cost_daily\" ./statusline.sh\n```\n\n#### **Benefits of Single Source Approach (v2.9.0)**\n\n- ✅ **No More Hunting** - All 227 settings in ONE file, just edit values\n- ✅ **Zero Confusion** - No need to choose from 13 different config files  \n- ✅ **Complete Control** - Edit display.lines, components, themes, everything\n- ✅ **User-Friendly** - Parameters pre-filled with sensible defaults\n- ✅ **Maintainable** - Single source of truth eliminates redundancy\n- ✅ **Environment Overrides** - Still works for testing: `ENV_CONFIG_THEME=garden ./statusline.sh`\n\n#### **Creative Custom (6-line)**\n```bash\n# Demonstrates flexible component reordering and custom arrangements\ncp ~/.claude/statusline/examples/Config.modular-custom.toml ~/.claude/statusline/Config.toml\n```\n- **Components**: MCP status first, prayer times second, creative mixing\n- **Layout**: Shows complete flexibility of modular system\n- **Best for**: Users who want personalized arrangements\n\n### 📋 **Quick Test Any Example**\n\n```bash\n# Test any modular example without copying\n./statusline.sh --config examples/Config.modular-compact.toml\n\n# Compare different layouts instantly\n./statusline.sh --config examples/Config.modular-minimal.toml\n./statusline.sh --config examples/Config.modular-comprehensive.toml\n\n# Use environment variables for instant testing\nENV_CONFIG_DISPLAY_LINES=3 \\\nENV_CONFIG_LINE1_COMPONENTS=\"repo_info,git_stats\" \\\nENV_CONFIG_LINE2_COMPONENTS=\"model_info,cost_repo\" \\\nENV_CONFIG_LINE3_COMPONENTS=\"mcp_status\" \\\n./statusline.sh\n```\n\n### 🎯 **Legacy Configuration Examples**\n\nTraditional configuration files for specific use cases:\n\n```bash\n# Base configuration template\ncp examples/Config.base.toml Config.toml\n\n# Advanced features showcase  \ncp examples/Config.advanced.toml Config.toml\n\n# Islamic prayer times focused\ncp examples/Config.prayer.toml Config.toml\n\n# Professional work environment (in sample-configs/)\ncp examples/sample-configs/work-profile.toml Config.toml\n\n# Personal projects setup (in sample-configs/)\ncp examples/sample-configs/personal-profile.toml Config.toml\n\n# Power developer setup (in sample-configs/)\ncp examples/sample-configs/developer-config.toml Config.toml\n\n# Performance-optimized minimal setup (in sample-configs/)\ncp examples/sample-configs/minimal-config.toml Config.toml\n```\n\n\u003e 💡 **Pro Tip**: Start with a modular example closest to your needs, then customize the `display.lineN.components` arrays to create your perfect layout!\n\n---\n\n## ⚙️ Configuration\n\nTransform your statusline with the **revolutionary single source configuration system**. ONE comprehensive Config.toml file with all 227 settings - no more hunting for parameter names!\n\n## 🚀 **Single Source Configuration (v2.9.0)**\n\n### Ultra-Simple Setup ✨\n\n```bash\n# 1. Install (creates comprehensive Config.toml automatically)\ncurl -sSfL https://raw.githubusercontent.com/rz1989s/claude-code-statusline/main/install.sh | bash\n\n# 2. Edit your comprehensive Config.toml (ALL 227 settings included!)\nnano ~/.claude/statusline/Config.toml\n\n# 3. Start using your enhanced statusline!\n~/.claude/statusline.sh\n```\n\n### Simplified Configuration Order (v2.9.0)\n\nThe statusline now uses a **streamlined single source approach**:\n\n1. **Environment variables** (`ENV_CONFIG_*`) - Temporary overrides for testing\n2. **`~/.claude/statusline/Config.toml`** - Your comprehensive configuration file (227 settings)\n3. **Auto-regeneration** - If missing, copied from examples/Config.toml template\n\n**🎯 No More Configuration Hunting!**\n- ✅ All 227 settings pre-filled in Config.toml\n- ✅ Just edit values, don't search for parameter names  \n- ✅ No hardcoded defaults in code\n- ✅ No jq fallbacks to confuse you\n\n## 📋 **Comprehensive TOML Configuration Structure (v2.9.0)**\n\n### All 227 Settings in ONE File! 🎯\n\n```toml\n# === THEME CONFIGURATION ===\ntheme.name = \"catppuccin\"  # Options: classic, garden, catppuccin, custom\n\n# === MODULAR DISPLAY CONFIGURATION ===\ndisplay.lines = 5  # Number of lines (1-9)\ndisplay.line1.components = [\"repo_info\", \"commits\", \"submodules\", \"version_info\", \"time_display\"]\ndisplay.line1.separator = \" │ \"\ndisplay.line1.show_when_empty = true\n\n# === FEATURE TOGGLES ===\nfeatures.show_commits = true\nfeatures.show_version = true\nfeatures.show_mcp_status = true\nfeatures.show_cost_tracking = true\n\n# === DISPLAY LABELS ===\nlabels.commits = \"Commits:\"\nlabels.repo = \"REPO\"\nlabels.monthly = \"30DAY\"\nlabels.weekly = \"7DAY\"\n\n# === TIMEOUTS \u0026 PERFORMANCE ===\n# Enhanced validation with contextual bounds checking (v1.2+)\ntimeouts.mcp = \"10s\"      # 1s-60s recommended, optimal: 3s-15s\ntimeouts.version = \"2s\"   # 1s-10s recommended, optimal: 1s-3s\n\n# === CUSTOMIZATION ===\nemojis.opus = \"🧠\"\nemojis.haiku = \"⚡\"\nemojis.sonnet = \"🎵\"\nemojis.clean_status = \"✅\"\n\nlabels.commits = \"Commits:\"\nlabels.repo = \"REPO\"\nlabels.mcp = \"MCP\"\n```\n\n### Advanced Custom Colors\n\n```toml\n# === CUSTOM THEME COLORS ===\ntheme.name = \"custom\"\n\ncolors.basic.red = \"\\\\033[31m\"\ncolors.basic.blue = \"\\\\033[34m\"\ncolors.basic.green = \"\\\\033[32m\"\ncolors.basic.yellow = \"\\\\033[33m\"\n\ncolors.extended.orange = \"\\\\033[38;5;208m\"\ncolors.extended.light_gray = \"\\\\033[38;5;248m\"\ncolors.extended.purple = \"\\\\033[95m\"\ncolors.extended.teal = \"\\\\033[38;5;73m\"\n```\n\n## 🔧 **Rich CLI Interface**\n\n### Configuration Management Commands\n\n```bash\n# === CONFIGURATION GENERATION ===\n~/.claude/statusline.sh --generate-config              # Create Config.toml from current settings\n~/.claude/statusline.sh --generate-config MyTheme.toml # Generate custom config file\n\n# === TESTING \u0026 VALIDATION ===\n~/.claude/statusline.sh --test-config                  # Test current configuration\n~/.claude/statusline.sh --test-config MyTheme.toml     # Test specific config file\n~/.claude/statusline.sh --test-config-verbose          # Detailed testing output\n~/.claude/statusline.sh --validate-config              # Validate configuration with enhanced timeout bounds checking\n\n# === COMPARISON \u0026 ANALYSIS ===\n~/.claude/statusline.sh --compare-config               # Compare inline vs TOML settings\n```\n\n### Live Reload \u0026 Management\n\n```bash\n# === LIVE CONFIGURATION RELOAD ===\n~/.claude/statusline.sh --reload-config                # Reload configuration now\n~/.claude/statusline.sh --reload-interactive           # Interactive config management menu\n~/.claude/statusline.sh --watch-config 3               # Watch for changes every 3 seconds\n\n# === MIGRATION \u0026 BACKUP ===\n~/.claude/statusline.sh --backup-config backup-dir/    # Backup current configuration\n~/.claude/statusline.sh --restore-config backup-dir/   # Restore from backup\n```\n\n### Help \u0026 Documentation\n\n```bash\n# === HELP SYSTEM ===\n~/.claude/statusline.sh --help                         # Complete help documentation with timeout guidance\n~/.claude/statusline.sh --help config                  # Configuration-specific help\n\n# === ADDITIONAL COMMANDS ===\n~/.claude/statusline.sh                               # Run statusline with current configuration\n```\n\n\u003e 💡 **Pro Tip**: Use environment overrides for temporary configuration changes without modifying your Config.toml file.\n\n## 🌍 **Environment Variable Overrides**\n\nTemporarily override any TOML setting with environment variables:\n\n```bash\n# === TEMPORARY THEME CHANGES ===\nENV_CONFIG_THEME=garden ~/.claude/statusline.sh        # Use garden theme once\nENV_CONFIG_THEME=classic ~/.claude/statusline.sh       # Use classic theme once\n\n# === FEATURE OVERRIDES ===\nENV_CONFIG_SHOW_MCP_STATUS=false ~/.claude/statusline.sh     # Disable MCP status\nENV_CONFIG_MCP_TIMEOUT=15s ~/.claude/statusline.sh           # Increase MCP timeout (validated: 1s-60s)\n\n# === PERFECT FOR CI/CD \u0026 AUTOMATION ===\nENV_CONFIG_SHOW_COST_TRACKING=false \\\nENV_CONFIG_SHOW_RESET_INFO=false \\\nENV_CONFIG_THEME=classic \\\n~/.claude/statusline.sh\n```\n\n## 🎛️ **Configuration Examples**\n\n### 🧩 **Modular System Examples (v2.6.0)**\n\n#### Ultra-Minimal Configuration (2-line)\n```bash\n# Use the actual modular-minimal example\ncp ~/.claude/statusline/examples/Config.modular-minimal.toml ~/.claude/statusline/Config.toml\n```\n\n**Key Features from `Config.modular-minimal.toml`:**\n```toml\n# Ultra-minimal 2-line layout\ndisplay.lines = 2\n\n# Line 1: Repository and Model Only\ndisplay.line1.components = [\"repo_info\", \"model_info\"]\n\n# Line 2: Session Cost Only  \ndisplay.line2.components = [\"cost_repo\"]\n\n# Only essentials enabled\ncomponents.repo_info.enabled = true\ncomponents.model_info.enabled = true\ncomponents.cost_repo.enabled = true\n```\n\n#### Comprehensive Configuration (7-line)\n```bash\n# Use the actual comprehensive example\ncp ~/.claude/statusline/examples/Config.modular-comprehensive.toml ~/.claude/statusline/Config.toml\n```\n\n**Key Features from `Config.modular-comprehensive.toml`:**\n```toml\n# Comprehensive 7-line layout\ndisplay.lines = 7\n\n# Line 1: Islamic Prayer Times (Priority Display)\ndisplay.line1.components = [\"prayer_times\"]\n\n# Lines 2-7: Strategic component arrangement\ndisplay.line2.components = [\"repo_info\", \"commits\", \"submodules\"]\ndisplay.line3.components = [\"model_info\", \"version_info\", \"time_display\"]\ndisplay.line4.components = [\"cost_repo\", \"cost_live\"]\ndisplay.line5.components = [\"cost_monthly\", \"cost_weekly\", \"cost_daily\"]\ndisplay.line6.components = [\"mcp_status\"]\ndisplay.line7.components = [\"reset_timer\"]\n```\n\n### 🎯 **Legacy Style Examples**\n\n#### Traditional Developer Configuration\n```bash\n# Use the advanced features example\ncp examples/Config.advanced.toml Config.toml\n\n# Or use a sample-configs developer setup\ncp examples/sample-configs/developer-config.toml Config.toml\n```\n\n**Traditional feature-based configuration:**\n```toml\n# Developer Config.toml with all features\ntheme.name = \"catppuccin\"\n\nfeatures.show_commits = true\nfeatures.show_version = true  \nfeatures.show_mcp_status = true\nfeatures.show_cost_tracking = true\nfeatures.show_reset_info = true\n\ntimeouts.mcp = \"10s\"      # Enhanced validation: 1s-60s range\ntimeouts.version = \"2s\"   # Enhanced validation: 1s-10s range  \nlabels.commits = \"Today's Commits:\"\nlabels.mcp = \"MCP Servers\"\nlabels.repo = \"Repository Cost\"\n```\n\n#### Performance-Optimized Configuration\n```bash\n# Use the minimal performance-focused setup\ncp examples/sample-configs/minimal-config.toml Config.toml\n```\n\n**Ultra-fast configuration for CI/CD and performance-critical environments:**\n```toml\n# Minimal Config.toml for maximum speed\ntheme.name = \"classic\"         # Maximum terminal compatibility\n\nfeatures.show_commits = true   # Only essential commit tracking\nfeatures.show_version = false  # Disable network calls for speed\nfeatures.show_mcp_status = false\nfeatures.show_cost_tracking = false\n\ntimeouts.mcp = \"1s\"           # Ultra-fast timeouts\ntimeouts.version = \"1s\"\nlabels.commits = \"C:\"         # Minimal labels for speed\nlabels.repo = \"R\"\nlabels.monthly = \"M\"\n\ncache.version_duration = 7200  # Extended 2-hour caching for performance\n```\n\n### Context-Specific Configuration Files\n\n```bash\n# Work environment - Professional setup\ncp examples/sample-configs/work-profile.toml Config.toml\n\n# Personal projects - Relaxed setup  \ncp examples/sample-configs/personal-profile.toml Config.toml\n\n# Power developer - Maximum information display\ncp examples/sample-configs/developer-config.toml Config.toml\n\n# Performance focus - Ultra-fast execution\ncp examples/sample-configs/minimal-config.toml Config.toml\n\n# Prayer-focused configuration\ncp examples/Config.prayer.toml Config.toml\n```\n\n\u003e 💡 **Note**: Profile-based automatic switching is planned for a future release. Currently, use different config files for different contexts.\n\n## 💡 **Migration from Inline Configuration**\n\nYour existing inline configuration **continues to work unchanged**! When you're ready:\n\n```bash\n# 1. Generate TOML from your current inline settings\n~/.claude/statusline.sh --generate-config\n\n# 2. Compare to see the differences  \n~/.claude/statusline.sh --compare-config\n\n# 3. Test the new TOML configuration\n~/.claude/statusline.sh --test-config\n\n# 4. Your inline config becomes the fallback\n# TOML configuration takes precedence automatically\n```\n\n## 🔗 **Documentation Links**\n\n- 📖 **[Complete Configuration Guide](docs/configuration.md)** - Detailed TOML configuration reference\n- 🎨 **[Themes Guide](docs/themes.md)** - Theme creation and customization with TOML\n- 🚀 **[Migration Guide](docs/migration.md)** - Step-by-step migration from inline configuration  \n- 🔧 **[CLI Reference](docs/cli-reference.md)** - Complete command-line interface documentation\n- ⏱️ **[Cache \u0026 Update Frequencies](docs/CACHE_AND_UPDATE_FREQUENCIES.md)** - Technical reference for cache durations and update intervals\n- 🐛 **[Troubleshooting](docs/troubleshooting.md)** - TOML configuration troubleshooting\n\n\u003e ⚡ **Pro Tip**: Start with `~/.claude/statusline.sh --generate-config` to create your base Config.toml, then customize from there! Changes are validated automatically.\n\n## 🔍 What Each Line Shows\n\nUnderstand every element of your enhanced statusline with this detailed breakdown:\n\n### 📁 **Line 1: Repository \u0026 Environment Info**\n\n```\n~/local-dev (main) ✅ │ Commits:0 │ ver2.1.45 │ SUB:— │ 🕐 08:22\n```\n\n- **📂 Directory**: Current working directory with elegant `~` notation\n- **🌿 Git Branch**: Active branch name with visual status indicators\n- **✅ Status**: Clean (✅) or dirty (⚠️) repository state\n- **📝 Commits**: Today's commit count for productivity tracking\n- **🔢 Version**: Claude Code version (intelligently cached for performance)\n- **📦 Submodules**: Git submodule count (shows `—` when none)\n- **🕐 Time**: Current system time for session awareness\n\n### 💰 **Line 2: Cost Tracking \u0026 Model Info**\n\n```\n🎵 Sonnet 4 │ REPO $3.87 │ 30DAY $108.81 │ 7DAY $66.48 │ DAY $9.35 │ 🔥 LIVE $6.74\n```\n\n- **🎵 Model**: Current Claude model with distinctive emoji indicator\n- **📊 REPO**: Total cost for current repository session\n- **📅 30DAY**: Monthly spending total across all sessions\n- **📈 7DAY**: Weekly spending for budget tracking\n- **🌅 DAY**: Today's accumulated costs\n- **🔥 LIVE**: Active billing block cost (when block is active)\n\n*Powered by native JSONL calculation for accurate cost monitoring*\n\n### 🔌 **Line 3: MCP Server Health**\n\n```\nMCP (3/4): upstash-context-7-mcp, supabase-mcp-server, firecrawl-mcp, sqlscan-mcp\n```\n\n- **📡 Status Count**: Connected servers vs total configured servers\n- **📋 Server List**: Individual MCP server names\n- **🟢 Connection Status**: Color-coded health indicators\n  - 🟢 **Connected**: Server is healthy and responding\n  - 🔴 **Disconnected**: Server is down or unreachable\n- **⚡ Real-time**: Updates automatically as servers come online/offline\n\n### ⏰ **Line 4: Block Reset Timer** *(Context-Aware Display)*\n\n```\nRESET at 11.00 (2h 37m left)           # Normal countdown\nRESET at 06.00 (waiting API response...)  # API calculating projection\n(Hidden when no active block)              # No active billing block\n```\n\n- **🕒 Reset Time**: When current 5-hour conversation block expires\n- **⏳ Smart States**: Three intelligent display modes:\n  - **📊 Active Countdown**: `(4h 15m left)` when projection data available\n  - **⏳ API Processing**: `(waiting API response...)` during calculation delays  \n  - **🔇 Hidden Display**: Automatically hidden when no active block\n- **🎯 Enhanced Detection**: Validates both block status and projection data\n- **📅 Context Aware**: Handles API timing issues gracefully\n\n---\n\n## 📋 System Requirements\n\n### ✅ **Platform Compatibility**\n\n**🎯 100% Cross-Platform Compatibility**: Extensively tested across all major platforms with automatic detection and adaptation.\n\n📖 **[→ See Complete Platform Matrix (PLATFORMS.md)](PLATFORMS.md)** - Detailed compatibility information, installation guides, and troubleshooting for each platform.\n\n| Platform | Version | Status | Package Manager | GPS Support |\n|----------|---------|--------|-----------------|-------------|\n| 🍎 **macOS** | 12+ (Monterey) | ✅ **Full Support** | `brew` | ✅ CoreLocationCLI |\n| 🐧 **Ubuntu** | 20.04+ LTS | ✅ **Full Support** | `apt` | ✅ geoclue2 |\n| 🐧 **Debian** | 11+ (Bullseye) | ✅ **Full Support** | `apt` | ✅ geoclue2 |\n| 🏔️ **Arch Linux** | Rolling | ✅ **Full Support** | `pacman` | ✅ geoclue2 |\n| 🎩 **Fedora** | 36+ | ✅ **Full Support** | `dnf` | ✅ geoclue2 |\n| 🏢 **RHEL/CentOS** | 8+ | ✅ **Full Support** | `dnf`/`yum` | ✅ geoclue2 |\n| 🏔️ **Alpine** | 3.16+ | ✅ **Full Support** | `apk` | ⚠️ Limited |\n| 🔺 **FreeBSD** | 13+ | ⚠️ **Partial** | `pkg` | ❌ None |\n| 🪟 **Windows WSL** | ✅ **Full Support** | `jq` | - |\n| 🪟 **Windows Native** | ❌ **Not Supported** | N/A | *Bash incompatible* |\n\n### 🛠️ **Required Dependencies**\n\n#### Core Requirements\n- **`jq`** - JSON processing and data parsing\n  - macOS: `brew install jq`\n  - Linux: `sudo apt install jq` or `sudo yum install jq`\n  - Purpose: Parse Claude Code JSON data and MCP server responses\n\n#### System Tools *(Usually Pre-installed)*\n- **`bash`** - Shell execution environment (v3.2+ with automatic upgrade to modern bash)\n- **`git`** - Version control integration\n- **`grep`**, **`sed`**, **`date`** - Text processing and utilities\n- **`timeout`** / **`gtimeout`** - Command timeout management\n\n**🚀 Revolutionary Bash Compatibility:**\n- **Runtime Detection**: Automatically finds and uses modern bash (4.0+) if available\n- **Compatibility Mode**: Falls back gracefully for old bash versions\n- **Universal Support**: Works across all system configurations without manual intervention\n\n### 🚀 **Recommended Enhancements**\n\n#### Cost Tracking\n- **100% Native** - No external tools required\n  - Cost calculation from JSONL files in `~/.claude/projects/`\n  - Purpose: Real-time cost tracking and billing information\n  - Pricing: Official Anthropic rates (Opus $5/$25, Sonnet $3/$15, Haiku $1/$5 per MTok)\n\n#### Performance Optimizations\n- **GNU Coreutils** (macOS) - Enhanced command compatibility\n  - Install: `brew install coreutils`\n  - Provides `gtimeout` and other GNU-style commands\n\n#### GPS Location Detection (Prayer Times)\n- **CoreLocationCLI** (macOS) - High-precision GPS coordinates\n  - Install: `brew install corelocationcli`\n  - Purpose: Real-time device location for accurate prayer times\n- **geoclue2** (Linux) - System location service\n  - Install: `sudo apt install geoclue-2.0-dev` or `sudo yum install geoclue2-devel`\n  - Purpose: GPS-based location detection independent of network/VPN\n\n### ⚙️ **Version Requirements**\n\n| Tool | Minimum Version | Recommended | Notes |\n|------|----------------|-------------|-------|\n| Bash | 3.2+ | 5.0+ | **Universal compatibility** - auto-detects modern bash |\n| jq | 1.5+ | 1.6+ | JSON processing performance |\n| Git | 2.0+ | 2.30+ | Modern git features |\n| Node.js | - | - | Not required (100% native) |\n\n**🎯 Bash Compatibility Revolution:**\n- **Automatic Detection**: Runtime bash detection finds the best available bash version\n- **Universal Compatibility**: Works on all Mac configurations (Apple Silicon, Intel, any package manager)\n- **Graceful Fallback**: Compatibility mode for old bash versions (3.2+) with reduced functionality\n- **Zero Configuration**: No manual shebang fixes needed - everything handled automatically\n\n### 🔧 **Quick Dependency Check**\n\nVerify your system is ready:\n\n```bash\n# Check core requirements\nbash --version \u0026\u0026 echo \"✅ Bash OK\" || echo \"❌ Bash missing\"\njq --version \u0026\u0026 echo \"✅ jq OK\" || echo \"❌ jq missing\" \ngit --version \u0026\u0026 echo \"✅ Git OK\" || echo \"❌ Git missing\"\n\n# Cost tracking is 100% native - no external tools needed\n\n# Check GPS location tools\nCoreLocationCLI --version \u0026\u0026 echo \"✅ CoreLocationCLI OK\" || echo \"⚠️ CoreLocationCLI missing (macOS: brew install corelocationcli)\"\nwhereis geoclue-2.0 \u0026\u0026 echo \"✅ geoclue2 OK\" || echo \"⚠️ geoclue2 missing (Linux: sudo apt install geoclue-2.0-dev)\"\n```\n\n## 📖 Documentation\n\n- [📦 Installation Guide](docs/installation.md) - Platform-specific setup instructions\n- [⚙️ Configuration Guide](docs/configuration.md) - Detailed customization options  \n- [🎨 Themes Guide](docs/themes.md) - Theme showcase and custom theme creation\n- [⏱️ Cache \u0026 Update Frequencies](docs/CACHE_AND_UPDATE_FREQUENCIES.md) - Technical reference for cache durations\n- [🐛 Troubleshooting](docs/troubleshooting.md) - Common issues and solutions\n\n## 🤝 Contributing\n\n**We welcome contributions from the community!** 🌟\n\nWhether you're interested in:\n- 🐛 **Bug fixes** and issue reports\n- 💡 **New features** and enhancements  \n- 🎨 **Theme creation** and design\n- 📖 **Documentation** improvements\n- 🧪 **Testing** and quality assurance\n\n**Please see our comprehensive [CONTRIBUTING.md](CONTRIBUTING.md)** for detailed guidelines on:\n- Development environment setup\n- Code standards and testing requirements  \n- Pull request process and review workflow\n- Community guidelines and project structure\n\n### 🚀 Quick Start for Contributors\n```bash\n# Fork and clone the repository\ngit clone https://github.com/YOUR-USERNAME/claude-code-statusline.git\ncd claude-code-statusline\n\n# Install dependencies and verify setup\nnpm install\nnpm test\n\n# Check our development roadmap\ncat TODOS.md\n```\n\n**Jazakallahu khairan** for helping make this project better for the Claude Code community! 🙏\n\n### 🐳 Docker Development Environment\n\nFor consistent development and testing across platforms:\n\n```bash\n# Build and run tests (Alpine - fast)\ndocker compose run test\n\n# Run tests on Ubuntu (CI parity)\ndocker compose run test-ubuntu\n\n# Development shell with mounted source\ndocker compose run dev\n\n# Run linting\ndocker compose run lint\n```\n\n**Available Docker services:**\n| Service | Description |\n|---------|-------------|\n| `dev` | Interactive bash shell with source mounted |\n| `test` | Run unit tests on Alpine |\n| `test-ubuntu` | Run unit tests on Ubuntu (matches CI) |\n| `test-all` | Run all tests (unit + integration) |\n| `lint` | Run shellcheck on main scripts |\n| `lint-all` | Run shellcheck on all lib files |\n\n**Build images manually:**\n```bash\n# Alpine (default, ~50MB)\ndocker build -t claude-statusline .\n\n# Ubuntu (CI parity, ~150MB)\ndocker build -f Dockerfile.ubuntu -t claude-statusline:ubuntu .\n```\n\n---\n\n## 📜 License\n\nThis project is licensed under the **MIT License** - see the [LICENSE](LICENSE) file for details.\n\n---\n\n## 🙏 Acknowledgments\n\nSpecial thanks to the amazing projects and communities that make this statusline possible:\n\n### 🛠️ Core Technologies\n- **[Claude Code](https://claude.ai/code)** - The revolutionary AI development tool that inspired this project\n- **[jq](https://jqlang.github.io/jq/)** - Powerful JSON processing for data parsing\n\n### 🎨 Design \u0026 Aesthetics  \n- **[Catppuccin](https://catppuccin.com/)** - Beautiful color palette that inspired our Catppuccin theme\n- **[Nerd Fonts](https://www.nerdfonts.com/)** - Icon fonts that enhance the visual experience\n- **Terminal Color Standards** - ANSI, 256-color, and RGB color support communities\n\n### 🔧 Development Tools\n- **[GNU Stow](https://www.gnu.org/software/stow/)** - Elegant dotfiles management solution\n- **[Bash](https://www.gnu.org/software/bash/)** - The shell that powers our cross-platform compatibility\n- **[Git](https://git-scm.com/)** - Version control integration and repository monitoring\n\n### 💡 Inspiration\n- **Open Source Community** - For fostering innovation and collaboration\n- **Terminal Enthusiasts** - For pushing the boundaries of command-line aesthetics\n- **Claude Code Users** - For feedback and feature requests that drive improvements\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n### 🌟 Show Your Support\n\n**Love this project? Give it a star!** ⭐\n\n[![GitHub stars](https://img.shields.io/github/stars/rz1989s/claude-code-statusline?style=social)](https://github.com/rz1989s/claude-code-statusline/stargazers)\n[![GitHub forks](https://img.shields.io/github/forks/rz1989s/claude-code-statusline?style=social)](https://github.com/rz1989s/claude-code-statusline/network/members)\n[![GitHub watchers](https://img.shields.io/github/watchers/rz1989s/claude-code-statusline?style=social)](https://github.com/rz1989s/claude-code-statusline/watchers)\n\n[![MIT License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n[![Platform Support](https://img.shields.io/badge/Platform-macOS%20%7C%20Linux%20%7C%20WSL-green.svg)](#-system-requirements)\n[![Made for Claude Code](https://img.shields.io/badge/Made%20for-Claude%20Code-9333EA.svg)](https://claude.ai/code)\n[![Shell](https://img.shields.io/badge/Shell-Bash-lightgrey.svg)]()\n\n### 💬 Connect \u0026 Support\n\n[🐛 Report Bug](https://github.com/rz1989s/claude-code-statusline/issues) • [💡 Request Feature](https://github.com/rz1989s/claude-code-statusline/issues) • [📖 Documentation](docs/) • [💬 Discussions](https://github.com/rz1989s/claude-code-statusline/discussions)\n\n**Made with ❤️ for the Claude Code community**\n\n\u003c/div\u003e","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frz1989s%2Fclaude-code-statusline","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frz1989s%2Fclaude-code-statusline","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frz1989s%2Fclaude-code-statusline/lists"}