status-line.md

April 8, 2026 ยท View on GitHub

Using the theme's built-in status modules

To use the theme's built in status modules, set the status-left and status-right tmux options after the plugin has been loaded with run.

The tmux status line modules are set as variables and prefixed with @catppuccin_status_<module>.

To use the application and session modules on the right and have nothing on the left:

set -g status-right-length 100

set -g status-right "#{E:@catppuccin_status_application}#{E:@catppuccin_status_session}"
set -g status-left ""

Some notes about expanding options when setting the status line:

  • Options are expanded as format strings by placing E: before the option name.
  • When a module status string contains a reference to another variable, you have to add the -F flag that treats the value passed as a format string that is immediately expanded, that is use set -gF (see tmux set-option man page).
  • Example for such a case is the battery module below, where the status contains the format string #{battery_percentage} that needs to be further expanded.

Customizing modules

Every module supports the following overrides:

Override the specific module icon

set -g @catppuccin_[module_name]_icon "icon"

Override the specific module color

set -g @catppuccin_[module_name]_color "color"

Override the specific module text

set -g @catppuccin_[module_name]_text "text"

Override the specific module's background color

set -g @catppuccin_status_[module_name]_bg_color "#{@thm_surface_0}"

Removing a specific module option

set -g @catppuccin_[module_name]_[option] ""

This is for the situation where you want to remove the icon from a module. For example:

set -g @catppuccin_date_time_icon ""

Notes for TPM users

Make sure you load the catppuccin theme prior to setting the status-left and/or status-* options. This ensures the catppuccin options (such as colors and status modules) are defined so they can then be used.

After status-left and/or status-right have been set, make sure to run TPM to load the modules. This runs any plugins that may replace text in the status line.

# load catppuccin theme ...
run '~/.config/tmux/plugins/tmux/catppuccin.tmux' # or where this file is located on your machine

# ... and then set status-left & status-right ...
set -g status-left "#{E:@catppuccin_status_session}"

set -g status-right "#{E:@catppuccin_status_[module_name]}"
set -ag status-right "#{E:@catppuccin_status_[module_name]}"
set -agF status-right "#{E:@catppuccin_status_[module_name]}"

# ... and finally start TPM
set -g @plugin 'tmux-plugins/tpm'
run '~/.tmux/plugins/tpm/tpm'

Battery module

Requirements: This module depends on tmux-battery.

Install: The preferred way to install tmux-battery is using TPM.

Configure:

run ~/.config/tmux/plugins/catppuccin/tmux/catppuccin.tmux

set -agF status-right "#{E:@catppuccin_status_battery}"

set -g @plugin 'tmux-plugins/tmux-battery'
run '~/.tmux/plugins/tpm/tpm'

CPU module

Requirements: This module depends on tmux-cpu.

Install: The preferred way to install tmux-cpu is using TPM.

Configure:

run ~/.config/tmux/plugins/catppuccin/tmux/catppuccin.tmux

set -agF status-right "#{E:@catppuccin_status_cpu}"

set -g @plugin 'tmux-plugins/tmux-cpu'
run '~/.tmux/plugins/tpm/tpm'

RAM module

Requirements: This module depends on tmux-cpu.

Install: The preferred way to install tmux-cpu is using TPM.

Configure:

run ~/.config/tmux/plugins/catppuccin/tmux/catppuccin.tmux

set -agF status-right "#{E:@catppuccin_status_ram}"

set -g @plugin 'tmux-plugins/tmux-cpu'
run '~/.tmux/plugins/tpm/tpm'

Weather modules

tmux-weather

Requirements: This module depends on tmux-weather.

Install: The preferred way to install tmux-weather is using TPM.

Configure:

run ~/.config/tmux/plugins/catppuccin/tmux/catppuccin.tmux

set -agF status-right "#{E:@catppuccin_status_weather}"

set -g @plugin 'xamut/tmux-weather'
run '~/.tmux/plugins/tpm/tpm'

tmux-clima

Requirements: This module depends on tmux-clima.

Install: The preferred way to install tmux-clima is using TPM.

Configure:

run ~/.config/tmux/plugins/catppuccin/tmux/catppuccin.tmux

set -agF status-right "#{E:@catppuccin_status_clima}"

set -g @plugin 'vascomfnunes/tmux-clima'
run '~/.tmux/plugins/tpm/tpm'

Load module

Configure:

run ~/.config/tmux/plugins/catppuccin/tmux/catppuccin.tmux

set -agF status-right "#{E:@catppuccin_status_load}"

Gitmux module

Requirements: This module depends on gitmux.

Install: To install gitmux, follow the instructions in the gitmux documentation.

Configure:

Add the gitmux module to the status modules list.

run ~/.config/tmux/plugins/catppuccin/tmux/catppuccin.tmux

set -agF status-right "#{@catppuccin_status_gitmux}"

Follow the instructions in the gitmux documentation to create a gitmux config file. The gitmux plugin expects a file to be present at ~/.gitmux.conf.

Add the following to your ~/.gitmux.conf so that it uses catppuccin colors:

tmux:
  styles:
    clear: "#[fg=#{@thm_fg}]"
    state: "#[fg=#{@thm_red},bold]"
    branch: "#[fg=#{@thm_fg},bold]"
    remote: "#[fg=#{@thm_teal}]"
    divergence: "#[fg=#{@thm_fg}]"
    staged: "#[fg=#{@thm_green},bold]"
    conflict: "#[fg=#{@thm_red},bold]"
    modified: "#[fg=#{@thm_yellow},bold]"
    untracked: "#[fg=#{@thm_mauve},bold]"
    stashed: "#[fg=#{@thm_blue},bold]"
    clean: "#[fg=#{@thm_rosewater},bold]"
    insertions: "#[fg=#{@thm_green}]"
    deletions: "#[fg=#{@thm_red}]"

Pomodoro module

Requirements:: This module depends on tmux-pomodoro-plus.

Install:: The preferred way to install tmux-pomodoro-plus is using TPM.

Configure:

run ~/.config/tmux/plugins/catppuccin/tmux/catppuccin.tmux

set -agF status-right "#{E:@catppuccin_status_pomodoro_plus}"

set -g @plugin 'olimorris/tmux-pomodoro-plus'
run '~/.tmux/plugins/tpm/tpm'

Kube module

Requirements: This module depends on tmux-kubectx.

Install: The preferred way to install tmux-kubectx is using TPM.

Configure:

set -g @catppuccin_kube_context_color "#{@thm_red}"
set -g @catppuccin_kube_namespace_color "#{@thm_sky}"

run ~/.config/tmux/plugins/catppuccin/tmux/catppuccin.tmux

set -agF status-right "#{E:@catppuccin_status_kube}"

set -g @plugin 'tony-sol/tmux-kubectx'
run '~/.tmux/plugins/tpm/tpm'