### TPM Plugin Loading and Status Line Setup

Source: https://github.com/catppuccin/tmux/blob/main/docs/reference/status-line.md

Example of loading the Catppuccin theme, setting status line options, and initializing TPM. Ensure theme is loaded before status options.

```bash
# 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'
```

--------------------------------

### TPM Installation

Source: https://github.com/catppuccin/tmux/blob/main/README.md

Add the plugin to your TPM configuration and optionally set the color flavor.

```bash
set -g @plugin 'catppuccin/tmux#v2.3.0' # See https://github.com/catppuccin/tmux/tags for additional tags
# ...alongside
set -g @plugin 'tmux-plugins/tpm'
```

```bash
set -g @catppuccin_flavor 'mocha' # latte, frappe, macchiato or mocha
```

--------------------------------

### Custom flavor reset configuration

Source: https://github.com/catppuccin/tmux/blob/main/docs/tutorials/03-resetting-theme.md

Configuration examples for resetting the theme when custom options are applied, requiring re-initialization.

```sh
# somewhere in a Tmux configuration file that will be sourced specifically for
# reloading `catppuccin/tmux`.
set -g @catppuccin_flavor "latte"
set -g @catppuccin_reset "true"
run /path/to/catppuccin/tmux/catppuccin.tmux
# we're not done yet!
```

```sh
# somewhere in a Tmux configuration file that will be sourced specifically for
# reloading `catppuccin/tmux`.
set -g @catppuccin_flavor "mocha"
set -g @catppuccin_reset "true"
run /path/to/catppuccin/tmux/catppuccin.tmux
```

--------------------------------

### Manual Installation of Catppuccin Tmux Theme

Source: https://context7.com/catppuccin/tmux/llms.txt

Clone the repository and add the plugin to your tmux.conf. Remember to reload your tmux configuration after making changes.

```bash
# Clone the repository
mkdir -p ~/.config/tmux/plugins/catppuccin
git clone -b v2.3.0 https://github.com/catppuccin/tmux.git ~/.config/tmux/plugins/catppuccin/tmux

# Add to ~/.tmux.conf
set -g @catppuccin_flavor 'mocha'  # latte, frappe, macchiato, or mocha
run ~/.config/tmux/plugins/catppuccin/tmux/catppuccin.tmux

# Reload tmux configuration
tmux source ~/.tmux.conf
```

--------------------------------

### TPM Installation of Catppuccin Tmux Theme

Source: https://context7.com/catppuccin/tmux/llms.txt

Install using Tmux Plugin Manager (TPM) for automatic updates. Ensure TPM is installed and configured separately.

```bash
# Add to ~/.tmux.conf
set -g @plugin 'catppuccin/tmux#v2.3.0'
set -g @plugin 'tmux-plugins/tpm'

# Optional: Set flavor before loading
set -g @catppuccin_flavor 'mocha'

# Run TPM
run '~/.tmux/plugins/tpm/tpm'
```

--------------------------------

### Recommended Tmux Full Configuration with Catppuccin

Source: https://context7.com/catppuccin/tmux/llms.txt

A comprehensive Tmux configuration including basic settings, Catppuccin theme setup, status line configuration, and integration with other plugins like tmux-cpu and tmux-battery.

```tmux
# ~/.tmux.conf

# Basic tmux settings
set -g mouse on
set -g default-terminal "tmux-256color"

# Catppuccin configuration (set BEFORE loading plugin)
set -g @catppuccin_flavor "mocha"
set -g @catppuccin_window_status_style "rounded"
set -g @catppuccin_window_text "#W"
set -g @catppuccin_window_current_text "#W"
set -g @catppuccin_window_flags "icon"

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

# Status line configuration (set AFTER loading plugin)
set -g status-right-length 100
set -g status-left-length 100
set -g status-left ""
set -g status-right "#{E:@catppuccin_status_application}"
set -agF status-right "#{E:@catppuccin_status_cpu}"
set -agF status-right "#{E:@catppuccin_status_ram}"
set -ag status-right "#{E:@catppuccin_status_session}"
set -ag status-right "#{E:@catppuccin_status_uptime}"
set -agF status-right "#{E:@catppuccin_status_battery}"

# Load additional plugins (if using TPM)
set -g @plugin 'tmux-plugins/tmux-cpu'
set -g @plugin 'tmux-plugins/tmux-battery'
run '~/.tmux/plugins/tpm/tpm'
```

--------------------------------

### Configure pomodoro module

Source: https://github.com/catppuccin/tmux/blob/main/docs/reference/status-line.md

Requires the tmux-pomodoro-plus plugin installed via TPM.

```sh
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'
```

--------------------------------

### Configure tmux-clima module

Source: https://github.com/catppuccin/tmux/blob/main/docs/reference/status-line.md

Requires the tmux-clima plugin installed via TPM.

```sh
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'
```

--------------------------------

### Display Memory Pressure with Icons

Source: https://github.com/catppuccin/tmux/blob/main/docs/tutorials/02-custom-status.md

