DOCSEARCHbyAlgolia
Submit Docs

Catppuccin for Tmux

repository·main·Indexed 25 days ago

https://github.com/catppuccin/tmux

A theme plugin for the Tmux terminal multiplexer providing high-quality color palettes: Latte, Frappé, Macchiato, and Mocha. It includes customizable window status styles (basic, rounded, slanted), built-in status modules for CPU, RAM, and Battery, and support for Tmux Plugin Manager (TPM). Compatible with Tmux 3.2+ for direct plugin use, with manual palette configuration available for older versions.

Tokens
8.3K
Snippets
28
Records
37
Agent score
84%

What's inside catppuccin-tmux

  1. Configure the Kube module

    main

    The Kube module requires the tmux-kubectx plugin. You can also customize the context and namespace colors using Catppuccin theme variables.

    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'

  2. Configure the Battery module

    main

    The Battery module requires the tmux-battery plugin. Use set -agF to append the module to your status line.

    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'

  3. Use built-in Catppuccin status modules

    main

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

    Modules are accessed via variables prefixed with @catppuccin_status_<module_name>. When setting these in tmux, use the E: prefix to expand the options as format strings. If a module contains references to other variables (like the battery module), use the -gF flag (e.g., set -gF status-right ...) to ensure immediate expansion.

    set -g status-right-length 100

# Use E: to expand the module variables
set -g status-right "#{E:@catppuccin_status_application}#{E:@catppuccin_status_session}"
set -g status-left ""

  5. Apply custom configurations when resetting the flavor

    main

    Because resetting the theme unsets all custom styling, you must run the plugin twice in rapid succession: once to perform the reset with the new flavor, and a second time after re-applying your custom options.

    Failure to re-apply options like @catppuccin_window_text_color or @catppuccin_status_module_bg_color will result in the theme reverting to its default styling rather than your customized setup.

    # 1. Set the new flavor and trigger the reset
set -g @catppuccin_flavor "mocha"
set -g @catppuccin_reset "true"
run /path/to/catppuccin/tmux/catppuccin.tmux

# 2. Immediately re-apply all custom settings
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 "   "
set -g @catppuccin_window_text_color "#{@thm_surface_0}"
set -g @catppuccin_window_number_color "#{@thm_overlay_2}"
set -g @catppuccin_window_current_text_color "#{@thm_surface_1}"
set -g @catppuccin_window_current_number_color "#{@thm_mauve}"
set -g @catppuccin_status_module_bg_color "#{@thm_surface_0}"
set -g @catppuccin_status_application_icon_fg "#{E:@thm_crust}"
set -g @catppuccin_status_application_text_fg "#{E:@thm_fg}"
set -g @catppuccin_application_color "#{E:@thm_maroon}"
set -g @catppuccin_status_session_icon_fg "#{E:@thm_crust}"
set -g @catppuccin_status_session_text_fg "#{E:@thm_fg}"
set -g @catppuccin_session_color "#{?client_prefix,#{E:@thm_red},#{E:@thm_green}}"
set -g @catppuccin_status_module_text_bg "#{?@catppuccin_status_module_bg_color,#{E:@catppuccin_status_module_bg_color},#{@thm_surface_0}}"

# 3. Run the plugin again to apply the re-applied settings
run /path/to/catppuccin/tmux/catppuccin.tmux

  6. Configure Catppuccin for Tmux versions prior to 3.2

    main

    If you are using a Tmux version older than 3.2, you cannot use the plugin directly. Instead, manually add the palette colors to your ~/.tmux.conf and configure the status line and windows using those variables.

    # In your ~/.tmux.conf

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

  7. Reset the Catppuccin theme flavor

    main

    To change the theme flavor (e.g., switching from mocha to latte) or to clear existing styling, you can perform a reset of all styling options by setting the global option @catppuccin_reset to true.

    Warning: Resetting unsets all styling options associated with the Tmux-line. If you have custom configurations, they will be lost and must be reapplied immediately after the reset call. This is most useful for automated flavor switching.

    # Minimal example for resetting to a specific flavor
set -g @catppuccin_flavor "latte"
set -g @catppuccin_reset "true"
run /path/to/catppuccin/tmux/catppuccin.tmux

  8. Install Catppuccin for Tmux via TPM

    main

    To use Catppuccin with Tmux Plugin Manager (TPM):

    1. Ensure TPM is installed.
    2. Add the Catppuccin plugin to your tmux.conf: set -g @plugin 'catppuccin/tmux#v2.3.0'
    3. (Optional) Set your preferred flavor (defaults to mocha): set -g @catppuccin_flavor 'mocha'

    Important: If upgrading from an earlier version (especially v0.3.0), you may need to run ~/.config/tmux/plugins/tpm/bin/clean_plugins to avoid issues.

    set -g @plugin 'catppuccin/tmux#v2.3.0'
# ...alongside
set -g @plugin 'tmux-plugins/tpm'

# Optional: Set flavor
set -g @catppuccin_flavor 'mocha' # latte, frappe, macchiato or mocha

  9. Configure the Gitmux module

    main

    The Gitmux module requires the gitmux binary installed on your system.

    1. Install gitmux following its own documentation.
    2. Add the module to your status line in .tmux.conf.
    3. Create a ~/.gitmux.conf file and use the Catppuccin theme color variables (e.g., #{@thm_red}, #{@thm_teal}) to match the theme.
    # In .tmux.conf
run ~/.config/tmux/plugins/catppuccin/tmux/catppuccin.tmux
set -agF status-right "#{@catppuccin_status_gitmux}"
    # In ~/.gitmux.conf
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}]"

  10. Automate theme switching for Tmux 3.6+

    main

    For Tmux 3.6+, you can use hooks to automatically switch between light and dark Catppuccin flavors. When switching, it is recommended to set @catppuccin_reset to true. Note that you may need to set additional @catppuccin_* variables to ensure a full reset of all styles.

    set-hook -g client-dark-theme {
  set -g @catppuccin_flavor "frappe"
  set -g @catppuccin_reset "true"

  # NOTE: you may need to set more `@catppuccin_*` variables to fully reset
  # everything.

  run ~/code/github.com/catppuccin/tmux/catppuccin.tmux
}
set-hook -g client-light-theme {
  set -g @catppuccin_flavor "latte"
  set -g @catppuccin_reset "true"

  # NOTE: you may need to set more `@catppuccin_*` variables to fully reset
  # everything.

  run ~/code/github.com/catppuccin/tmux/catppuccin.tmux
}

  11. Install Catppuccin for Tmux manually (Recommended)

    main

    The manual installation method is recommended to avoid name conflicts with TPM.

    1. Clone the repository to your desired location (e.g., ~/.config/tmux/plugins/catppuccin).
    2. Add the following line to your tmux.conf: run ~/.config/tmux/plugins/catppuccin/tmux/catppuccin.tmux.
    3. Reload Tmux by restarting or running tmux source ~/.tmux.conf.

    Note: To display icons correctly, use or update to a Nerd Font.

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

  12. Create simple custom status line modules

    main
    You can add arbitrary content to your tmux status line using Catppuccin theme variables. Use the set -agF status-right or set -agF status-left commands in your ~/.tmux.conf to append custom modules. You can reference theme colors using the @thm_<color> syntax (e.g., #{@thm_teal}).