Skip to content

gufranco/yoru-revamped-tmux

 
 

Repository files navigation

夜 yoru

A nocturnal tmux experience inspired by Tokyo nights.


Tests Lint tmux bash platform license


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


Two-Tier Caching

Fast-path cache returns stale output in ~20ms while a background process refreshes. Cold starts fall through to synchronous computation.

Interactive Dashboard

Full-screen popup with CPU, GPU, RAM, Disk, Battery, Bluetooth, Network, Git, and system info. ANSI true-color progress bars, 5-second auto-refresh.

GitHub and GitLab Integration

Auto-detects provider from remote URL. Shows open PRs/MRs, reviews needed, assigned issues, and bugs directly in the status bar.

Cross-Platform

macOS Apple Silicon, macOS Intel, and Linux. Platform-specific code paths with automatic fallbacks. No GNU coreutils conflicts.

Dynamic Icons

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.

Fully Modular

Pick your widgets, reorder them, toggle individual components, override colors, or skip everything with minimal mode. One tmux option per feature.


Screenshots

Screenshots coming soon. The plugin renders Tokyo Night colors with Nerd Font icons in the tmux status bar and a popup dashboard.


Quick Start

Prerequisites

Tool Version Install
tmux 3.0+ github.com/tmux/tmux
Bash 4.2+ macOS: brew install bash
Nerd Fonts v3+ nerdfonts.com

Install with TPM

# Add to ~/.tmux.conf
set -g @plugin "gufranco/yoru-revamped-tmux"

# Press Prefix + I to install, then reload
tmux source-file ~/.tmux.conf

Install Manually

git 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.conf

Verify

tmux show-options -g | grep yoru_revamped
# Should list all default options

Themes

Three 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"

Widgets

Widget Ordering

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"

System Widget

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 20

Color 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

Git Widget

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 ellipsis

Local: 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.

Network Widget

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 1

Features: 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.

Context Widget

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=SI

Date 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.

Music Widget

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 25

Player 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.


Dashboard

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 28

Status Left

User 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 1

Format: user [@session] [w:p] [SYNC|ZOOM|MOUSE|@hostname]


Minimal Mode

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.


Architecture

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
Loading

Design principles:

  • Single entry point. yoru-revamped.tmux sources only theme-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.sh checks a file-based cache, returns stale output instantly if available, and spawns a background refresh. cache.sh provides the standard get/set/invalidate API.
  • Platform abstraction. platform-cache.sh detects OS and architecture once and caches the result. platform-detector.sh aggregates all platform-specific function implementations. coreutils-compat.sh handles macOS BSD vs GNU stat differences 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

Custom Widgets

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"
}

main

Add 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.


Public API

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

Optional Dependencies

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

Development

Commands

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

CI Matrix

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.

Code Style

  • [[ ]] 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

Commit Format

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


FAQ

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.


Troubleshooting

Widgets not showing
  1. Check the widget is enabled: tmux show-options -g | grep show_system
  2. Check widgets_order includes it: tmux show-options -g @yoru_revamped_widgets_order
  3. Verify you are not in minimal mode
  4. Test the widget directly: bash src/system-widget.sh
  5. 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.conf
Git web features not working
  1. Verify tools: gh --version && jq --version
  2. Authenticate: gh auth login
  3. 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.sh
Reporting 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.log

Security

Report 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}/

Acknowledgments

License

MIT

About

Nocturnal tmux status bar with Tokyo Night themes, 5 modular widgets, interactive dashboard, two-tier caching, and GitHub/GitLab integration. 31 library modules, 511 tests, pure bash, zero compiled dependencies

Topics

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

 
 
 

Contributors

Languages

  • Shell 98.7%
  • Makefile 1.3%