Shows memory pressure percentage on MacOS using Catppuccin theme colors and icons. This example requires specific tmux configuration and potentially external commands like 'memory_pressure'.

```sh
set -g status-right "#[bg=#{@thm_flamingo},fg=#{@thm_crust}]#[reverse]#[noreverse]󱀙  "
set -ag status-right "#[fg=#{@thm_fg},bg=#{@thm_mantle}] #(memory_pressure | awk '/percentage/{print $5}') "
```

--------------------------------

### Remove Date Time Module Icon

Source: https://github.com/catppuccin/tmux/blob/main/docs/reference/status-line.md

Example of removing the icon from the date_time module.

```tmux
set -g @catppuccin_date_time_icon ""
```

--------------------------------

### Configure basic tmux settings

Source: https://github.com/catppuccin/tmux/blob/main/docs/tutorials/01-getting-started.md

Sets the color flavor and initializes the plugin in the .tmux.conf file.

```bash
set -g @catppuccin_flavor 'mocha'

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

--------------------------------

### Default configuration options

Source: https://github.com/catppuccin/tmux/blob/main/docs/reference/configuration.md

A comprehensive list of default settings for menu, pane, and window styling in the Catppuccin Tmux plugin.

```bash
# Menu styling options
set -g @catppuccin_menu_selected_style "fg=#{@thm_fg},bold,bg=#{@thm_overlay_0}"

# Pane styling options
set -g @catppuccin_pane_status_enabled "no" # set to "yes" to enable
set -g @catppuccin_pane_border_status "off" # set to "yes" to enable
set -g @catppuccin_pane_border_style "fg=#{@thm_overlay_0}"
set -g @catppuccin_pane_active_border_style "##{?pane_in_mode,fg=#{@thm_lavender},##{?pane_synchronized,fg=#{@thm_mauve},fg=#{@thm_lavender}}}"
set -g @catppuccin_pane_left_separator "█"
set -g @catppuccin_pane_middle_separator "█"
set -g @catppuccin_pane_right_separator "█"
set -g @catppuccin_pane_color "#{@thm_green}"
set -g @catppuccin_pane_background_color "#{@thm_surface_0}"
set -g @catppuccin_pane_default_text "##{b:pane_current_path}"
set -g @catppuccin_pane_default_fill "number"
set -g @catppuccin_pane_number_position "left" # right, left

set -g @catppuccin_window_status_style "basic" # basic, rounded, slanted, custom, or none
set -g @catppuccin_window_text_color "#{@thm_surface_0}"
set -g @catppuccin_window_number_color "#{@thm_overlay_2}"
set -g @catppuccin_window_text " #T"
set -g @catppuccin_window_number "#I"
set -g @catppuccin_window_current_text_color "#{@thm_surface_1}"
set -g @catppuccin_window_current_number_color "#{@thm_mauve}"
set -g @catppuccin_window_current_text " #T"
set -g @catppuccin_window_current_number "#I"
set -g @catppuccin_window_number_position "left"
set -g @catppuccin_window_flags "none" # none, icon, or text
set -g @catppuccin_window_flags_icon_last " 󰖰" # -
set -g @catppuccin_window_flags_icon_current " 󰖯" # *
set -g @catppuccin_window_flags_icon_zoom " 󰁌" # Z
set -g @catppuccin_window_flags_icon_mark " 󰃀" # M
set -g @catppuccin_window_flags_icon_silent " 󰂛" # ~
set -g @catppuccin_window_flags_icon_activity " 󱅫" # #
set -g @catppuccin_window_flags_icon_bell " 󰂞" # !
```

--------------------------------

### Configure CPU Module with TPM

Source: https://github.com/catppuccin/tmux/blob/main/docs/reference/status-line.md

Integrate the tmux-cpu plugin with Catppuccin theme. Load the theme, append the CPU module to status-right, and then initialize TPM.

```tmux
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'
```

--------------------------------

### Configure Window Flags

Source: https://context7.com/catppuccin/tmux/llms.txt

Enable and customize indicators for window states like zoom, activity, or bells.

```bash
# ~/.tmux.conf

# Enable window flags
set -g @catppuccin_window_flags "icon"  # none, icon, or text

# Customize individual flag icons
set -g @catppuccin_window_flags_icon_last " 󰖰"     # Last active window
set -g @catppuccin_window_flags_icon_current " 󰖯" # Current window
set -g @catppuccin_window_flags_icon_zoom " 󰁌"    # Zoomed pane
set -g @catppuccin_window_flags_icon_mark " 󰃀"    # Marked window
set -g @catppuccin_window_flags_icon_silent " 󰂛" # Silence monitoring
set -g @catppuccin_window_flags_icon_activity " 󱅫" # Activity alert
set -g @catppuccin_window_flags_icon_bell " 󰂞"   # Bell alert

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

--------------------------------

### Add Kubernetes Module

Source: https://context7.com/catppuccin/tmux/llms.txt

Shows the current Kubernetes context and namespace. Requires tmux-kubectx plugin. Set colors before loading Catppuccin.

