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