{"id":34383297,"url":"https://github.com/fabioluciano/tmux-powerkit","last_synced_at":"2026-04-02T00:29:41.139Z","repository":{"id":160161983,"uuid":"635097749","full_name":"fabioluciano/tmux-powerkit","owner":"fabioluciano","description":"The Ultimate tmux Status Bar Framework","archived":false,"fork":false,"pushed_at":"2026-03-27T23:37:47.000Z","size":11512,"stargazers_count":497,"open_issues_count":2,"forks_count":83,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-03-28T05:52:05.892Z","etag":null,"topics":["tmux","tmux-framework","tmux-plugin","tmux-theme"],"latest_commit_sha":null,"homepage":"","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/fabioluciano.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"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":"2023-05-02T00:50:12.000Z","updated_at":"2026-03-27T23:37:49.000Z","dependencies_parsed_at":"2023-10-16T23:48:31.756Z","dependency_job_id":"99bec16d-421d-4fbf-9c5e-b79612dc1b69","html_url":"https://github.com/fabioluciano/tmux-powerkit","commit_stats":null,"previous_names":["fabioluciano/tmux-powerkit","fabioluciano/tmux-tokyo-night"],"tags_count":115,"template":false,"template_full_name":null,"purl":"pkg:github/fabioluciano/tmux-powerkit","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fabioluciano%2Ftmux-powerkit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fabioluciano%2Ftmux-powerkit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fabioluciano%2Ftmux-powerkit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fabioluciano%2Ftmux-powerkit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fabioluciano","download_url":"https://codeload.github.com/fabioluciano/tmux-powerkit/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fabioluciano%2Ftmux-powerkit/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31293379,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-01T21:15:39.731Z","status":"ssl_error","status_checked_at":"2026-04-01T21:15:34.046Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["tmux","tmux-framework","tmux-plugin","tmux-theme"],"created_at":"2025-12-18T17:00:26.315Z","updated_at":"2026-04-02T00:29:41.122Z","avatar_url":"https://github.com/fabioluciano.png","language":"Shell","funding_links":[],"categories":["Shell","\u003ca name=\"tools\"\u003e\u003c/a\u003eTools and session management"],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# ⚡ PowerKit\n\n![PowerKit Status Bar Preview](https://raw.githubusercontent.com/wiki/fabioluciano/tmux-powerkit/assets/images/tmux-powerkit-session-plugins-windows.png)\n\n① \u003cb\u003eSession\u003c/b\u003e – Current tmux session name with mode-aware icon (changes on prefix/copy mode)\u003cbr /\u003e\n② \u003cb\u003ePlugins\u003c/b\u003e – Modular status indicators with health-based colors (cpu, memory, git, datetime, etc.)\u003cbr /\u003e\n③ \u003cb\u003eWindows\u003c/b\u003e – Window list with index icons, names, and state indicators (active, zoomed, activity)\n\n## The Ultimate tmux Status Bar Framework\n\n45 Plugins • 43 Themes • Infinite Possibilities\n\n[![Version](https://img.shields.io/github/v/release/fabioluciano/tmux-powerkit?style=for-the-badge\u0026logo=github\u0026logoColor=white)](https://github.com/fabioluciano/tmux-powerkit/releases)\n[![License](https://img.shields.io/github/license/fabioluciano/tmux-powerkit?style=for-the-badge)](LICENSE)\n[![CI](https://img.shields.io/github/actions/workflow/status/fabioluciano/tmux-powerkit/plugin-tests.yml?branch=main\u0026style=for-the-badge\u0026label=tests\u0026logo=github-actions\u0026logoColor=white)](https://github.com/fabioluciano/tmux-powerkit/actions)\n[![Stars](https://img.shields.io/github/stars/fabioluciano/tmux-powerkit?style=for-the-badge\u0026logo=starship\u0026logoColor=white)](https://github.com/fabioluciano/tmux-powerkit/stargazers)\n\nTransform your tmux status bar into a powerful, beautiful, and intelligent command center\n\n[**Getting Started**](#-quick-start) • [**Plugins**](#-plugins) • [**Themes**](#-themes) • [**Documentation**](https://github.com/fabioluciano/tmux-powerkit/wiki)\n\n\u003c/div\u003e\n\n---\n\n## ✨ What Makes PowerKit Special?\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003ctd width=\"50%\"\u003e\n\n### 🎨 **Beautiful by Default**\n\nChoose from **43 carefully crafted themes** with **71 variants** including Catppuccin, Dracula, Monokai, Nord, Tokyo Night, and more. Every theme supports automatic color variants (light/lighter/dark/darker) for perfect contrast.\n\n### ⚡ **Blazingly Fast**\n\nSmart **multi-layer caching**, **Stale-While-Revalidate (SWR) lazy loading**, and optimized background rendering ensure minimal overhead even with dozens of plugins active. Returns stale data immediately while refreshing in background - never blocks on slow API calls or external commands.\n\n\u003c/td\u003e\n\u003ctd width=\"50%\"\u003e\n\n### 🧩 **Truly Modular**\n\n**45 production-ready plugins** covering system monitoring, development tools, productivity, media control, and more. Mix and match to create your perfect setup.\n\n### 🔧 **Extensible Architecture**\n\nContract-based plugin system with strict separation of concerns. Create your own plugins, themes, and helpers with ease.\n\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n---\n\n## 🚀 Quick Start\n\n### Installation with TPM\n\nAdd to your `~/.tmux.conf`:\n\n```bash\n# PowerKit plugin\nset -g @plugin 'fabioluciano/tmux-powerkit'\n\n# Basic configuration\nset -g @powerkit_plugins \"datetime,battery,cpu,memory,git,hostname\"\nset -g @powerkit_theme \"catppuccin\"\nset -g @powerkit_theme_variant \"mocha\"\n\n# Initialize TPM (keep at bottom)\nrun '~/.tmux/plugins/tpm/tpm'\n```\n\nThen press `prefix + I` to install.\n\n### Manual Installation\n\nFor faster download (~1.5 MB), use shallow clone:\n\n```bash\ngit clone --depth 1 https://github.com/fabioluciano/tmux-powerkit.git ~/.tmux/plugins/tmux-powerkit\n```\n\nAdd to `~/.tmux.conf`:\n\n```bash\nrun-shell ~/.tmux/plugins/tmux-powerkit/tmux-powerkit.tmux\n```\n\n\u003e See [Installation Guide](https://github.com/fabioluciano/tmux-powerkit/wiki/Installation) for more options (tarball, full clone).\n\n### Nix/NixOS\n\nAdd to `flake.nix`:\n\n```nix\n{\n  inputs.tmux-powerkit.url = \"github:fabioluciano/tmux-powerkit\";\n}\n```\n\nAdd to `configuration.nix` or `home.nix`:\n\n```nix\nprograms.tmux = {\n  enable = true;\n  plugins = [{\n    plugin = inputs.tmux-powerkit.packages.${pkgs.system}.default;\n    extraConfig = ''\n      set -g @powerkit_plugins \"datetime,battery,cpu,memory,git\"\n      set -g @powerkit_theme \"catppuccin\"\n      set -g @powerkit_theme_variant \"mocha\"\n    '';\n  }];\n};\n```\n\nFor non-flake install, add to your `configuration.nix` or `home.nix`:\n\n```nix\nlet\n  tmux-powerkit = pkgs.callPackage (pkgs.fetchFromGitHub {\n    owner = \"fabioluciano\";\n    repo = \"tmux-powerkit\";\n    rev = \"main\";  # or pin to a specific commit\n    sha256 = \"\";   # nix will provide correct hash on first build\n  } + \"/default.nix\") {};\nin {\n  programs.tmux = {\n    enable = true;\n    plugins = [ tmux-powerkit ];\n    extraConfig = ''\n      set -g @powerkit_plugins \"datetime,battery,cpu,memory,git\"\n      set -g @powerkit_theme \"catppuccin\"\n      set -g @powerkit_theme_variant \"mocha\"\n    '';\n  };\n}\n```\n\n### Your First Customization\n\n```bash\n# Choose your separator style\nset -g @powerkit_separator_style \"rounded\"  # or normal, flame, pixel, honeycomb\n\n# Enable spacing between elements\nset -g @powerkit_elements_spacing \"both\"\n\n# Customize update interval\nset -g @powerkit_status_interval \"5\"\n\n# Make it transparent\nset -g @powerkit_transparent \"true\"\n```\n\n**That's it!** Reload tmux and enjoy your new status bar.\n\n---\n\n## 🎯 Plugins\n\n### 📊 System Monitoring (13 plugins)\n\nMonitor every aspect of your system in real-time:\n\n| Plugin | Description | Highlights |\n|--------|-------------|-----------|\n| `battery` | Battery level with charge state | Shows charging status, time remaining, health indicators |\n| `cpu` | CPU usage with per-core support | Thresholds, multi-core detection, platform-specific |\n| `memory` | RAM usage and availability | Multiple formats (percentage, usage, available) |\n| `swap` | Swap memory usage | Cross-platform, threshold alerts, multiple display formats |\n| `disk` | Disk usage by mount point | Configurable thresholds, multiple drives |\n| `loadavg` | System load average | 1/5/15 minute averages, per-core normalization |\n| `temperature` | CPU temperature | macOS (osx-cpu-temp), Linux (hwmon) |\n| `fan` | Fan speed monitoring | Dell SMM, ThinkPad, generic hwmon, macOS |\n| `gpu` | GPU utilization | NVIDIA, AMD, Intel, macOS support |\n| `iops` | Disk I/O operations | Read/write operations per second |\n| `brightness` | Screen brightness | Linux only (sysfs, brightnessctl, light, xbacklight) |\n| `uptime` | System uptime | Human-readable format |\n| `hostname` | System hostname | Color-coded by environment |\n\n### 🌐 Network (7 plugins)\n\nStay connected and informed:\n\n| Plugin | Description | Features |\n|--------|-------------|----------|\n| `netspeed` | Upload/download speed | Real-time bandwidth monitoring |\n| `wifi` | WiFi SSID + signal strength | Signal quality indicators |\n| `vpn` | VPN connection status | Detects active VPN tunnels |\n| `ping` | Network latency | Configurable host, threshold alerts |\n| `external_ip` | Public IP address | Cached with configurable TTL |\n| `ssh` | SSH session indicator | Shows when connected via SSH |\n| `weather` | Weather from wttr.in | Location-based, customizable format |\n\n### 🎵 Media (7 plugins)\n\nControl your media experience:\n\n| Plugin | Description | Platform |\n|--------|-------------|----------|\n| `volume` | System volume level | macOS only |\n| `brightness` | Screen brightness | Linux only |\n| `nowplaying` | Current music track | Music.app, Spotify (macOS) |\n| `audiodevices` | Active audio output device | macOS (SwitchAudioSource) |\n| `camera` | Camera usage indicator | macOS (lsof) |\n| `microphone` | Microphone mute status | macOS (osascript) |\n| `bluetooth` | Bluetooth status + devices | macOS (blueutil), Linux (bluetoothctl) |\n\n### 💻 Development (11 plugins)\n\nSupercharge your development workflow:\n\n| Plugin | Description | Features |\n|--------|-------------|----------|\n| `git` | Git branch + status | Modified files, branch info, repo state |\n| `github` | GitHub notifications | PRs, issues, notifications (gh CLI) |\n| `gitlab` | GitLab merge requests | MRs, todos (glab CLI) |\n| `bitbucket` | Bitbucket pull requests | PR count via API |\n| `jira` | Jira assigned issues | Issue count via API |\n| `kubernetes` | K8s context + namespace | Current context and namespace |\n| `terraform` | Terraform workspace | Active workspace indicator |\n| `cloud` | Cloud provider profile | AWS/Azure/GCP active profile |\n| `cloudstatus` | Cloud service status | Service health monitoring |\n| `yadm` | yadm dotfile status | Modified/untracked dotfiles, ahead/behind counts |\n| `packages` | Pending system updates | brew, apt, yum, pacman support |\n\n### ⏰ Productivity (5 plugins)\n\nBoost your productivity:\n\n| Plugin | Description | Features |\n|--------|-------------|----------|\n| `datetime` | Date and time | 15 format presets, fully customizable |\n| `timezones` | Multiple timezones | Display multiple zones simultaneously |\n| `pomodoro` | Pomodoro timer | Work/break phases, keybindings |\n| `bitwarden` | Bitwarden vault status | Lock status, quick access |\n| `smartkey` | Custom environment variables | Display any env var or command output |\n\n### 💰 Financial (2 plugins)\n\nTrack your investments:\n\n| Plugin | Description | Source |\n|--------|-------------|--------|\n| `crypto` | Cryptocurrency prices | CoinGecko API |\n| `stocks` | Stock prices | Yahoo Finance API |\n\n---\n\n## 🎨 Themes\n\nPowerKit comes with **43 beautiful themes** and **71 variants**, each carefully designed for optimal readability and aesthetics\n\n### Popular Themes\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003ctd align=\"center\"\u003e\u003cstrong\u003eTokyo Night\u003c/strong\u003e\u003cbr/\u003enight • storm • day\u003c/td\u003e\n\u003ctd align=\"center\"\u003e\u003cstrong\u003eCatppuccin\u003c/strong\u003e\u003cbr/\u003emocha • macchiato • frappe • latte\u003c/td\u003e\n\u003ctd align=\"center\"\u003e\u003cstrong\u003eDracula\u003c/strong\u003e\u003cbr/\u003edark\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd align=\"center\"\u003e\u003cstrong\u003eNord\u003c/strong\u003e\u003cbr/\u003edark\u003c/td\u003e\n\u003ctd align=\"center\"\u003e\u003cstrong\u003eGruvbox\u003c/strong\u003e\u003cbr/\u003edark • light\u003c/td\u003e\n\u003ctd align=\"center\"\u003e\u003cstrong\u003eRose Pine\u003c/strong\u003e\u003cbr/\u003emain • moon • dawn\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd align=\"center\"\u003e\u003cstrong\u003eMaterial\u003c/strong\u003e\u003cbr/\u003edefault • ocean • palenight • lighter\u003c/td\u003e\n\u003ctd align=\"center\"\u003e\u003cstrong\u003eSolarized\u003c/strong\u003e\u003cbr/\u003edark • light\u003c/td\u003e\n\u003ctd align=\"center\"\u003e\u003cstrong\u003eGitHub\u003c/strong\u003e\u003cbr/\u003edark • light\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd align=\"center\"\u003e\u003cstrong\u003eAyu\u003c/strong\u003e\u003cbr/\u003edark • mirage • light\u003c/td\u003e\n\u003ctd align=\"center\"\u003e\u003cstrong\u003eNight Owl\u003c/strong\u003e\u003cbr/\u003edefault • light\u003c/td\u003e\n\u003ctd align=\"center\"\u003e\u003cstrong\u003eMoonlight\u003c/strong\u003e\u003cbr/\u003edefault\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\nPlus **Monokai**, **Cobalt2**, **SynthWave '84**, **Horizon**, **Iceberg**, **Snazzy**, **Spacegray**, **Molokai**, **Vesper**, **Poimandres**, **Flexoki**, **Slack**, and more!\n\n### Theme Features\n\n- ✅ **Automatic color variants** - Each base color generates 6 variants (light/lighter/lightest/dark/darker/darkest)\n- ✅ **Smart health mapping** - Plugin states automatically map to theme colors\n- ✅ **Transparent mode** - All themes support transparent backgrounds\n- ✅ **Consistent contrast** - Automated foreground color selection for perfect readability\n\n### Quick Theme Switch\n\n```bash\n# Tokyo Night - Night variant\nset -g @powerkit_theme \"tokyo-night\"\nset -g @powerkit_theme_variant \"night\"\n\n# Catppuccin - Mocha variant\nset -g @powerkit_theme \"catppuccin\"\nset -g @powerkit_theme_variant \"mocha\"\n\n# Dracula\nset -g @powerkit_theme \"dracula\"\nset -g @powerkit_theme_variant \"dark\"\n```\n\n**See all themes:** [Themes Documentation](https://github.com/fabioluciano/tmux-powerkit/wiki/Themes)\n\n---\n\n## 🎭 Separator Styles\n\nChoose from **9 beautiful separator styles** to customize your status bar appearance:\n\n| Style | Right | Left | Unicode |\n|-------|-------|------|---------|\n| **normal** |  |  | E0B0/E0B2 |\n| **rounded** |  |  | E0B4/E0B6 |\n| **slant** |  |  | E0B8/E0BA |\n| **slantup** |  |  | E0BC/E0BE |\n| **trapezoid** |  |  | E0C8/E0CA |\n| **flame** |  |  | E0C0/E0C2 |\n| **pixel** |  |  | E0C4/E0C6 |\n| **honeycomb** |  |  | E0CC/E0CD |\n| **none** | - | - | - |\n\n```bash\n# Configure separator style\nset -g @powerkit_separator_style \"rounded\"\n\n# Different style for edge separators\nset -g @powerkit_edge_separator_style \"flame\"\n\n# Add spacing between elements\nset -g @powerkit_elements_spacing \"both\"  # false, true, both, windows, plugins\n```\n\n---\n\n## ⚙️ Advanced Configuration\n\n### Plugin-Specific Options\n\nEvery plugin is highly customizable. Example with the `battery` plugin:\n\n```bash\n# Battery plugin options\nset -g @powerkit_plugin_battery_warning_threshold \"30\"\nset -g @powerkit_plugin_battery_critical_threshold \"15\"\nset -g @powerkit_plugin_battery_icon \"\"\nset -g @powerkit_plugin_battery_icon_charging \"󰂄\"\nset -g @powerkit_plugin_battery_cache_ttl \"5\"\nset -g @powerkit_plugin_battery_show_only_on_threshold \"false\"\n```\n\n### CPU Plugin with Thresholds\n\n```bash\nset -g @powerkit_plugin_cpu_warning_threshold \"70\"\nset -g @powerkit_plugin_cpu_critical_threshold \"90\"\nset -g @powerkit_plugin_cpu_show_cores \"false\"\nset -g @powerkit_plugin_cpu_icon \"\"\n```\n\n### Git Plugin\n\n```bash\nset -g @powerkit_plugin_git_icon \"\"\nset -g @powerkit_plugin_git_show_branch \"true\"\nset -g @powerkit_plugin_git_show_files \"true\"\nset -g @powerkit_plugin_git_max_length \"30\"\n```\n\n### Network Speed\n\n```bash\nset -g @powerkit_plugin_netspeed_interface \"auto\"  # or eth0, wlan0, etc.\nset -g @powerkit_plugin_netspeed_icon_up \"󰕒\"\nset -g @powerkit_plugin_netspeed_icon_down \"󰇚\"\nset -g @powerkit_plugin_netspeed_format \"both\"  # up, down, both\n```\n\n### DateTime Formats\n\nChoose from **15 preset formats** or create your own:\n\n```bash\nset -g @powerkit_plugin_datetime_format \"preset_1\"  # %Y-%m-%d %H:%M:%S\nset -g @powerkit_plugin_datetime_format \"preset_7\"  # %I:%M %p\nset -g @powerkit_plugin_datetime_format \"preset_12\" # %a %b %d\n# Or custom format\nset -g @powerkit_plugin_datetime_format \"%Y-%m-%d %A\"\n```\n\n---\n\n## 🎮 Keybindings\n\nPowerKit includes powerful interactive helpers with keybindings:\n\n```bash\n# Built-in keybindings (all customizable)\nset -g @powerkit_options_key \"C-e\"          # View all options\nset -g @powerkit_keybindings_key \"C-y\"      # View keybindings\nset -g @powerkit_theme_selector_key \"C-r\"   # Theme selector\nset -g @powerkit_cache_clear_key \"C-d\"      # Clear cache\n\n# Plugin-specific keybindings\nset -g @powerkit_plugin_bitwarden_keybinding_unlock \"C-b u\"\nset -g @powerkit_plugin_bitwarden_keybinding_lock \"C-b l\"\nset -g @powerkit_plugin_pomodoro_keybinding_start \"C-p s\"\nset -g @powerkit_plugin_pomodoro_keybinding_pause \"C-p p\"\n```\n\n### Interactive Helpers\n\nPowerKit includes several interactive helpers:\n\n- **Options Viewer** (`prefix + C-e`) - Browse all configuration options\n- **Keybindings Viewer** (`prefix + C-y`) - View all active keybindings\n- **Theme Selector** (`prefix + C-r`) - Interactively switch themes\n- **Cache Manager** (`prefix + C-d`) - Clear plugin cache\n- **Bitwarden Selector** - Quick password access\n- **Audio Device Selector** - Switch audio outputs\n\n---\n\n## 🏗️ Architecture\n\nPowerKit uses a **contract-based architecture** with strict separation of concerns:\n\n```text\n┌─────────────────────────────────────────────────────────────────┐\n│                         POWERKIT CORE                            │\n│  Lifecycle • Cache • Options • Datastore • Theme Loader         │\n└───────┬──────────────────────┬──────────────────┬───────────────┘\n        │                      │                  │\n        ▼                      ▼                  ▼\n┌──────────────┐      ┌─────────────────┐   ┌─────────────┐\n│   PLUGINS    │      │    RENDERER     │   │   THEMES    │\n├──────────────┤      ├─────────────────┤   ├─────────────┤\n│ • Data       │─────▶│ • Colors        │◀──│ • Color     │\n│ • State      │      │ • Icons         │   │   Palette   │\n│ • Health     │      │ • Separators    │   │             │\n│ • Context    │      │ • Formatting    │   │             │\n└──────────────┘      └─────────────────┘   └─────────────┘\n```\n\n### Key Principles\n\n1. **Plugins** provide data and semantics (state, health, context)\n2. **Renderer** handles all UI decisions (colors, icons, formatting)\n3. **Themes** define color palettes only\n4. **Core** orchestrates the lifecycle and manages caching\n\nThis architecture ensures:\n\n- ✅ Plugins never decide colors or formatting\n- ✅ Themes are purely declarative\n- ✅ Rendering is consistent across all plugins\n- ✅ Easy to extend without breaking existing code\n\n**Learn more:** [Architecture Documentation](https://github.com/fabioluciano/tmux-powerkit/wiki/Architecture)\n\n---\n\n## 📐 Layout Options\n\n### Single vs Double Layout\n\n```bash\n# Single line layout (default)\nset -g @powerkit_bar_layout \"single\"\n\n# Double line layout (session on top, plugins on bottom)\nset -g @powerkit_bar_layout \"double\"\n```\n\n### Element Order and Centered Layout\n\nPowerKit supports flexible element ordering with automatic centered layout:\n\n```bash\n# 2-element orders (auto-expanded with windows):\nset -g @powerkit_status_order \"session,plugins\"  # Standard: session+windows LEFT, plugins RIGHT\nset -g @powerkit_status_order \"plugins,session\"  # Inverted: plugins LEFT, windows+session RIGHT\n\n# 3-element orders enable CENTERED layout:\nset -g @powerkit_status_order \"session,windows,plugins\"  # session LEFT, windows CENTER, plugins RIGHT\nset -g @powerkit_status_order \"plugins,windows,session\"  # plugins LEFT, windows CENTER, session RIGHT\nset -g @powerkit_status_order \"session,plugins,windows\"  # session LEFT, plugins CENTER, windows RIGHT\n```\n\nAny element in the middle position will be automatically centered in the status bar.\n\n### Lazy Loading (SWR Caching)\n\nPowerKit uses Stale-While-Revalidate caching for optimal performance:\n\n```bash\n# Enable lazy loading (default: true)\nset -g @powerkit_lazy_loading \"true\"\n\n# Stale multiplier: how many times the TTL before data is considered \"too old\"\n# Example: TTL=300s, multiplier=3 → data up to 900s old can be returned while refreshing\nset -g @powerkit_stale_multiplier \"3\"\n```\n\n**How it works:**\n\n- Fresh data (within TTL): Returns cached data immediately\n- Stale data (within TTL × multiplier): Returns stale data immediately, refreshes in background\n- Too old data (beyond TTL × multiplier): Blocks and refreshes synchronously\n\nThis ensures your status bar never hangs waiting for slow API calls or network requests.\n\n### Plugin Groups\n\nGroup related plugins together using the `group(...)` syntax for visual cohesion:\n\n```bash\n# Group related plugins with shared separator backgrounds\nset -g @powerkit_plugins \"group(cpu,memory,loadavg),group(git,github),datetime\"\n```\n\nGroups are assigned colors from the `@powerkit_plugin_group_colors` palette in order:\n\n```bash\n# Customize group color palette (comma-separated theme colors or hex values)\nset -g @powerkit_plugin_group_colors \"info-base-darker,window-active-base-darker,ok-base-darker,warning-base-darker,error-base-darker,disabled-base\"\n```\n\nBy default, group colors only affect the separator backgrounds between plugins in the same group. Each plugin still uses its own health-based colors for the segment itself.\n\nTo create a fully unified visual band where all plugins in a group share the same background color, enable group coloring:\n\n```bash\n# Apply group palette colors to plugin segment backgrounds (default: false)\nset -g @powerkit_plugin_group_coloring \"true\"\n```\n\nWhen group coloring is enabled:\n\n- Plugin segment backgrounds use the group's palette color instead of health-based colors\n- Health feedback is preserved through **bold text styling** (warning/error states render bold)\n- Special states (`inactive`, `failed`) still use their semantic colors and are not overridden\n- Transparent mode (`@powerkit_transparent \"true\"`) disables group coloring and falls back to health-based colors\n- Stale data applies a darkened variant of the group color, consistent with the normal stale behavior\n\n---\n\n## 🔧 Creating Your Own Plugin\n\nPowerKit makes it easy to create custom plugins. Here's a minimal example:\n\n```bash\n#!/usr/bin/env bash\nPOWERKIT_ROOT=\"${POWERKIT_ROOT:-$(cd \"$(dirname \"${BASH_SOURCE[0]}\")/../..\" \u0026\u0026 pwd)}\"\n. \"${POWERKIT_ROOT}/src/contract/plugin_contract.sh\"\n\nplugin_get_metadata() {\n    metadata_set \"id\" \"my_plugin\"\n    metadata_set \"name\" \"My Plugin\"\n    metadata_set \"description\" \"What this plugin does\"\n}\n\nplugin_declare_options() {\n    declare_option \"icon\" \"icon\" \"󰀀\" \"Plugin icon\"\n    declare_option \"cache_ttl\" \"number\" \"60\" \"Cache duration\"\n}\n\nplugin_collect() {\n    # Collect your data\n    local value=\"42\"\n    plugin_data_set \"value\" \"$value\"\n}\n\nplugin_get_content_type() { printf 'dynamic'; }\nplugin_get_presence() { printf 'always'; }\nplugin_get_state() { printf 'active'; }\nplugin_get_health() { printf 'ok'; }\n\nplugin_render() {\n    local value=$(plugin_data_get \"value\")\n    printf '%s' \"$value\"\n}\n\nplugin_get_icon() {\n    printf '%s' \"$(get_option 'icon')\"\n}\n```\n\n**Learn more:** [Developing Plugins](https://github.com/fabioluciano/tmux-powerkit/wiki/DevelopingPlugins)\n\n---\n\n## 🎨 Creating Your Own Theme\n\nThemes are simple color definitions:\n\n```bash\n#!/usr/bin/env bash\ndeclare -A THEME_COLORS=(\n    # Status bar\n    [statusbar-bg]=\"#1a1b26\"\n    [statusbar-fg]=\"#c0caf5\"\n\n    # Session\n    [session-bg]=\"#7aa2f7\"\n    [session-fg]=\"#1a1b26\"\n\n    # Windows (variants auto-generated)\n    [window-active-base]=\"#7aa2f7\"\n    [window-inactive-base]=\"#3b4261\"\n\n    # Health states (variants auto-generated)\n    [ok-base]=\"#9ece6a\"\n    [info-base]=\"#7dcfff\"\n    [warning-base]=\"#e0af68\"\n    [error-base]=\"#f7768e\"\n)\n```\n\nThe system automatically generates **6 color variants** (light/lighter/lightest/dark/darker/darkest) for each base color!\n\n**Learn more:** [Developing Themes](https://github.com/fabioluciano/tmux-powerkit/wiki/DevelopingThemes)\n\n---\n\n## 📚 Complete Documentation\n\n| Resource | Description |\n|----------|-------------|\n| [**Installation Guide**](https://github.com/fabioluciano/tmux-powerkit/wiki/Installation) | Detailed setup instructions |\n| [**Quick Start**](https://github.com/fabioluciano/tmux-powerkit/wiki/Quick-Start) | Get started in 5 minutes |\n| [**Configuration Reference**](https://github.com/fabioluciano/tmux-powerkit/wiki/Configuration) | All configuration options explained |\n| [**Plugin Documentation**](https://github.com/fabioluciano/tmux-powerkit/wiki/Home#plugins-45-available) | Detailed docs for all 45 plugins |\n| [**Theme Gallery**](https://github.com/fabioluciano/tmux-powerkit/wiki/Themes) | Preview all themes and variants |\n| [**Developing Plugins**](https://github.com/fabioluciano/tmux-powerkit/wiki/DevelopingPlugins) | Create your own plugins |\n| [**Developing Themes**](https://github.com/fabioluciano/tmux-powerkit/wiki/DevelopingThemes) | Create custom themes |\n| [**Architecture**](https://github.com/fabioluciano/tmux-powerkit/wiki/Architecture) | Understanding the contract system |\n| [**API Reference**](https://github.com/fabioluciano/tmux-powerkit/wiki/API-Reference) | Core APIs and utilities |\n\n### 📋 Complete Options Reference\n\nA fully documented configuration file with **all available options** is maintained at:\n\n```text\nwiki/assets/powerkit-options.conf\n```\n\n**[📥 Download powerkit-options.conf](https://raw.githubusercontent.com/wiki/fabioluciano/tmux-powerkit/assets/powerkit-options.conf)**\n\nUse this file as a reference or copy the options you need to your `~/.tmux.conf`. Every option includes descriptions, valid values, and defaults.\n\n---\n\n## 🚦 Requirements\n\n- **tmux** 3.0 or higher\n- **Bash** 5.0 or higher (5.1+ recommended for optimal performance)\n- **TPM** (Tmux Plugin Manager)\n- **Nerd Font** (recommended for icons)\n\n\u003e **Note for macOS users:** macOS ships with Bash 3.x. Install a modern version with `brew install bash`.\n\n### Bash Version Features Used\n\n| Version | Features Used |\n|---------|--------------|\n| 5.0+ | `$EPOCHSECONDS`, `$EPOCHREALTIME`, `${var,,}`, `${var^^}` |\n| 5.1+ | `assoc_expand_once` (performance optimization) |\n\n### Platform Support\n\n- ✅ **macOS** (Intel \u0026 Apple Silicon)\n- ✅ **Linux** (Ubuntu, Debian, Fedora, Arch, and more)\n- ✅ **FreeBSD** (limited testing)\n- ✅ **WSL** (Windows Subsystem for Linux)\n\n---\n\n## 💡 Example Configurations\n\n### Minimal Setup\n\n```bash\nset -g @powerkit_plugins \"datetime,hostname\"\nset -g @powerkit_theme \"tokyo-night\"\nset -g @powerkit_separator_style \"rounded\"\n```\n\n### Developer Setup\n\n```bash\nset -g @powerkit_plugins \"git,github,kubernetes,terraform,cpu,memory,datetime\"\nset -g @powerkit_theme \"dracula\"\nset -g @powerkit_plugin_git_show_files \"true\"\nset -g @powerkit_plugin_kubernetes_show_namespace \"true\"\n```\n\n### System Monitor Setup\n\n```bash\nset -g @powerkit_plugins \"cpu,memory,disk,loadavg,temperature,fan,netspeed,datetime\"\nset -g @powerkit_theme \"gruvbox\"\nset -g @powerkit_theme_variant \"dark\"\nset -g @powerkit_plugin_cpu_show_cores \"true\"\nset -g @powerkit_plugin_netspeed_format \"both\"\n```\n\n### Productivity Setup\n\n```bash\nset -g @powerkit_plugins \"pomodoro,datetime,timezones,bitwarden,git,battery\"\nset -g @powerkit_theme \"catppuccin\"\nset -g @powerkit_theme_variant \"mocha\"\nset -g @powerkit_plugin_timezones_zones \"UTC,America/New_York,Europe/London\"\n```\n\n---\n\n## 🤝 Contributing\n\nWe welcome contributions! Here's how you can help:\n\n### Ways to Contribute\n\n- 🐛 **Report bugs** - Open an issue with details\n- 💡 **Suggest features** - Share your ideas\n- 📝 **Improve documentation** - Fix typos, add examples\n- 🔌 **Create plugins** - Share your custom plugins\n- 🎨 **Design themes** - Create beautiful color schemes\n- 💻 **Submit PRs** - Fix bugs or add features\n\n### Development Workflow\n\n1. **Fork** the repository\n2. **Create** a feature branch (`git checkout -b feature/amazing-feature`)\n3. **Commit** your changes (`git commit -m 'Add amazing feature'`)\n4. **Push** to the branch (`git push origin feature/amazing-feature`)\n5. **Open** a Pull Request\n\n### Development Tools\n\n```bash\n# Validate syntax\nbash -n src/**/*.sh\n\n# Run shellcheck\nshellcheck src/**/*.sh\n\n# Test render\nPOWERKIT_ROOT=\"$(pwd)\" ./bin/powerkit-render\n\n# Test specific plugin\nPOWERKIT_ROOT=\"$(pwd)\" ./bin/powerkit-plugin battery\n```\n\n**See:** [Development Guide](https://github.com/fabioluciano/tmux-powerkit/wiki/DevelopingPlugins)\n\n---\n\n## 🏆 Credits \u0026 Acknowledgments\n\nPowerKit is built on the shoulders of giants:\n\n- **[Powerline](https://github.com/powerline/powerline)** - Original inspiration\n- **[tmux](https://github.com/tmux/tmux)** - The best terminal multiplexer\n- **[TPM](https://github.com/tmux-plugins/tpm)** - Tmux Plugin Manager\n- All theme creators for their beautiful color schemes\n- The tmux community for continuous feedback and support\n\n---\n\n## 📄 License\n\nPowerKit is released under the **MIT License**.\n\nSee [LICENSE](LICENSE) for full details.\n\n---\n\n## 📬 Support \u0026 Community\n\n- 🐛 **Bug Reports:** [GitHub Issues](https://github.com/fabioluciano/tmux-powerkit/issues)\n- 📖 **Documentation:** [Wiki](https://github.com/fabioluciano/tmux-powerkit/wiki)\n- ⭐ **Show Support:** Star this repository!\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n### Made with ❤️ by [@fabioluciano](https://github.com/fabioluciano)\n\nIf PowerKit improves your tmux experience, please consider starring the repo! ⭐\n\n[⬆ Back to Top](#-powerkit)\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffabioluciano%2Ftmux-powerkit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffabioluciano%2Ftmux-powerkit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffabioluciano%2Ftmux-powerkit/lists"}