```tmux
# ~/.tmux.conf

# Set colors before loading catppuccin
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'
```

--------------------------------

### Configuring Catppuccin Application Module

Source: https://context7.com/catppuccin/tmux/llms.txt

Display the current pane command in the status line using the application module. Customize the icon and color using `@catppuccin_application_icon` and `@catppuccin_application_color`.

```bash
# ~/.tmux.conf
run ~/.config/tmux/plugins/catppuccin/tmux/catppuccin.tmux

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

# Customize the module
set -g @catppuccin_application_icon "󰣆 "
set -g @catppuccin_application_color "#{@thm_maroon}"
```

--------------------------------

### Configure RAM Module with TPM

Source: https://github.com/catppuccin/tmux/blob/main/docs/reference/status-line.md

Integrate the tmux-cpu plugin (for RAM usage) with Catppuccin theme. Load the theme, append the RAM module to status-right, and then initialize TPM.

```tmux
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'
```

--------------------------------

### Clone the Catppuccin repository

Source: https://github.com/catppuccin/tmux/blob/main/docs/tutorials/01-getting-started.md

Creates the plugin directory and clones the repository into the local tmux configuration path.

```bash
mkdir -p ~/.config/tmux/plugins/catppuccin
git clone -b v2.3.0 https://github.com/catppuccin/tmux.git ~/.config/tmux/plugins/catppuccin/tmux
```

--------------------------------

### Configure gitmux module

Source: https://github.com/catppuccin/tmux/blob/main/docs/reference/status-line.md

Integrates gitmux for git status display, requiring a configuration file at ~/.gitmux.conf.

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

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

```yaml
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}]"
```

--------------------------------

### Configure Battery Module with TPM

Source: https://github.com/catppuccin/tmux/blob/main/docs/reference/status-line.md

Integrate the tmux-battery plugin with Catppuccin theme. Load the theme, append the battery module to status-right, and then initialize TPM.

```tmux
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'
```

--------------------------------

### Configure Weather Module with TPM

Source: https://github.com/catppuccin/tmux/blob/main/docs/reference/status-line.md

Integrate the tmux-weather plugin with Catppuccin theme. Load the theme, append the weather module to status-right, and then initialize TPM.

```tmux
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'
```

--------------------------------

### Run Catppuccin Tmux Script

Source: https://github.com/catppuccin/tmux/blob/main/docs/tutorials/03-resetting-theme.md

Execute the main Catppuccin Tmux configuration script. This command should be run after setting the desired options to apply the theme.

```sh
run /path/to/catppuccin/tmux/catppuccin.tmux
```

--------------------------------

### Minimal flavor reset configuration

Source: https://github.com/catppuccin/tmux/blob/main/docs/tutorials/03-resetting-theme.md

Basic configuration for resetting the theme flavor when using default settings.

```sh
# somewhere in a Tmux configuration file that will be sourced specifically for
# reloading `catppuccin/tmux`.
set -g @catppuccin_flavor "latte"
set -g @catppuccin_reset "true"
run /path/to/catppuccin/tmux/catppuccin.tmux
```

--------------------------------

### Configure Window Text Format

Source: https://github.com/catppuccin/tmux/blob/main/docs/guides/troubleshooting.md

Sets the display format for window names in the status bar. Use these options to customize the text shown for active and inactive windows.

```bash
set -g @catppuccin_window_text "#W"
set -g @catppuccin_window_current_text "#W"
```

--------------------------------

### Style Pane Borders

Source: https://context7.com/catppuccin/tmux/llms.txt

Configure pane border appearance and status display options.

```bash
# ~/.tmux.conf

# Enable pane status (shows pane info in border)
set -g @catppuccin_pane_status_enabled "yes"
set -g @catppuccin_pane_border_status "top"  # off, top, bottom

# Customize pane border colors
set -g @catppuccin_pane_border_style "fg=#{@thm_overlay_0}"
set -g @catppuccin_pane_active_border_style "fg=#{@thm_lavender}"

# Customize pane status separators
set -g @catppuccin_pane_left_separator "█"
set -g @catppuccin_pane_middle_separator "█"
set -g @catppuccin_pane_right_separator "█"

# Pane status content
set -g @catppuccin_pane_default_text "#{b:pane_current_path}"
set -g @catppuccin_pane_color "#{@thm_green}"
set -g @catppuccin_pane_number_position "left"  # left or right

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

--------------------------------

### Add Host and User Modules

Source: https://context7.com/catppuccin/tmux/llms.txt

Displays the current hostname and username in the status line. Optional customization for icons and colors.

```tmux
# ~/.tmux.conf
run ~/.config/tmux/plugins/catppuccin/tmux/catppuccin.tmux

# Add user and host modules
set -ag status-right "#{E:@catppuccin_status_user}"
set -ag status-right "#{E:@catppuccin_status_host}"

