tmux2k

Make tmux powerful and pretty 🥊💅

tmux2k is a highly customizable framework designed to enhance your tmux status bar, providing you with a sleek and informative interface for your terminal sessions.

✨ Features

• Informative Display: Essential system stats, git info, weather, and more.
• Plugin Ecosystem: Extensive plugins for system monitoring and version control.
• Easy Customization: Intuitive configuration and flexible architecture.
• Real-Time Updates: Dynamic content rendering for a responsive experience.

⚡ Setup

⚙️ Requirements

• A patched nerd font for powerline and glyphs support.

💻 Installation

If you are a tpm user, you can install the theme and keep up to date by adding the following to your .tmux.conf file:

set -g @plugin '2kabhishek/tmux2k'

Run tmux and use the tpm install command: prefix + I (default prefix is ctrl+b)

You can also directly clone the repo to your ~/.tmux/plugins/ folder.

🎨 Available Themes:

• default
• default icons
• catppuccin
• catppuccin icons
• gruvbox
• gruvbox icons
• monokai
• monokai icons
• onedark
• onedark icons
• duo
• duo icons
• duo blue
• default no powerline

To use themes:

# use a theme
set -g @tmux2k-theme 'onedark'

# to show icons only
set -g @tmux2k-icons-only true

# to customize duo bg and fg
set -g @tmux2k-duo-fg "#1688f0" # this will get you duo blue shown above
set -g @tmux2k-duo-bg "#000000" # this will set the bg for duo theme

# to set powerline symbols
set -g @tmux2k-right-sep  # alternate right status bar sep
set -g @tmux2k-window-list-right-sep  # alternate window list right sep

# to not show powerline
set -g @tmux2k-show-powerline false

# set session icon, accepts: `session`, `window`, or any string
set -g @tmux2k-session-icon " #S" # `#W` for window name

set -g @tmux2k-light-yellow '#f8c800' # change light yellow base color
set -g @tmux2k-bg-main '#ffffff' # change bg to white
set -g @tmux2k-prefix-highlight '#f8c800' # change prefix color

# 1. Auto-palette hashing (deterministic unique color per session/branch)
set -g @tmux2k-session-dynamic-colors "auto"

# 2. Pattern matching (evaluated left-to-right, supports globs)
set -g @tmux2k-session-dynamic-colors "prod*=red work*=blue dev*=#3dd50a"
set -g @tmux2k-git-dynamic-colors "*dirty*=red main*=green feat*=pink fix*=yellow auto"
set -g @tmux2k-cwd-dynamic-colors "/etc*=red ~/Projects*=green ~/Work*=purple"

🌈 Gradient Colors

Gradients dynamically color plugin output values based on their magnitude — lower values use colors from the start of the gradient, higher values from the end.

Each color represents a percentage range determined by the gradient's length. Given a 5-color gradient (5 ranges of 20%), a value of 25% applies color 2 of 5.

Named Gradients

Gradient colors can be reversed by prepending a ! to the gradient name, e.g.: !gruvbox

Gradient	Colors
catppuccin | catppuccin-dark
gruvbox | gruvbox-dark
monokai | monokai-dark
onedark | onedark-dark
heat | heat-dark
cosmic | cosmic-dark

You can also define a custom gradient as a space-separated list of hex colors:

# 3-color gradient: R=0-32% G=33-65% B=66-100%
set -g @tmux2k-cpu-gradient '#ff0000 #00ff00 #0000ff'

Supported Plugins:

The following plugins support gradients and expose @tmux2k-[plugin]-gradient and @tmux2k-[plugin]-icon-link-to values:

Plugin	icon-link-to values
cpu	usage, 1m,5m,15m
ram	usage
gpu	usage
battery	usage

set -g @tmux2k-[plugin]-gradient 'heat'
set -g @tmux2k-[plugin]-icon-link-to 'usage'
# example for cpu plugin:
set -g @tmux2k-cpu-gradient 'catppuccin'  # Use 'catppuccin' themed gradient
set -g @tmux2k-cpu-icon-link-to 'usage'   # Share usage value color with icon

🧩 Available Plugins

bandwidth

Show network bandwidth usage

