31 library modules · 5 status bar widgets · 1 interactive dashboard · 3 Tokyo Night themes · 60 config options · 511 tests across an 8-job CI matrix · ~5,400 lines of pure bash · zero compiled dependencies
|
Fast-path cache returns stale output in ~20ms while a background process refreshes. Cold starts fall through to synchronous computation. |
Full-screen popup with CPU, GPU, RAM, Disk, Battery, Bluetooth, Network, Git, and system info. ANSI true-color progress bars, 5-second auto-refresh. |
|
Auto-detects provider from remote URL. Shows open PRs/MRs, reviews needed, assigned issues, and bugs directly in the status bar. |
macOS Apple Silicon, macOS Intel, and Linux. Platform-specific code paths with automatic fallbacks. No GNU coreutils conflicts. |
|
11-level icon sets for CPU, GPU, RAM, Swap, Disk, and Battery that change based on usage percentage. Color shifts from cyan to yellow to red at configurable thresholds. |
Pick your widgets, reorder them, toggle individual components, override colors, or skip everything with minimal mode. One tmux option per feature. |
Screenshots coming soon. The plugin renders Tokyo Night colors with Nerd Font icons in the tmux status bar and a popup dashboard.
| Tool | Version | Install |
|---|---|---|
| tmux | 3.0+ | github.com/tmux/tmux |
| Bash | 4.2+ | macOS: brew install bash |
| Nerd Fonts | v3+ | nerdfonts.com |
# Add to ~/.tmux.conf
set -g @plugin "gufranco/yoru-revamped-tmux"
# Press Prefix + I to install, then reload
tmux source-file ~/.tmux.confgit clone https://github.com/gufranco/yoru-revamped-tmux.git ~/.tmux/plugins/yoru-revamped-tmux
# Add to ~/.tmux.conf
# run-shell ~/.tmux/plugins/yoru-revamped-tmux/yoru-revamped.tmux
tmux source-file ~/.tmux.conftmux show-options -g | grep yoru_revamped
# Should list all default optionsThree variants of the Tokyo Night palette. Set with @yoru_revamped_theme.
| Theme | Background | Description |
|---|---|---|
night |
#1A1B26 |
Classic Tokyo Night. Default. |
storm |
#24283b |
Darker variant with muted contrast. |
day |
#d5d6db |
Light variant for bright environments. |
All themes include 8 base colors, 8 bright variants, and 4 GitHub integration colors. Every color is overridable with @yoru_revamped_color_* options.
set -g @yoru_revamped_theme "storm"Control which widgets appear and in what order:
# Default: all five
set -g @yoru_revamped_widgets_order "system,git,music,netspeed,context"
# Developer-focused
set -g @yoru_revamped_widgets_order "system,git,context"
# Minimal
set -g @yoru_revamped_widgets_order "context"CPU, GPU, Memory, Swap, Disk, and Battery in one status segment.
set -g @yoru_revamped_show_system 1
# Toggle individual components
set -g @yoru_revamped_system_cpu 1
set -g @yoru_revamped_system_gpu 1
set -g @yoru_revamped_system_memory 1
set -g @yoru_revamped_system_disk 1
set -g @yoru_revamped_system_battery 1
# Display options
set -g @yoru_revamped_system_show_percent 1 # 0 to hide "%" suffix, saves ~5 chars
# Configuration
set -g @yoru_revamped_system_disk_path "/"
set -g @yoru_revamped_system_battery_threshold 20Color scale: Cyan below 50%, Yellow at 50-79%, Red at 80%+. Battery blinks red below threshold.
GPU support by platform:
| Platform | Source | Method |
|---|---|---|
| macOS (Apple Silicon) | ioreg |
Max of Device, Renderer, and Tiler Utilization |
| Linux (NVIDIA) | nvidia-smi |
utilization.gpu query |
| Linux (AMD) | rocm-smi |
--showuse flag |
| Linux (generic) | sysfs | /sys/class/drm/card*/device/gpu_busy_percent |
Local repository status and web platform integration.
set -g @yoru_revamped_show_git 1
set -g @yoru_revamped_git_untracked 1
set -g @yoru_revamped_git_web 1
# Optional features
set -g @yoru_revamped_git_stash 1
set -g @yoru_revamped_git_ahead_behind 1
set -g @yoru_revamped_git_last_commit 1
# Display options
set -g @yoru_revamped_git_max_branch 25 # max chars before truncation with ellipsisLocal: Branch name, sync status, modified files, insertions/deletions, untracked count, stash count, ahead/behind, last commit time.
Web (requires gh/glab + jq): Auto-detects GitHub or GitLab from the remote URL. Shows open PRs/MRs, reviews needed, assigned issues, and bugs.
Real-time network monitoring with VPN awareness.
set -g @yoru_revamped_show_netspeed 1
set -g @yoru_revamped_netspeed_ping 1
set -g @yoru_revamped_netspeed_vpn 1
set -g @yoru_revamped_netspeed_vpn_name 1
set -g @yoru_revamped_netspeed_wifi 1
set -g @yoru_revamped_netspeed_connections 1Features: Upload/download speeds with color-coded thresholds, ping latency, WiFi signal strength in dBm, VPN detection for utun/tun/tap/WireGuard/Tailscale/NordLynx, active connection count.
Interface detection is automatic. Override with @yoru_revamped_netspeed_iface if needed.
Date, time, timezones, and weather.
set -g @yoru_revamped_show_context 1
set -g @yoru_revamped_context_date_format YMD # YMD, MD, DM, MDY, DMY, hide
set -g @yoru_revamped_context_time_format 24H # 24H, 12H, hide
# Multiple timezones
set -g @yoru_revamped_context_timezone 1
set -g @yoru_revamped_context_compact_timezone 1 # "LA 06:25 NY 09:25" instead of full format
set -g @yoru_revamped_context_timezones "America/Los_Angeles,America/New_York"
# Weather (requires curl or wget)
set -g @yoru_revamped_context_weather 1
set -g @yoru_revamped_context_weather_units "m" # m=metric, u=US, M=SIDate formats: YMD = 2026-03-04, MD = 03-04, DM = 04-03, MDY/DMY = full with year, hide = no date.
Compact timezone: Extracts a short label from the timezone city name. America/Los_Angeles becomes LA, America/New_York becomes NY, Europe/London becomes Lon. Drops the clock icon and timezone abbreviation for a tighter display.
Now-playing display with track info, artist, elapsed time, and a background-fill progress indicator. Disabled by default.
set -g @yoru_revamped_show_music 1
set -g @yoru_revamped_music_show_artist 1
set -g @yoru_revamped_music_show_progress 1
set -g @yoru_revamped_music_show_time 1
set -g @yoru_revamped_music_max_title 25Player detection priority:
| Platform | Priority |
|---|---|
| macOS | media-control (JSON, macOS 15+), osascript (Spotify/Music.app), cmus-remote |
| Linux | playerctl (MPRIS/D-Bus), cmus-remote |
Progress indicator: Instead of a separate bar, the played portion of the widget text gets a lighter background that advances as the track plays. This saves space compared to a dedicated ██░░ bar.
Press Prefix + d to open an interactive system dashboard in a tmux popup.
Sections (dynamically shown based on available data):
| Section | Metrics |
|---|---|
| CPU | Usage %, frequency (GHz), temperature (C) |
| GPU | Usage %, frequency, temperature |
| RAM | Used/Total with breakdown: wired, compressed, swap |
| Disk | Usage % with read/write I/O rates |
| Battery | Level %, cycle count, health %, wattage |
| Bluetooth | Connected peripherals with battery levels |
| Network | Upload/download speeds, ping, VPN, WiFi, local/public IPs |
| Git | Branch, modified/untracked, insertions/deletions, ahead/behind |
| System | Uptime, load averages, CPU count, top 3 processes, Docker/K8s counts |
The dashboard renders ANSI true-color progress bars with threshold coloring, auto-refreshes every 5 seconds, and closes with q, Esc, or Ctrl-C. On macOS the GPU row is always visible since Apple Silicon has an integrated GPU. On Linux it only appears when a GPU is detected.
# Change keybinding (default: d)
set -g @yoru_revamped_dashboard_key d
# Popup dimensions
set -g @yoru_revamped_dashboard_width 56
set -g @yoru_revamped_dashboard_height 28User information and session context. Turns green when the prefix key is active.
set -g @yoru_revamped_status_left_show_session 1
set -g @yoru_revamped_status_left_show_windows 1
set -g @yoru_revamped_status_left_show_panes 1
set -g @yoru_revamped_status_left_show_sync 1
set -g @yoru_revamped_status_left_show_zoom 1
set -g @yoru_revamped_status_left_show_mouse 1
set -g @yoru_revamped_status_left_show_hostname 1Format: user [@session] [w:p] [SYNC|ZOOM|MOUSE|@hostname]
Disable all widgets for a specific session:
set -g @yoru_revamped_minimal_session "minimal"Then tmux new-session -s minimal gives you a clean status bar with only the theme applied.
graph TD
subgraph Entry["Entry Point"]
EP["yoru-revamped.tmux"]
end
subgraph Orchestration["Theme and Widget Setup"]
TC["theme-config.sh"]
TH["themes.sh"]
SL["status-left.sh"]
end
subgraph Widgets["Status Bar Widgets"]
SW["system-widget.sh"]
GW["git-widget.sh"]
MW["music-widget.sh"]
NW["network-widget.sh"]
CW["context-widget.sh"]
end
subgraph Dashboard["Popup Dashboard"]
DB["dashboard.sh"]
end
subgraph Libraries["Library Modules"]
HW["Hardware: cpu, gpu, ram, disk, battery, bluetooth"]
NET["Network: network, network-utils, network-speed"]
MUS["Music: music"]
GIT["Git: git"]
UI["UI: themes, color-scale, color-config, ui"]
TMX["Tmux: tmux-ops, tmux-config, tmux-cache"]
UTL["Utils: fast-cache, cache, platform-cache, coreutils-compat, constants, has-command, error-logger"]
WDG["Widget: widget-loader, widget-common, widget-config"]
PD["platform-detector"]
end
EP --> TC
TC --> TH
TC --> SL
TC -->|"configures status-right"| SW
TC -->|"configures status-right"| GW
TC -->|"configures status-right"| MW
TC -->|"configures status-right"| NW
TC -->|"configures status-right"| CW
TC -->|"binds Prefix+d"| DB
SW --> WDG
GW --> WDG
MW --> WDG
NW --> WDG
CW --> WDG
WDG -->|"lazy loads"| HW
WDG -->|"lazy loads"| NET
WDG -->|"lazy loads"| MUS
WDG -->|"lazy loads"| GIT
WDG --> UTL
DB --> HW
DB --> NET
DB --> GIT
DB --> UI
HW --> PD
NET --> PD
Design principles:
- Single entry point.
yoru-revamped.tmuxsources onlytheme-config.sh, which orchestrates everything. - Lazy loading. Widgets load only the library modules they need via
widget-loader.sh. The system widget loads CPU, GPU, RAM, Disk, and Battery modules. The git widget loads only the git module. - Two-tier caching.
fast-cache.shchecks a file-based cache, returns stale output instantly if available, and spawns a background refresh.cache.shprovides the standard get/set/invalidate API. - Platform abstraction.
platform-cache.shdetects OS and architecture once and caches the result.platform-detector.shaggregates all platform-specific function implementations.coreutils-compat.shhandles macOS BSD vs GNUstatdifferences by explicitly calling/usr/bin/stat.
Project structure
yoru-revamped-tmux/
├── yoru-revamped.tmux # Entry point: loads theme-config.sh
├── src/
│ ├── dashboard.sh # Interactive popup dashboard
│ ├── system-widget.sh # CPU, GPU, RAM, Swap, Disk, Battery
│ ├── git-widget.sh # Branch, changes, web stats
│ ├── music-widget.sh # Now-playing: track, artist, progress
│ ├── network-widget.sh # Speeds, ping, VPN, WiFi
│ ├── context-widget.sh # Date, time, timezone, weather
│ └── lib/
│ ├── battery/battery.sh # Battery level, cycle count, health
│ ├── bluetooth/bluetooth.sh # Connected peripherals
│ ├── cpu/cpu.sh # Usage, frequency, temperature
│ ├── disk/disk.sh # Usage, I/O rates, multi-disk
│ ├── git/git.sh # Branch, diff stats, web integration
│ ├── gpu/gpu.sh # Usage, temperature (ioreg/nvidia/amd/drm)
│ ├── music/music.sh # Player detection, metadata, formatting
│ ├── network/
│ │ ├── network.sh # Interface detection, connections
│ │ ├── network-utils.sh # VPN, WiFi, ping utilities
│ │ └── network-speed.sh # Upload/download speed calculation
│ ├── ram/ram.sh # Total, active, memory pressure
│ ├── tmux/
│ │ ├── theme-config.sh # Widget orchestration, tmux settings
│ │ ├── status-left.sh # Left status bar rendering
│ │ ├── tmux-config.sh # Option helpers, numeric validation
│ │ └── tmux-ops.sh # get/set option, session detection
│ ├── ui/
│ │ ├── themes.sh # Tokyo Night palettes (night/storm/day)
│ │ ├── color-scale.sh # Dynamic color by value
│ │ ├── color-config.sh # User color overrides
│ │ └── ui.sh # Formatting: segments, bars, icons
│ ├── utils/
│ │ ├── fast-cache.sh # Stale-while-revalidate (~20ms)
│ │ ├── cache.sh # Standard file-based cache
│ │ ├── tmux-cache.sh # Bulk tmux option caching
│ │ ├── constants.sh # Icons, thresholds, defaults
│ │ ├── has-command.sh # Memoized command detection
│ │ ├── platform-cache.sh # OS/arch detection cache
│ │ ├── coreutils-compat.sh # BSD/GNU stat compatibility
│ │ └── error-logger.sh # Error and performance logging
│ ├── widget/
│ │ ├── widget-loader.sh # Lazy dependency loading
│ │ ├── widget-common.sh # Cache check, minimal session guard
│ │ └── widget-config.sh # Widget option helpers
│ └── platform-detector.sh # Platform-specific function aggregation
├── test/ # 33 bats-core test files, 511 tests
│ ├── lib/ # 28 library test files
│ ├── widgets/ # 5 widget test files
│ ├── helpers.bash # Shared test mocks and utilities
│ └── run_tests.sh # Test runner script
├── examples/ # Ready-to-use configuration presets
│ ├── developer.tmux.conf # Git-focused setup
│ ├── power-user.tmux.conf # All features enabled
│ ├── minimal.tmux.conf # Theme-only setup
│ ├── minimal-performance.tmux.conf # Lightweight with caching
│ └── themes/custom-colors.tmux.conf # Color override examples
├── scripts/ # Development tools
│ ├── benchmark.sh # Performance benchmarking
│ ├── check-dependencies.sh # Dependency health check
│ └── install-hooks.sh # Git hooks installer
├── templates/
│ └── custom-widget.sh # Widget creation template
├── .github/workflows/ # CI: lint, test matrix, release
├── Makefile # 30 make targets
├── .editorconfig # 2-space indent, UTF-8
├── .shellcheckrc # ShellCheck configuration
├── .pre-commit-config.yaml # Pre-commit hooks
└── LICENSE.md # MIT
Create widgets that integrate with the caching and theming framework.
#!/usr/bin/env bash
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
PROJECT_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
source "${PROJECT_ROOT}/src/lib/widget/widget-loader.sh"
is_minimal_session && exit 0
is_widget_enabled "@yoru_revamped_show_mywidget" || exit 0
cache_key="mywidget"
cache_ttl=$(get_tmux_option "@yoru_revamped_mywidget_refresh" "5")
if is_cache_valid "$cache_key" "$cache_ttl"; then
get_cached_value "$cache_key"
exit 0
fi
main() {
local metric="42"
local color
color=$(get_system_color "$metric")
local icon
icon=$(format_icon "MY_ICON" "#7dcfff")
local output="${icon} ${color}${metric}%#[default]"
set_cached_value "$cache_key" "$output"
echo "$output"
}
mainAdd to ~/.tmux.conf:
set -g @yoru_revamped_show_mywidget 1
set -g status-right "#(bash ~/my-custom-widget.sh)"Widget lifecycle: tmux executes the script on each status refresh. The fast-path cache returns instantly if a cached value exists. On cache miss, the widget checks minimal session and enabled status, collects metrics, formats output with theme colors, caches the result, and returns.
Functions available for custom scripts and extensions.
| Module | Functions |
|---|---|
platform-cache.sh |
get_os, get_arch, is_macos, is_linux, is_apple_silicon |
cpu.sh |
get_cpu_count, get_cpu_usage_percentage, get_load_average, get_cpu_temperature, get_cpu_frequency |
gpu.sh |
get_gpu_usage_percentage, get_gpu_temperature |
ram.sh |
get_total_memory_kb, get_active_memory_kb, get_memory_pressure |
disk.sh |
get_disk_usage, get_disk_space_gb, get_multiple_disks, get_disk_io |
network/*.sh |
get_default_network_interface, get_network_connections, get_vpn_connection_name, get_wifi_signal_strength, get_interface_ipv4, detect_vpn |
git.sh |
get_git_branch, get_git_status, get_git_changes, get_git_insertions, get_git_deletions |
music.sh |
detect_music_player, get_music_metadata, format_music_time, truncate_string, build_progress_bar |
cache.sh |
get_cached_value, set_cached_value, invalidate_cache, clear_all_caches |
tmux-ops.sh |
get_tmux_option, set_tmux_option, is_tmux_option_enabled, is_minimal_session |
Core functionality needs only tmux, Bash, and a Nerd Font. Everything else is optional and degrades gracefully when missing.
| Tool | Enables | Install |
|---|---|---|
git |
Git widget | Usually pre-installed |
gh |
GitHub PRs, issues, reviews | brew install gh / apt install gh |
glab |
GitLab MRs, issues | brew install glab / apt install glab |
jq |
JSON parsing for web features | brew install jq / apt install jq |
media-control |
Music widget (macOS 15+) | brew install ungive/media-control/media-control |
playerctl |
Music widget (Linux) | apt install playerctl |
curl / wget |
Weather widget | Usually pre-installed |
nvidia-smi |
NVIDIA GPU monitoring | NVIDIA drivers |
rocm-smi |
AMD GPU monitoring | ROCm |
sensors |
Temperature (Linux) | apt install lm-sensors |
istats |
Temperature (macOS) | gem install iStats |
| Command | Description |
|---|---|
make test |
Run all 511 tests |
make test-lib |
Run library tests only |
make test-widgets |
Run widget tests only |
make test-verbose |
Run tests with TAP output |
make benchmark |
Run performance benchmarks |
make check-deps |
Check dependency health |
make clean |
Remove cache temp files |
make install-hooks |
Install pre-commit hooks |
Tests run on every push and PR across 8 combinations:
| Bash 5.1 | Bash 5.2 | |
|---|---|---|
| Ubuntu + tmux 3.2 | tested | tested |
| Ubuntu + tmux 3.4 | tested | tested |
| macOS + tmux 3.2 | tested | tested |
| macOS + tmux 3.4 | tested | tested |
ShellCheck, markdown lint, bash syntax validation, and trailing whitespace/tab checks run in a separate Lint workflow.
[[ ]]for conditionals, not[ ]- 2-space indentation, no tabs
- All variables quoted:
"${variable}" - Max 120 characters per line
- Descriptive function names:
get_cpu_usage_percentage,detect_vpn_macos
Conventional Commits: <type>(<scope>): <subject>
Types: feat, fix, docs, style, refactor, perf, test, chore, ci
Scopes: system, git, music, network, context, dashboard, cache, color, ui, tests, ci
Does this work with tmux 2.x?
No. The plugin requires tmux 3.0+ for popup support, which powers the dashboard. Status bar widgets would work on 2.9+ in theory, but the CI matrix only tests 3.2 and 3.4. Stick with 3.0+.
Can I use only the theme without any widgets?
Set @yoru_revamped_widgets_order to an empty string, or use @yoru_revamped_minimal_session to get a clean status bar with only theme colors applied. The examples/minimal.tmux.conf preset does exactly this.
How does the caching work?
Two layers. fast-cache.sh implements stale-while-revalidate: it returns the last cached output immediately, even if expired, and spawns a background process to refresh. This keeps status bar updates under ~20ms. cache.sh is the standard get/set layer underneath, storing values as files in ${TMPDIR:-/tmp}/tmux_yoru_cache_${UID}/. Each widget controls its own cache TTL.
Why pure bash instead of Go, Rust, or Python?
Zero compiled dependencies. Every machine with tmux already has bash. No build step, no version manager, no runtime to install. The two-tier cache keeps latency low enough that a compiled language would not meaningfully improve the user experience for status bar rendering.
How do I add my own widget?
Copy templates/custom-widget.sh, rename it, and follow the pattern: source widget-loader.sh, check minimal session and enabled status, use the cache API, format output with theme colors. See the Custom Widgets section for a complete example.
Why does GPU show 0% on macOS?
Apple Silicon reports three GPU utilization fields: Device, Renderer, and Tiler. The plugin takes the max of all three. If all are 0, the GPU is genuinely idle. Run ioreg -r -d 1 -w 0 -c IOAccelerator | grep "Utilization %" to verify. The GPU only lights up under sustained graphics workloads, not normal terminal use.
Widgets not showing
- Check the widget is enabled:
tmux show-options -g | grep show_system - Check
widgets_orderincludes it:tmux show-options -g @yoru_revamped_widgets_order - Verify you are not in minimal mode
- Test the widget directly:
bash src/system-widget.sh - Check tmux messages:
tmux show-messages
Widgets showing "0" or empty values
Clear the cache and reload:
rm -rf "${TMPDIR:-/tmp}/tmux_yoru_cache_${UID}/"
tmux source ~/.tmux.confGit web features not working
- Verify tools:
gh --version && jq --version - Authenticate:
gh auth login - Test from a git repo:
bash src/git-widget.sh "$(pwd)"
GPU always shows 0%
macOS: Check all three utilization fields: ioreg -r -d 1 -w 0 -c IOAccelerator | grep "Utilization %". The plugin takes the max of Device, Renderer, and Tiler. If all are 0, the GPU is idle.
Linux NVIDIA: nvidia-smi --query-gpu=utilization.gpu --format=csv,noheader.
Linux AMD: rocm-smi --showuse.
Linux generic: cat /sys/class/drm/card*/device/gpu_busy_percent.
Temperature not showing
macOS: gem install iStats, then verify: istats cpu.
Linux: apt install lm-sensors && sensors-detect, then check: ls /sys/class/thermal/thermal_zone*/temp.
GNU coreutils conflicts on macOS
The plugin uses /usr/bin/stat explicitly to avoid conflicts between BSD and GNU stat flag semantics. This is handled automatically. If you see "unbound variable" errors, update to the latest version.
Advanced debugging
# Trace widget execution
bash -x src/system-widget.sh 2>&1 | tee debug.log
# Test individual functions
source src/lib/platform-detector.sh
get_cpu_usage_percentage
# Inspect cache
ls -lh "${TMPDIR:-/tmp}/tmux_yoru_cache_${UID}/"
# Complete reset
rm -rf "${TMPDIR:-/tmp}/tmux_yoru_cache_${UID}/"
rm -rf ~/.tmux/yoru-logs/
tmux kill-server && tmux
# Health check
bash scripts/check-dependencies.shReporting issues
Include this output:
uname -a
tmux -V
bash --version
tmux show-options -g | grep yoru_revamped
bash -x src/system-widget.sh 2>&1 | tee error.logReport vulnerabilities via GitHub Security Advisories.
- All widget scripts run with your user permissions
- GitHub/GitLab tokens should have minimal required scopes
- Weather and web features make external API calls
- Cache files are created with user-only permissions in
${TMPDIR:-/tmp}/tmux_yoru_cache_${UID}/
- Tokyo Night VSCode Theme by enkia
- tokyonight-vim by ghifarit53
- Nerd Fonts community