# Customize (optional)
set -g @catppuccin_host_icon "󰒋 "
set -g @catppuccin_host_color "#{@thm_mauve}"
set -g @catppuccin_user_icon " "
set -g @catppuccin_user_color "#{@thm_sky}"
```

--------------------------------

### Configuring Catppuccin Session Module

Source: https://context7.com/catppuccin/tmux/llms.txt

Display the current tmux session name with a prefix indicator. The session module changes color based on whether the prefix key is active.

```bash
# ~/.tmux.conf
run ~/.config/tmux/plugins/catppuccin/tmux/catppuccin.tmux

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

--------------------------------

### Setting Catppuccin Color Flavor

Source: https://context7.com/catppuccin/tmux/llms.txt

Configure the Catppuccin color palette by setting the `@catppuccin_flavor` option before loading the plugin. Options include latte, frappe, macchiato, and mocha.

```bash
# ~/.tmux.conf

# Choose your preferred flavor
set -g @catppuccin_flavor 'frappe'  # Options: latte, frappe, macchiato, mocha

# Load the plugin after setting options
run ~/.config/tmux/plugins/catppuccin/tmux/catppuccin.tmux
```

--------------------------------

### Recommended Default Tmux Configuration

Source: https://github.com/catppuccin/tmux/blob/main/README.md

A recommended default configuration for the Catppuccin Tmux plugin, including mouse support, terminal settings, flavor selection, and status line customization. Load additional plugins like tmux-cpu and tmux-battery if needed.

```tmux
# ~/.tmux.conf

# Options to make tmux more pleasant
set -g mouse on
set -g default-terminal "tmux-256color"

# Configure the catppuccin plugin
set -g @catppuccin_flavor "mocha"
set -g @catppuccin_window_status_style "rounded"

# Load catppuccin
run ~/.config/tmux/plugins/catppuccin/tmux/catppuccin.tmux
# For TPM, instead use `run ~/.tmux/plugins/tmux/catppuccin.tmux`

# Make the status line pretty and add some modules
set -g status-right-length 100
set -g status-left-length 100
set -g status-left ""
set -g status-right "#{E:@catppuccin_status_application}"
set -agF status-right "#{E:@catppuccin_status_cpu}"
set -agF status-right "#{E:@catppuccin_status_ram}"
set -ag status-right "#{E:@catppuccin_status_session}"
set -ag status-right "#{E:@catppuccin_status_uptime}"
set -agF status-right "#{E:@catppuccin_status_battery}"

run ~/.config/tmux/plugins/tmux-plugins/tmux-cpu/cpu.tmux
run ~/.config/tmux/plugins/tmux-plugins/tmux-battery/battery.tmux
# Or, if using TPM, just run TPM

```

--------------------------------

### Create Custom Status Module

Source: https://context7.com/catppuccin/tmux/llms.txt

Defines and uses a custom status line module with Catppuccin styling. Define properties before sourcing the utility and loading Catppuccin.

```tmux
# ~/.tmux.conf - Add BEFORE loading catppuccin

# Define custom module
%hidden MODULE_NAME="my_custom_module"

set -g "@catppuccin_${MODULE_NAME}_icon" " "
set -gF "@catppuccin_${MODULE_NAME}_color" "#{E:@thm_pink}"
set -g "@catppuccin_${MODULE_NAME}_text" "#{pane_current_command}"

# Source the module utility (adjust path as needed)
source ~/.config/tmux/plugins/catppuccin/tmux/utils/status_module.conf

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

# Use your custom module
set -g status-right "#{E:@catppuccin_status_application}#{E:@catppuccin_status_my_custom_module}"
```

--------------------------------

### Add Directory Module

Source: https://context7.com/catppuccin/tmux/llms.txt

Shows the current pane's working directory in the status line. Customize the icon, color, and text format.

```tmux
# ~/.tmux.conf
run ~/.config/tmux/plugins/catppuccin/tmux/catppuccin.tmux

set -ag status-right "#{E:@catppuccin_status_directory}"

# Customize (optional)
set -g @catppuccin_directory_icon " "
set -g @catppuccin_directory_color "#{@thm_rosewater}"
set -g @catppuccin_directory_text " #{b:pane_current_path}"  # basename only
```

--------------------------------

### Catppuccin Pane Border Format (Mocha)

Source: https://github.com/catppuccin/tmux/blob/main/tests/pane_styling_expected.txt

Sets the pane border format using Catppuccin Mocha colors, displaying pane index and current path.

```tmux
pane-border-format #[fg=#313244,bg=default]█#[fg=#a6e3a1,bg=#313244]#{b:pane_current_path} #[fg=#a6e3a1,bg=#313244]█#[fg=#313244,bg=#a6e3a1]#{pane_index}#[fg=#a6e3a1,bg=default]█
```

--------------------------------

### Configure kube module

Source: https://github.com/catppuccin/tmux/blob/main/docs/reference/status-line.md

Requires the tmux-kubectx plugin and allows customization of context and namespace colors.

```sh
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'
```

--------------------------------

### Configuring Catppuccin Window Status Style

Source: https://context7.com/catppuccin/tmux/llms.txt

Customize the appearance of window tabs in the status line using the `@catppuccin_window_status_style` option. Styles include basic, rounded, slanted, custom, and none. You can also customize active window colors and window text format.