• tmux2k-bandwidth-network-name: Network interface to track bandwidth of, default: en0
• tmux2k-bandwidth-up-icon: Icon for bandwidth upload usage, default: 
• tmux2k-bandwidth-down-icon: Icon for bandwidth download usage, default: 

battery

Show battery stats and percentage

• tmux2k-battery-charging-icon: Icon for charging status, default: 
• tmux2k-battery-missing-icon: Icon for missing battery, default: 󱉝
• tmux2k-battery-percentage-0: Icon for 0-25% battery, default: 
• tmux2k-battery-percentage-1: Icon for 25-50% battery, default: 
• tmux2k-battery-percentage-2: Icon for 50-75% battery, default: 
• tmux2k-battery-percentage-3: Icon for 75-90% battery, default: 
• tmux2k-battery-percentage-4: Icon for 90-100% battery, default: 

cpu

Show CPU usage and load information

• tmux2k-cpu-icon: Icon for CPU usage, default: 

• tmux2k-cpu-display-usage: Display CPU usage percentage, default: true

• tmux2k-cpu-precision: Decimal precision for usage percentage (e.g. 0 for 3%, 1 for 3.1%, 2 for 3.11%), default: 0

• tmux2k-cpu-usage-average: Number of usage values to average, default: 0

  
  

  Display CPU usage as an average of n values over s seconds, where n is the value given to this option and s the value of tmux2k-refresh-rate multiplied by n.

  # Display a 10s avg w/2s refresh rate
  set -g @tmux2k-refresh-rate 2
  set -g @tmux2k-cpu-usage-average 5
  
  # Display a 1m avg w/15s refresh rate
  set -g @tmux2k-refresh-rate 15
  set -g @tmux2k-cpu-usage-average 4
  

• tmux2k-cpu-usage-decimal: Display usage with decimal accuracy, default: true

• tmux2k-cpu-display-load: Display CPU load averages, default: false

  
  

  Displays CPU load averages given by uptime, each representing the average number of processes using or waiting to use CPU time over 1, 5 and 15 minutes.

• tmux2k-cpu-load-percent: Display load averages as percentages, default: true

• tmux2k-cpu-load-normalize: Normalize CPU load averages, default: true

  
  

  When this option is true, each load average provided by uptime is divided by the number of logical cores on the system to give a more identifiable reading.

• tmux2k-cpu-load-averages: CPU load averages to display, default: 1m 5m 15m

  
  

  The uptime command provides averages at 1, 5 and 15 minute intervals. You can define which of the three intervals to display by passing them as a space-separated list.

  For example, passing 1m 15m will display the 1 and 15 minute CPU load averages.

cpu-temp

Show CPU temperature

• tmux2k-cpu-temp-icon: Icon for CPU temperature, default: 
• tmux2k-cpu-temp-delimiter: Decimal delimiter for CPU temperature, default: .
• tmux2k-cpu-temp-round: Round CPU temperature to the nearest integer, default: false

cwd

Show current working directory

• tmux2k-cwd-icon: Icon for directory, default: 
• tmux2k-cwd-length: Maximum path length before truncation, default: 30
• tmux2k-cwd-min-depth: Minimum directory depth before mid-truncation, default: 4
• tmux2k-cwd-prefix-chars: Characters to keep from each directory name when truncating, default: 2

docker

Show the number of running Docker containers, with support for filtering by grep term.

• tmux2k-docker-icon: Icon for docker, default: 
• tmux2k-docker-grep: Grep term for filtering containers, default: ``

git

Show Git branch and status information

• tmux2k-git-display-status: Control git status display, default: false
• tmux2k-git-added-icon: Icon for added files, default: 
• tmux2k-git-modified-icon: Icon for modified files, default: 
• tmux2k-git-updated-icon: Icon for updated files, default: 
• tmux2k-git-deleted-icon: Icon for deleted files, default: 
• tmux2k-git-repo-icon: Icon for repository, default: 
• tmux2k-git-diff-icon: Icon for differences, default: 
• tmux2k-git-no-repo-icon: Icon for no repository, default: 

github

Show the number of pending GitHub notifications using GitHub CLI (needs gh cli with auth logged in)

• tmux2k-github-icon: Icon for GitHub notifications, default: 

