Crafting Your Perfect tmux Status Bar

For developers, system administrators, and anyone who spends significant time in the terminal, tmux is an indispensable tool. It dramatically boosts productivity by allowing you to manage multiple sessions, windows, and panes efficiently. However, have you ever felt that the default tmux interface, especially the status bar at the bottom, is a bit bland? This article will guide you step-by-step through transforming your tmux status bar from a simple information line into a powerful, personalized dashboard.

We'll cover everything from changing basic colors to embedding dynamic information like system stats, your current Git branch, and the time. By the end of this guide, your terminal environment will be more informative, visually appealing, and uniquely yours.

Getting Started: The .tmux.conf File

All tmux customization begins in the .tmux.conf configuration file, located in your home directory. If this file doesn't exist, you'll need to create it.

# Navigate to your home directory
cd ~

# Create the .tmux.conf file if it doesn't exist
touch .tmux.conf

Now, you can open this file with your favorite text editor to add your settings. Crucially, after modifying .tmux.conf, you must either restart tmux or reload the configuration within a running session for the changes to take effect.

The most common way to reload the config is to use the tmux command mode. By default, you press Ctrl+b followed by : to bring up the command prompt. Enter the following command and press Enter:

source-file ~/.tmux.conf

Since typing this repeatedly can be tedious, it's highly recommended to create a key binding for it in your .tmux.conf. For example, you can set it up so that pressing Ctrl+b followed by r reloads the configuration instantly.

# Add the following to your .tmux.conf
# Reload config with prefix + r
bind r source-file ~/.tmux.conf \; display-message "Config reloaded."

With the setup complete, let's dive into customizing the status bar.

Basic Status Bar Styling: Colors and Position

First, let's change the overall look and feel of the status bar by setting its background and foreground colors. This is done with the status-style option.

# .tmux.conf

# Set the default status bar style
# fg: foreground color, bg: background color
set -g status-style "fg=white,bg=black"

Available colors include black, red, green, yellow, blue, magenta, cyan, and white. If your terminal supports 256 colors, you can use colour0 through colour255, or even Hex codes in the #RRGGBB format.

If you prefer the status bar at the top of the screen instead of the default bottom position, use the status-position option.

# .tmux.conf

# Move the status bar to the top
set -g status-position top

Now, let's define what information appears on the left (status-left) and right (status-right) sides of the bar.

Populating the Status Bar: status-left and status-right

tmux provides a rich set of format strings to display dynamic information in the status bar. By combining these formats, you can populate the status-left and status-right options with exactly what you need.

Key Format Strings

• #S: Session name
• #I: Window index
• #W: Window name
• #F: Window flags (e.g., * for current, - for last, Z for zoomed)
• #P: Pane index
• #H: Hostname (short)
• #h: Hostname (full)
• %Y-%m-%d: Year-Month-Day
• %H:%M:%S: Hour:Minute:Second
• #(shell-command): The output of a shell command (the most powerful feature!)

1. Customizing status-left: Session and Window Info

The left side is typically used for displaying the current session and window information. Using separators improves readability.

# .tmux.conf

# Set the length of the left status bar
set -g status-left-length 40

# Display in the format: [SessionName] | WindowName
set -g status-left "[#S] | #W"

We can make this more visually appealing by adding colors using the #[fg=color,bg=color] syntax.

# .tmux.conf

# Highlight the session name with a yellow background and black text
set -g status-left "#[fg=black,bg=yellow] #S #[fg=white,bg=black] | #W"

2. Customizing status-right: System Info and Time

The right side is perfect for frequently checked information like system stats or the current time. The #(shell-command) format allows you to display almost anything.

For example, let's display the current date and time.

# .tmux.conf

# Set the length of the right status bar
set -g status-right-length 60

# Display in the format: "NetworkIP | Date | Time"
# Note: The command for IP may vary. This is for macOS. For Linux, try: #(ip a | grep 'inet' | grep -v '127.0.0.1' | awk '{print $2}' | cut -d'/' -f1 | head -n1)
set -g status-right "#(ifconfig en0 | grep 'inet ' | awk '{print $2}') | %Y-%m-%d | %H:%M"

Example for CPU Usage and Battery on macOS:

# .tmux.conf

# CPU Usage (macOS)
set -g status-right "CPU: #(top -l 1 | grep -E \"^CPU\" | cut -d' ' -f3) | %Y-%m-%d %H:%M"