```bash
# ~/.tmux.conf

# Set window style before loading plugin
set -g @catppuccin_window_status_style "rounded"  # basic, rounded, slanted, custom, none

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

# Optional: Change the active window highlight color (default is mauve)
set -g @catppuccin_window_current_number_color "#{@thm_lavender}"

# Custom window text format
set -g @catppuccin_window_text "#W"  # Show window name instead of pane title
set -g @catppuccin_window_current_text "#W"

# Enable window flags with icons
set -g @catppuccin_window_flags "icon"  # none, icon, or text
```

--------------------------------

### Configure load module

Source: https://github.com/catppuccin/tmux/blob/main/docs/reference/status-line.md

Enables the system load status module in the tmux status bar.

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

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

--------------------------------

### Legacy Configuration for Tmux < 3.2

Source: https://github.com/catppuccin/tmux/blob/main/README.md

Manually define color variables and apply them to status line and window styles for older Tmux versions.

```sh
# In your ~/.tmux.conf

# Add the colors from the pallete. Check the themes/ directory for all options.

# Some basic mocha colors.
set -g @ctp_bg "#24273a"
set -g @ctp_surface_1 "#494d64"
set -g @ctp_fg "#cad3f5"
set -g @ctp_mauve "#c6a0f6"
set -g @ctp_crust "#181926"

# status line
set -gF status-style "bg=#{@ctp_bg},fg=#{@ctp_fg}"

# windows
set -gF window-status-format "#[bg=#{@ctp_surface_1},fg=#{@ctp_fg}] ##I ##T "
set -gF window-status-current-format "#[bg=#{@ctp_mauve},fg=#{@ctp_crust}] ##I ##T "
```

--------------------------------

### Set Catppuccin Tmux Flavor and Options

Source: https://github.com/catppuccin/tmux/blob/main/docs/tutorials/03-resetting-theme.md

Configure the Catppuccin theme flavor, window status style, text, number, and pane status settings. These options define the visual appearance of the Tmux status bar.

```sh
set -g @catppuccin_flavor "mocha"
set -g @catppuccin_window_status_style "basic"
set -g @catppuccin_window_text " #W"
set -g @catppuccin_window_number "#I"
set -g @catppuccin_window_current_text " #W"
set -g @catppuccin_window_current_number "#I"
set -g @catppuccin_pane_status_enabled "yes"
set -g @catppuccin_pane_border_status "yes"
set -g @catppuccin_window_number_position "right"
set -g @catppuccin_window_current_text "#{pane_current_path}"
set -g @catppuccin_pane_left_separator "▓"
set -g @catppuccin_pane_middle_separator "▓"
set -g @catppuccin_pane_right_separator "▓"
set -g @catppuccin_status_left_separator "▓"
set -g @catppuccin_status_middle_separator "▓"
set -g @catppuccin_status_right_separator "▓"
set -g @catppuccin_status_right_separator_inverse "no"
set -g @catppuccin_status_connect_separator "yes"
set -g @catppuccin_window_status_enable "yes"
set -g @catppuccin_status_fill "icon"
set -g @catppuccin_window_flags "icon"
set -g @catppuccin_application_icon " 󰣆  "
set -g @catppuccin_session_icon "   "
```

--------------------------------

### Bind Key with Themed Popup in Tmux

Source: https://context7.com/catppuccin/tmux/llms.txt

Creates a key binding to display a popup window with themed text and background colors, executing 'htop'.

```tmux
bind-key C-t display-popup -E -w 80% -h 80% \
  -S "fg=#{@thm_surface_1}" \
  -s "bg=#{@thm_bg},fg=#{@thm_fg}" \
  "htop"
```

--------------------------------

### Catppuccin Pane Border Format (Latte)

Source: https://github.com/catppuccin/tmux/blob/main/tests/pane_styling_expected.txt

Sets the pane border format using Catppuccin Latte colors, displaying pane index and current path.

```tmux
pane-border-format #[fg=#a6e3a1,bg=default]█#[fg=#313244,bg=#a6e3a1]#{pane_index}#[fg=#a6e3a1,bg=#313244]█ #[fg=#a6e3a1,bg=#313244]#{b:pane_current_path}#[fg=#313244,bg=default]█
```

--------------------------------

### Customize Session Colors

Source: https://context7.com/catppuccin/tmux/llms.txt

Optional configuration to set the color and icon for the Catppuccin Tmux session.

```tmux
set -g @catppuccin_session_color "#{?client_prefix,#{E:@thm_red},#{E:@thm_green}}"
set -g @catppuccin_session_icon " "
```

--------------------------------

### Add CPU Module

Source: https://context7.com/catppuccin/tmux/llms.txt

Displays CPU usage percentage in the status line. Requires the tmux-cpu plugin. Customize threshold colors.

```tmux
# ~/.tmux.conf
run ~/.config/tmux/plugins/catppuccin/tmux/catppuccin.tmux

# Add CPU module (use -agF for format expansion)
set -agF status-right "#{E:@catppuccin_status_cpu}"

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

# Optional: Customize threshold colors
set -g @cpu_low_fg_color "#{E:@thm_fg}"
set -g @cpu_high_bg_color "#{E:@thm_red}"
```