gpu

Show GPU usage information

• tmux2k-gpu-icon: Icon for GPU usage, default: 

group

Group output from several other plugins to present information in a compact manner.

• tmux2k-group[N]-plugins: Space-separated list of plugins to combine in group N (e.g. "cpu ram")
• tmux2k-group[N]-delimiter: Delimiter string between plugins in group N, default: " "
• tmux2k-group[N]-colors: Custom background and foreground colors for group N, default: inherited from preceding plugin

# Define multiple groups
set -g @tmux2k-group1-plugins "cpu ram"
set -g @tmux2k-group1-delimiter " | "

set -g @tmux2k-group2-plugins "battery network"
set -g @tmux2k-group2-delimiter " • "

set -g @tmux2k-group3-plugins "time uptime"

# Use them in your status bar
set -g @tmux2k-left-plugins "session group1 git"
set -g @tmux2k-right-plugins "group2 group3"

# Set colors for specific groups
set -g @tmux2k-group1-colors "blue text"
set -g @tmux2k-group2-colors "purple text"

keyboard-layout

Show the active keyboard layout. Supports KDE Plasma (Wayland), X11 (via setxkbmap/xkb-switch), Hyprland, Sway, GNOME, macOS (HIToolbox/im-select), and localectl system fallback.

• tmux2k-keyboard-layout-icon: Icon for keyboard layout, default: 
• tmux2k-keyboard-layout-format: Display mode format, default: short, options: short, long
• tmux2k-keyboard-layout-case: Text capitalization mode, default: upper, options: upper, lower, none

mise

Show active runtime versions managed by mise (dev tool version manager) with language icons

• tmux2k-mise-max-tools: Maximum number of tools to display, default: 3
• tmux2k-mise-exclude-tools: Space-separated list of tools to exclude, default: usage

Supports language icons for popular languages out of the box, easy to add more.

network

Show network status and statistics

• tmux2k-network-ethernet-icon: Icon for Ethernet connection, default: 󰈀
• tmux2k-network-wifi-icon: Icon for Wi-Fi connection, default: 
• tmux2k-network-offline-icon: Icon for offline status, default: 󰌙

ping

Show network ping statistics

• tmux2k-ping-server: Host/port to ping, default: google.com
• tmux2k-ping-icon: Icon for ping, default: 󱘖

pomodoro

Shows pomodoro timer, needs tmux-pomodoro-plus (hit prefix + p to start)

ram

Show RAM usage information

• tmux2k-ram-icon: Icon for RAM usage, default: 
• tmux2k-ram-display: Display mode format, default: percent, options: percent, free, used, used_total
• tmux2k-ram-precision: Decimal precision for usage percentage (e.g. 0 for 15%, 1 for 15.2%), default: 0

storage

Show disk storage usage information

• tmux2k-storage-icon: Icon for storage usage, default: 󰋊
• tmux2k-storage-path: Path to monitor, default: /
• tmux2k-storage-display: Display mode format, default: percent, options: percent, free, used, used_total

volume

Show system volume level and mute status

• tmux2k-volume-icon: Fixed icon for volume display (overrides dynamic level icons)
• tmux2k-volume-icon-high: Icon for high volume (>=70%), default: 
• tmux2k-volume-icon-med: Icon for medium volume (>=30%), default: 󰖀
• tmux2k-volume-icon-low: Icon for low volume (<30%), default: 
• tmux2k-volume-icon-muted: Icon for muted volume, default: 󰖁

session

Shows Current Session/Window with custom icon

• tmux2k-session-format: Format for Tmux session, default: #S
• tmux2k-session-icon: Icon for Tmux session, default: 
• tmux2k-session-dynamic-colors: Dynamic colors or auto-hashing, e.g. auto or work=blue prod*=red

time

Show current time and date

• tmux2k-time-format: Format for displaying time, default: "%a %I:%M %p"
• tmux2k-time-icon: Icon for time display, default: 

updates

Show available system updates. The following package managers are supported:

• pacman [+ yay] (arch, manjaro, endeavourOS)
• apt (debian, ubuntu, popos, elementaryOS, mint, zorin)
• brew (macOS)

weather

Show weather information