# Battery Percentage (macOS)
set -g status-right "BAT: #(pmset -g batt | grep -o '[0-9]*%' | tr -d '%')% | %Y-%m-%d %H:%M"

Example for CPU Usage and Battery on Linux:

# .tmux.conf

# CPU Usage (Linux)
set -g status-right "CPU: #(grep 'cpu ' /proc/stat | awk '{usage=($2+$4)*100/($2+$4+$5)} END {print usage \"%\"}') | %Y-%m-%d %H:%M"

# Battery Percentage (Linux, path may vary)
set -g status-right "BAT: #(cat /sys/class/power_supply/BAT0/capacity)% | %Y-%m-%d %H:%M"

By leveraging shell scripts, you can display your Git branch, the currently playing song, or anything else you can imagine.

Center Alignment: Styling the Window List

The center portion of the status bar displays the window list by default. You can style this area as well.

# .tmux.conf

# Center the window list
set -g status-justify centre

# Style for the current window
setw -g window-status-current-style "fg=black,bg=green,bold"
# Format for the current window (show index, name, and flags)
setw -g window-status-current-format " #I:#W#F "

# Style for other windows
setw -g window-status-style "fg=gray,bg=default"
# Format for other windows
setw -g window-status-format " #I:#W#F "

The #F format is useful for displaying window flags, which indicate the window's state (current, last active, zoomed, etc.).

Advanced Techniques: Powerline Style and Plugins

While manual configuration is powerful, sometimes you want a beautiful result with less effort. This is where plugins and Powerline-style themes shine.

1. Creating a Manual Powerline Style

Powerline is a visual style that uses special characters to connect information segments with an arrow shape. To implement this, you first need to install and set up a Powerline-patched font in your terminal.

Once the font is set, you can use special characters (like , ) in your .tmux.conf to create the style.

# .tmux.conf (Example of a Powerline-like style)

# Required special characters
# U+E0B0 (), U+E0B2 ()
set -g status-left-length 30
set -g status-right-length 150

# Left side: Session info
set -g status-left "#[fg=black,bg=green] #S #[fg=green,bg=blue,nobold]"

# Center: Window list
set -g status-justify left
setw -g window-status-current-format "#[fg=black,bg=yellow] #I:#W #[fg=yellow,bg=blue]"
setw -g window-status-format "#[fg=white,bg=blue] #I:#W #[fg=blue,bg=blue]"

# Right side: System info
set -g status-right "#[fg=white,bg=blue]#[fg=black,bg=blue] #(echo 'some info') #[fg=blue,bg=cyan]#[fg=black,bg=cyan] %Y-%m-%d %H:%M "

The code above is a simple example mimicking the Powerline effect. It connects segments of different colors and information using the  (right arrow) and  (left arrow) characters to create a visual separation.

2. Using a Plugin Manager: TPM (Tmux Plugin Manager)

The most convenient method is to use TPM. TPM is a tool that makes it incredibly easy to install and manage tmux plugins.

Install TPM:

# Clone the TPM repository using git
git clone https://github.com/tmux-plugins/tpm ~/.tmux/plugins/tpm

Add TPM configuration to .tmux.conf:

You must add the following lines to the very bottom of your file.

# .tmux.conf

# List of plugins
set -g @plugin 'tmux-plugins/tpm'
set -g @plugin 'tmux-plugins/tmux-sensible' # Sensible tmux defaults
set -g @plugin 'dracula/tmux' # Dracula theme (includes status bar)
# set -g @plugin 'catppuccin/tmux' # Catppuccin theme
# set -g @plugin 'tmux-plugins/tmux-cpu' # CPU info plugin

# Dracula theme options (optional)
set -g @dracula-plugins "cpu-usage ram-usage"
set -g @dracula-show-powerline true

# Initialize TPM (must be at the very end of the file)
run '~/.tmux/plugins/tpm/tpm'

After saving the config file, launch tmux and press prefix(Ctrl+b) + I (capital 'I') to install the plugins. You will immediately see a beautiful status bar styled by the Dracula theme. To use other themes or functional plugins, simply add them to the list and install them with prefix + I.

Conclusion

We've explored various ways to customize the tmux status bar to fit your personal preferences and needs. From simple color changes and dynamic information via shell scripts to easy theming with TPM plugins, the possibilities are endless.

Take what you've learned today and start building your own .tmux.conf. A well-crafted status bar is more than just eye candy; it's a valuable partner that enhances both the efficiency and enjoyment of your time in the terminal.