--------------------------------

### Configure Window Flags Icon Format

Source: https://github.com/catppuccin/tmux/blob/main/docs/reference/configuration.md

Sets the format for window flags using conditional logic to display specific icons based on window states.

```tmux
set -g @catppuccin_window_flags_icon_format "##{?window_activity_flag,#{E:@catppuccin_window_flags_icon_activity},}##{?window_bell_flag,#{E:@catppuccin_window_flags_icon_bell},}##{?window_silence_flag,#{E:@catppuccin_window_flags_icon_silent},}##{?window_active,#{E:@catppuccin_window_flags_icon_current},}##{?window_last_flag,#{E:@catppuccin_window_flags_icon_last},}##{?window_marked_flag,#{E:@catppuccin_window_flags_icon_mark},}##{?window_zoomed_flag,#{E:@catppuccin_window_flags_icon_zoom},} "
```

--------------------------------

### Catppuccin Pane Border Format (Macchiato)

Source: https://github.com/catppuccin/tmux/blob/main/tests/pane_styling_expected.txt

Sets the pane border format using Catppuccin Macchiato colors, displaying pane index and current path.

```tmux
pane-border-format #[fg=#a6e3a1,bg=default]█#[fg=#313244,bg=#a6e3a1]#{pane_index}#[fg=#a6e3a1,bg=#313244]█ #[fg=#313244,bg=#a6e3a1]#{b:pane_current_path}#[fg=#a6e3a1,bg=default]█
```

--------------------------------

### Set Tmux Status Line Modules

Source: https://github.com/catppuccin/tmux/blob/main/docs/reference/status-line.md

Use these commands to set the status-right and status-left options after loading the Catppuccin theme. Options are expanded using 'E:' prefix.

```tmux
set -g status-right-length 100

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

--------------------------------

### Catppuccin Pane Border Format (Cinnamon)

Source: https://github.com/catppuccin/tmux/blob/main/tests/pane_styling_expected.txt

Sets the pane border format using Catppuccin Cinnamon colors, displaying pane index and current path.

```tmux
pane-border-format #[fg=#313244,bg=default]█#[fg=#cdd6f4,bg=#313244]#{pane_index}#[fg=#cdd6f4,bg=#313244]█ #[fg=#cdd6f4,bg=#313244]#{b:pane_current_path}#[fg=#313244,bg=default]█
```

--------------------------------

### Customize window separators

Source: https://github.com/catppuccin/tmux/blob/main/docs/reference/configuration.md

Enables custom window styling by setting the style to 'custom' and defining specific separator characters.

```bash
set -g @catppuccin_window_status_style "custom"
set -g @catppuccin_window_left_separator ""
set -g @catppuccin_window_middle_separator ""
set -g @catppuccin_window_right_separator ""
```

--------------------------------

### Reference Theme Color Variables

Source: https://context7.com/catppuccin/tmux/llms.txt

List of available theme color variables accessible via the `#{@thm_<color>}` syntax.

```bash
# Available theme color variables:
# @thm_bg, @thm_fg
# @thm_rosewater, @thm_flamingo, @thm_pink, @thm_mauve
# @thm_red, @thm_maroon, @thm_peach, @thm_yellow
# @thm_green, @thm_teal, @thm_sky, @thm_sapphire, @thm_blue, @thm_lavender
# @thm_subtext_1, @thm_subtext_0
```

--------------------------------

### Tmux Window Status Format (Alternative)

Source: https://github.com/catppuccin/tmux/blob/main/tests/window_status_styling_expected.txt

An alternative format for inactive window statuses, prioritizing window title display before index, using Catppuccin theme colors.

```tmux
window-status-format #[fg=#cdd6f4,bg=#{@thm_surface_0}] #[fg=#cdd6f4,bg=#{@thm_surface_0}] #T #[fg=#11111b,bg=#{@thm_overlay_2}] #I
```

--------------------------------

### Add Gitmux Module

Source: https://context7.com/catppuccin/tmux/llms.txt

Displays Git repository status using Gitmux. Requires Gitmux and a custom ~/.gitmux.conf with Catppuccin colors.

```tmux
# ~/.tmux.conf
run ~/.config/tmux/plugins/catppuccin/tmux/catppuccin.tmux

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

# Create ~/.gitmux.conf with catppuccin colors:
# tmux:
#   styles:
#     clear: "#[fg=#{@thm_fg}]"
#     state: "#[fg=#{@thm_red},bold]"
#     branch: "#[fg=#{@thm_fg},bold]"
#     remote: "#[fg=#{@thm_teal}]"
#     staged: "#[fg=#{@thm_green},bold]"
#     modified: "#[fg=#{@thm_yellow},bold]"
#     untracked: "#[fg=#{@thm_mauve},bold]"
#     clean: "#[fg=#{@thm_rosewater},bold]"
```