• tmux2k-weather-scale: Temperature scale, default: c, options: c, f, k
• tmux2k-weather-display-condition: Display weather condition text, default: true
• tmux2k-weather-display-location: Display location name, default: false
• tmux2k-weather-location: Fixed location for weather, default: ""

window-list

tmux window list, this plugin is not supposed to be added to left / right plugin arrays, use the alignment option to position it.

• tmux2k-window-list-alignment: Alignment of the window list, default: absolute-centre, options: left, centre, right, absolute-centre
• tmux2k-window-list-left-sep: Left separator for the window list, default: 
• tmux2k-window-list-right-sep: Right separator for the window list, default: 
• tmux2k-window-list-format: Format for the window list items, default: #I:#W
• tmux2k-window-list-compact: Compact mode without spaces, default: false

uptime

Show current system uptime

• tmux2k-uptime-icon: Icon for system uptime, default: 󱎫

tdo

Show pending todo with tdo

• tmux2k-tdo-icon: Icon for todos display, default: 

🪆 Add New Plugins

To add a new plugin:

• Copy plugin/custom.sh and rename it to match your plugin name.
• Update the new plugin script to echo the expected output.
• Add color declaration for your plugin name into the plugin_colors array in main.sh

The plugin name and script file name must match e.g: plugin named foo should have a file called scripts/foo.sh

General Plugin Configs

# set the left and right plugin sections
set -g @tmux2k-left-plugins "session git cpu ram"
set -g @tmux2k-right-plugins "battery network time"

# control refresh rate of status bar plugins that display dynamic information
set -g @tmux2k-refresh-rate 5

# override the refresh rate for a specific plugin (in seconds)
# its output is cached and re-computed only after this many seconds,
# useful for expensive plugins, e.g. ones that hit network APIs
set -g @tmux2k-[plugin-name]-refresh-rate 300
set -g @tmux2k-github-refresh-rate 300 # poll the GitHub API every 5 minutes only

# to customize plugin colors
set -g @tmux2k-[plugin-name]-colors "[background] [foreground]"
set -g @tmux2k-cpu-colors "red black" # set cpu plugin bg to red, fg to black

🪟 Interactive Status Bar Popups

tmux2k supports interactive status bar popups — simply click any plugin segment on the status bar to launch a popup terminal tool!

Popup Configuration Options

# Enable/disable interactive status bar popups (default: true)
set -g @tmux2k-enable-popups true

# Popup window dimensions (default: 85%)
set -g @tmux2k-popup-width "85%"
set -g @tmux2k-popup-height "85%"

# Override popup command for a specific plugin
set -g @tmux2k-[plugin-name]-popup-cmd "my-custom-tool"
set -g @tmux2k-window-list-popup-cmd "tea -p"

# Override popup execution type: 'popup' (tmux display-popup) or 'direct' (background execution for tools managing their own popup e.g. tea)
set -g @tmux2k-[plugin-name]-popup-type "popup"
set -g @tmux2k-session-popup-type "direct"
set -g @tmux2k-window-list-popup-type "direct"

Smart Popup Auto-Detection

Clicking any status bar segment automatically detects and opens the best available TUI or system tool installed on your system (e.g., btop/htop for resource plugins, ranger/yazi for file browsing, lazygit/gitui for git, yay/pacman/apt for updates, and desktop settings panels for keyboard layout).

You can override any plugin's popup command or execution mode at any time using:

set -g @tmux2k-[plugin-name]-popup-cmd "your-custom-command"
set -g @tmux2k-[plugin-name]-popup-type "popup" # 'popup' or 'direct'

🧑‍💻 Behind The Code

🌈 Inspiration

I came across dracula/tmux sometime back and I wanted to create a more customizable and easy to expand solution.

💡 Challenges/Learnings

• Learned a lot about the tmux and tpm ecosystem.
• Did some fancy shell scripting.

🏗️ What's Next

• You tell me!

🧰 Tooling

• dots2k — Dev Environment
• nvim2k — Personalized Editor
• sway2k — Desktop Environment
• qute2k — Personalized Browser

🔍 More Info

• tmux-tea — Simple and powerful tmux session manager
• tmux-tilit — Turns tmux into a terminal window manager