--------------------------------

### Configure Status Background

Source: https://context7.com/catppuccin/tmux/llms.txt

Control the status bar background transparency and color settings.

```bash
# ~/.tmux.conf

# Use default theme background (mantle color)
set -g @catppuccin_status_background "default"

# Make status bar transparent
set -g @catppuccin_status_background "none"

# Use custom color (hex or theme variable)
set -g @catppuccin_status_background "#1e1e2e"
set -g @catppuccin_status_background "#{@thm_surface_0}"

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

--------------------------------

### Add RAM Module

Source: https://context7.com/catppuccin/tmux/llms.txt

Displays RAM usage percentage in the status line. Requires the tmux-cpu plugin, which also provides RAM monitoring.

```tmux
# ~/.tmux.conf
run ~/.config/tmux/plugins/catppuccin/tmux/catppuccin.tmux

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

# Load tmux-cpu plugin (provides both CPU and RAM)
set -g @plugin 'tmux-plugins/tmux-cpu'
run '~/.tmux/plugins/tpm/tpm'
```

--------------------------------

### Adding Built-in Status Modules to Tmux

Source: https://context7.com/catppuccin/tmux/llms.txt

Display information in the status bar by adding pre-configured modules to `status-left` or `status-right`. Use `#{E:@catppuccin_status_<module>}` syntax. Use `-ag` to append and `-agF` for modules with format strings.

```bash
# ~/.tmux.conf

# Load catppuccin first
run ~/.config/tmux/plugins/catppuccin/tmux/catppuccin.tmux

# Set status line length to accommodate modules
set -g status-right-length 100
set -g status-left-length 100

# Clear left side, add session to left
set -g status-left ""
set -g status-left "#{E:@catppuccin_status_session}"

# Add multiple modules to the right side
set -g status-right "#{E:@catppuccin_status_application}"
set -ag status-right "#{E:@catppuccin_status_directory}"
set -ag status-right "#{E:@catppuccin_status_session}"
set -ag status-right "#{E:@catppuccin_status_user}"
set -ag status-right "#{E:@catppuccin_status_host}"
set -ag status-right "#{E:@catppuccin_status_date_time}"
```

--------------------------------

### Configure Status Line Options

Source: https://github.com/catppuccin/tmux/blob/main/docs/reference/configuration.md

Defines separators, connection behavior, fill style, and background colors for the Tmux status line.

```tmux
set -g @catppuccin_status_left_separator ""
set -g @catppuccin_status_middle_separator ""
set -g @catppuccin_status_right_separator "█"
set -g @catppuccin_status_connect_separator "yes" # yes, no
set -g @catppuccin_status_fill "icon"
set -g @catppuccin_status_module_bg_color "#{@thm_surface_0}"
```

--------------------------------

### List of reset Tmux options

Source: https://github.com/catppuccin/tmux/blob/main/docs/tutorials/03-resetting-theme.md

A comprehensive list of all internal Tmux options that are unset when @catppuccin_reset is enabled.

```txt
@thm_bg
@thm_fg
@thm_rosewater
@thm_flamingo
@thm_rosewater
@thm_pink
@thm_mauve
@thm_red
@thm_maroon
@thm_peach
@thm_yellow
@thm_green
@thm_teal
@thm_sky
@thm_sapphire
@thm_blue
@thm_lavender
@thm_subtext_1
@thm_subtext_0
@thm_overlay_2
@thm_overlay_1
@thm_overlay_0
@thm_surface_2
@thm_surface_1
@thm_surface_0
@thm_mantle
@thm_crust
@catppuccin_window_status_style
@catppuccin_window_text_color
@catppuccin_window_number_color
@catppuccin_window_text
@catppuccin_window_number
@catppuccin_window_current_text_color
@catppuccin_window_current_number_color
@catppuccin_window_current_text
@catppuccin_window_current_number
@catppuccin_window_number_position
@catppuccin_window_flags
@catppuccin_window_flags_icon_last
@catppuccin_window_flags_icon_current
@catppuccin_window_flags_icon_zoom
@catppuccin_window_flags_icon_mark
@catppuccin_window_flags_icon_silent
@catppuccin_window_flags_icon_activity
@catppuccin_window_flags_icon_bell
@catppuccin_window_flags_icon_format
@catppuccin_status_left_separator
@catppuccin_status_middle_separator
@catppuccin_status_right_separator
@catppuccin_status_connect_separator
@catppuccin_status_module_text_bg
@catppuccin_window_current_left_separator
@catppuccin_window_current_middle_separator
@catppuccin_window_current_right_separator
```

--------------------------------

### Add Date and Time Module

Source: https://context7.com/catppuccin/tmux/llms.txt

Integrates the date and time into the Tmux status line. Customize the format, icon, and color.

```tmux
# ~/.tmux.conf
run ~/.config/tmux/plugins/catppuccin/tmux/catppuccin.tmux

set -ag status-right "#{E:@catppuccin_status_date_time}"

# Customize format (uses strftime format)
set -g @catppuccin_date_time_text " %Y-%m-%d %H:%M:%S"
set -g @catppuccin_date_time_icon "󰃰"
set -g @catppuccin_date_time_color "#{@thm_sapphire}"
```

--------------------------------

### Customize Module Appearance

Source: https://context7.com/catppuccin/tmux/llms.txt

Override default icons, colors, and text content for individual status modules.

```bash
# ~/.tmux.conf

# Override module icon (set to empty to remove)
set -g @catppuccin_application_icon "󰣆 "
set -g @catppuccin_session_icon ""  # Remove icon
set -g @catppuccin_date_time_icon ""

# Override module colors
set -g @catppuccin_application_color "#{@thm_blue}"
set -g @catppuccin_session_color "#{@thm_lavender}"

# Override module text content
set -g @catppuccin_date_time_text " %H:%M"  # Time only

# Override module background colors
set -g @catppuccin_status_application_bg_color "#{@thm_surface_0}"
set -g @catppuccin_status_module_bg_color "#{@thm_surface_0}"

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

--------------------------------

### Define and Integrate Custom Tmux Module

Source: https://github.com/catppuccin/tmux/blob/main/docs/tutorials/02-custom-status.md

Defines a custom tmux status module using Catppuccin theme variables and integrates it into the status line. This requires setting module-specific variables and sourcing the Catppuccin utility script before configuring the status line.

```sh
# In ~/.tmux.conf, before the catppuccin plugin has been loaded.

%hidden MODULE_NAME="my_custom_module"

set -g "@catppuccin_${MODULE_NAME}_icon" " "
set -gF "@catppuccin_${MODULE_NAME}_color" "#{E:@thm_pink}"
set -g "@catppuccin_${MODULE_NAME}_text" "#{pane_current_command}"

source "<path to catppuccin plugin>/utils/status_module.conf"

set -g status-right "#{E:@catppuccin_status_application}#{E:@catppuccin_status_my_custom_module}"
```

--------------------------------

### Tmux Current Window Status Format (Alternative)

Source: https://github.com/catppuccin/tmux/blob/main/tests/window_status_styling_expected.txt

An alternative format for the active window status, emphasizing the window title and using distinct Catppuccin colors for highlighting.

```tmux
window-status-current-format #[fg=#cdd6f4,bg=#{@thm_surface_1}] #[fg=#cdd6f4,bg=#{@thm_surface_1}] #T #[fg=#11111b,bg=#{@thm_mauve}] #I
```

--------------------------------

### Set menu selected style

Source: https://github.com/catppuccin/tmux/blob/main/docs/reference/configuration.md

Configures the visual style for selected items in the Tmux menu using theme variables.

```sh
# Use a value compatible with the standard tmux `menu-selected-style`
set -g @catppuccin_menu_selected_style "fg=#{@thm_surface_0},bg=#{@thm_yellow}"
```

--------------------------------

### Style Inline Status Line

Source: https://context7.com/catppuccin/tmux/llms.txt

Add custom content and styling to the status line using theme color variables.

```bash
# ~/.tmux.conf
run ~/.config/tmux/plugins/catppuccin/tmux/catppuccin.tmux

# Add custom styled content
set -g status-right "#[fg=#{@thm_crust},bg=#{@thm_teal}] #H "

# Combine with icons
set -g status-right "#[bg=#{@thm_flamingo},fg=#{@thm_crust}]#[reverse]#[noreverse]󱀙  "
set -ag status-right "#[fg=#{@thm_fg},bg=#{@thm_mantle}] #(memory_pressure | awk '/percentage/{print $5}') "

# Custom session display with colors
set -g status-left ""
set -g status-right '#[fg=#{@thm_crust},bg=#{@thm_teal}] session: #S '
set -g status-right-length 100
```

--------------------------------

### Auto-Switch Tmux Theme Flavors

Source: https://context7.com/catppuccin/tmux/llms.txt

Configures automatic theme flavor switching based on system light/dark theme detection using tmux hooks. Ensure `@catppuccin_reset "true"` is set before reloading the theme.

```tmux
set-hook -g client-dark-theme {
  set -g @catppuccin_flavor "frappe"
  set -g @catppuccin_reset "true"
  run ~/path/to/catppuccin/tmux/catppuccin.tmux
}
```

```tmux
set-hook -g client-light-theme {
  set -g @catppuccin_flavor "latte"
  set -g @catppuccin_reset "true"
  run ~/path/to/catppuccin/tmux/catppuccin.tmux
}
```

--------------------------------

### Format a breaking change commit message

Source: https://github.com/catppuccin/tmux/blob/main/CONTRIBUTING.md

Use the <type>! syntax for breaking changes and include a BREAKING CHANGE footer for the changelog generator.

```text
feat(bar)!: foo the bars

BREAKING CHANGE: bars are now foo'ed
```

--------------------------------

### Configure current window number color

Source: https://github.com/catppuccin/tmux/blob/main/docs/reference/configuration.md

Sets the color of the active window number in the status bar.

```bash
set -g @catppuccin_window_current_number_color "#{@thm_lavender}"
```