themux

A themed, multi-theme status line for tmux.

Themes

themux ships three palette families — catppuccin, kanagawa and kanso — and adds its own component-based styling on top. Every flavor below is the same status line, swapped only by @themux_theme:

Catppuccin

@themux_theme	Preview
catppuccin_latte
catppuccin_frappe
catppuccin_macchiato
catppuccin_mocha

Kanagawa

@themux_theme	Preview
kanagawa_wave
kanagawa_dragon
kanagawa_lotus

Kanso

@themux_theme	Preview
kanso_zen
kanso_ink
kanso_mist
kanso_pearl

Multi-theme selection

This fork is a multi-theme manager: besides the catppuccin flavors, other themes can be selected with @themux_theme, which loads themes/<theme>.palette (a plain name hex palette — a legacy themes/<theme>_tmux.conf with set -ogq @thm_* still works for custom themes):

# Kanagawa (wave, dragon or lotus)
set -g @themux_theme 'kanagawa_dragon'

# Kanso (zen, ink, mist or pearl)
set -g @themux_theme 'kanso_zen'

# Catppuccin (latte, frappe, macchiato or mocha)
set -g @themux_theme 'catppuccin_frappe'

Available themes: catppuccin_latte, catppuccin_frappe, catppuccin_macchiato, catppuccin_mocha, kanagawa_wave, kanagawa_dragon, kanagawa_lotus, kanso_zen, kanso_ink, kanso_mist, kanso_pearl.

Preset looks

The same components compose into very different bars. Four to copy and tweak — each is just a theme plus a handful of @themux_* options.

Catppuccin classic — rounded pills with solid icon blocks, the signature look.

set -g @themux_theme "catppuccin_mocha"
set -g @themux_all_shape "rounded"
set -g @themux_module_leading_variant "solid"
set -g @themux_status_line_1 "windows / application cpu ram session uptime"

Nvim / lualine — powerline chevrons flushed to both terminal edges (the leading and trailing =), the way a neovim statusline fills the row.

set -g @themux_theme "kanagawa_wave"
set -g @themux_all_shape "powerline"
set -g @themux_status_line_1 "=session>application / windows / cpu<ram="

Slanted tabs — parallelogram caps on every item for an angled, tabbed bar.

set -g @themux_theme "kanso_zen"
set -g @themux_all_shape "slanted"
set -g @themux_status_line_1 "windows / cpu ram date_time"

Minimal — a fully transparent bar: naked blocks, no backgrounds, colored text only.

set -g @themux_theme "catppuccin_mocha"
set -g @themux_status_background "none"
set -g @themux_module_leading_variant "naked"
set -g @themux_module_text_variant    "naked"
set -g @themux_window_leading_variant "naked"
set -g @themux_window_text_variant    "naked"
set -g @themux_status_line_1 "windows / application cpu ram session"

Style variants

Every item of the UI — status modules, the window list, panes — is a component with independent props, so any combination is valid:

set -g @themux_module_shape           "rounded"
set -g @themux_module_leading_variant "solid"  # the icon/number block
set -g @themux_module_text_variant    "naked"  # the text block (windows: _name)
set -g @themux_module_notch           "off"

• shape — squared, rounded, slanted, powerline (blocks with square / round / slant / arrow caps — powerline is the classic powerline/lualine chevron ) or unstyled to leave the item untouched and build it by hand with the @thm_* palette. The window list under each shape:

  @themux_window_shape	Window list
  squared
  rounded
  slanted
  powerline

• leading / text — the icon-or-number block and the text block each take a style: solid (accent block), soft (grey block), subtle (grey block, accent text) or naked (transparent, accent text — pair with @themux_status_background "none"). A naked block keeps the shape's caps as an outline, so rounded leading + naked text reads as a capsule.

• notch — the leading↔text seam. off (default) is flat; > bakes the shape's cap with leading's colour tapering into text; < mirrors it, colours reversed (with the squared shape both draw the same full-block glyph — only the colour placement differs); auto (on is an alias) picks a direction per placement: zone-aware for modules/windows (left zone >, right zone <, centre off), position-aware for panes (leading_position left → >, right → <). A different axis from the connectors below — notch shapes the seam inside one item, connectors join between items. auto/on only resolve through the layout grammar; a module consumed directly (your own format, _prepend/_append) keeps no seam at all — see the Configuration Reference for why.

The text-block variant prop is @themux_<item>_text_variant for all three items; on windows the name content lives in @themux_window_name (the bare @themux_<name>_text is a module's text content, hence the _variant suffix).

Each of these per-item props defaults from a shared @themux_all_<prop>: set -g @themux_all_shape "rounded" shapes every item at once, a per-item value (e.g. @themux_window_shape "powerline") overrides it, and a per-module value (e.g. @themux_cpu_text_variant "subtle") overrides one module. Cascadable props: shape, leading_variant, text_variant, notch, leading_position, leading_active_variant, text_active_variant. The selected window/pane (or a module with _active_when, like session's prefix) re-renders with each part's _active_variant + _active_color — by default the same variant with the active colour swapped in.

Composition

The status line is built from up to five rows (@themux_status_line_1 … _5). Each row is split into zones by / — none gives one left column, one gives left + right, two gives left / center / right. A zone is a list of component names (a token NAME becomes the @themux_module_NAME segment) or the special token windows (the window list).

Connecting modules

The character between two module names decides whether they stay separate or merge into one shape, and how the seam between them looks. Below, ( ) stands for the shape's caps (rounded half-circles, powerline arrows, …):

Connector	Meaning	Sketch
space	two separate pills	( a )( b )
=	merge — flat (squared) seam	( a │ b )
>	merge — seam points right (a into b)	( a > b )
<	merge — seam points left (b into a)	( a < b )
|	separate pills + the modules divider	( a ) · ( b )

=, > and < build a group: a run of modules under a single pair of outer caps, with the chosen seam between each. A space or a | ends the group, so the next module opens a fresh pill.

#                             one merged pill   own pill
set -g @themux_status_line_1 "cpu=ram=swap / windows / gitmux"

Directions mix freely: a>b<c makes b the peak (it pushes into both neighbours), a<b>c makes it the valley.

Note

Connectors need a shape with caps. squared uses a square █ cap, while rounded, slanted, and powerline use taper glyphs. Only unstyled has no caps, so there =/>/< collapse to a plain space.

Flushing to the terminal edge

For the lualine/nvim look — flat outer edges with powerline seams inside — drop the bar's outermost edge cap so that block fills solid to the terminal border instead of tapering. It is part of the line grammar: a leading = on a row's left zone, a trailing = on its right zone.

set -g @themux_module_shape "powerline"
set -g @themux_status_line_1 "=session>application / windows / cpu<ram="
#                            ^ flush left zone        flush right zone ^

It is the same = that flat-merges two modules, carried out to the bar's edge: one marker flushes whatever sits there — a module group or a leading/trailing windows token. It is per row, so each line flushes independently. squared drops its square █ cap; rounded/slanted/powerline drop their taper cap. unstyled has no cap to drop.

Rows render up to the last non-empty line, so a blank ("") line in between becomes an empty row — handy for spacing. The window list aligns to its zone:

set -g @themux_status_line_1 "session / gitmux date_time"   # left + right
set -g @themux_status_line_2 ""                             # blank row
set -g @themux_status_line_3 "windows"                      # windows, own row

Prepend / append

@themux_status_line_<N>_prepend and _append pin arbitrary content to a row's far left / far right — any tmux format (text, an emoji, #{...}, #[styles]), useful for padding:

set -g @themux_status_line_2_prepend "  "    # 2-space left pad on row 2
set -g @themux_status_line_2_append  " 🚀"

Note

A prepend/append occupies the row edge, so the edge item no longer touches the terminal border: a prepend cancels that line's left flush (the leading =), an append cancels the right (the trailing =). Drop the prepend/append (or the flush marker) if you need the edge-to-edge look on that row.

The divider between status modules and the divider between windows are configured independently:

set -g @themux_module_divider " | "            # what "|" inserts
set -g @themux_module_divider_color "#{@thm_overlay_0}"
set -g @themux_window_divider " "                     # window-status-separator
set -g @themux_window_divider_color "#{@thm_overlay_0}"

Status-line items merge into a powerline run only through the explicit =/>/< connectors above; those connectors can bridge modules and the windows token in the same zone. The windows inside the list merge with each other through one option — it is a uniform list, so there is nothing to annotate inline — @themux_window_seam, with symbols mirroring the connectors:

@themux_window_seam	Window list
| (default)	separate pills, with @themux_window_divider between
<>	one ribbon, raised (active window over both neighbours)
> / <	one ribbon, seam points right / left
=	one ribbon, flat (squared) seams

Any value but | joins the list into a ribbon (needs a capped shape + left numbers); @themux_window_divider then only supplies the separator for |.

Note

The connected window ribbon (@themux_window_seam <>/>/</=) colours each seam from its neighbour and caps the first window using the window index, both of which assume contiguous window indices. Pair it with:

set -g renumber-windows on

so killing a middle window never leaves a gap. Without it, the seam and left cap next to a gap render incorrectly until you renumber.

Pane status

Off by default. @themux_pane_status is the master switch for the styled label on each pane border — set it to top or bottom to enable (setting @themux_pane_shape only picks the look, never turns it on). With off themux draws no pane label, but its reset still clears pane-border-style / pane-active-border-style to tmux's defaults on every load — so set your own pane border styles after themux.tmux if you want them (the @themux_pane_border_style options only apply while the label is enabled).

set -g @themux_pane_status "top"                                  # off | top | bottom
set -g @themux_pane_shape "rounded"                              # squared | rounded | slanted | powerline | unstyled
set -g @themux_pane_leading_active_color "#{@thm_green}"        # active number accent
set -g @themux_pane_text_active_color "#{@thm_green}"            # active label accent
set -g @themux_pane_leading_active_variant "solid"             # solid | soft | subtle | naked
set -g @themux_pane_default_text "#{b:pane_current_path}"         # label text
set -g @themux_pane_leading_position "left"                     # left | right

Window names

@themux_window_name_mode controls when a window shows its name:

set -g @themux_window_name_mode "always"  # always | never | manual

• always — the name is always shown.
• never — only the number block.
• manual — the name shows only on windows you renamed by hand (tmux's automatic-rename off); auto-named windows show just the number.

Naked style

By default status modules render as "pills" — icon and text blocks with their own backgrounds — even when @themux_status_background is "none" (that option only clears the bar itself). For a fully transparent status line, set the naked style: blocks become colored text on the default background.

# Before loading the plugin
set -g @themux_module_leading_variant "naked"
set -g @themux_module_text_variant    "naked"  # transparent modules
set -g @themux_window_leading_variant "naked"
set -g @themux_window_text_variant    "naked"  # naked window list to match
set -g @themux_status_background "none"

naked is per part, so it pairs with any shape and with the other styles: a rounded shape keeps the bare bar but outlines each item with the rounded caps, and a solid leading + naked text gives a colored chip with a transparent label. Each module's icon and text take the module color (@themux_<module>_color), so all the existing modules and per-module options keep working — only the rendering changes.

Extra named dividers can be created from the template (after loading the plugin) and then dropped into a zone as a token:

%hidden DIVIDER_NAME="dot"
set -g @themux_dot_text "·"
source -F "~/.config/tmux/plugins/themux/utils/divider.conf"

set -g @themux_status_line_1 "session dot application / windows / date_time"

This fork also adds a zoom status module (#{E:@themux_module_zoom}) that renders only while the active pane is zoomed, in both pill and naked styles.

Clean reloads

themux resets its own derived state automatically when it loads: on a running server themux.tmux clears the palette, internals, the derived separators and the status/window/pane formats before rebuilding — but never your @themux_* config. So switching theme or style is just a config reload; no tmux kill-server, no reset file to source.

set -g @themux_theme 'kanagawa_dragon'
# ... options ...
run ~/.config/tmux/plugins/themux/themux.tmux  # resets + rebuilds

Installation

In order to have the icons displayed correctly please use/update your favorite nerd font. If you do not have a patched font installed, you can override or remove any icon. Check the documentation on the options available.

Manual (Recommended)

This method is recommended as TPM has some issues with name conflicts.

1. Clone this repository to your desired location (e.g. ~/.config/tmux/plugins/themux).

   mkdir -p ~/.config/tmux/plugins
   git clone https://github.com/jals1212/themux.git ~/.config/tmux/plugins/themux

2. Add the following line to your tmux.conf file: run ~/.config/tmux/plugins/themux/themux.tmux.

3. Reload Tmux by either restarting or reloading with tmux source ~/.tmux.conf.

Check out what to do next in the "Getting Started Guide".

TPM

1. Install TPM

2. Add the themux plugin:

   set -g @plugin 'jals1212/themux'
   # ...alongside
   set -g @plugin 'tmux-plugins/tpm'

3. (Optional) Set your preferred theme, it defaults to catppuccin_mocha:

   set -g @themux_theme 'catppuccin_mocha'

Important

You may have to run ~/.config/tmux/plugins/tpm/bin/clean_plugins if upgrading from an earlier version (especially from v0.3.0).

Requirements

themux needs tmux ≥ 3.6. Its variant rendering relies on format-resolution behaviour that older builds get wrong: on tmux 3.4 module styles resolve empty, leaving segments uncoloured. (3.6 also enables the automatic dark/light theme switching below.)

Automatic dark/light theme switching

This plugin can be used in conjunction with the support for tmux to automatically report dark or light themes using hooks. You can leverage these hooks in your tmux configuration file like so:

set-hook -g client-dark-theme {
  set -g @themux_theme "catppuccin_frappe"
  run ~/.config/tmux/plugins/themux/themux.tmux
}
set-hook -g client-light-theme {
  set -g @themux_theme "catppuccin_latte"
  run ~/.config/tmux/plugins/themux/themux.tmux
}

The above is only possible with versions of tmux 3.6+. To replicate this functionality with versions prior to 3.6, you will need to set variables and run the themux.tmux file and trigger it yourself. If you'd like some inspiration for how to do this, read through the Bash code found in this Nix function here which reloads Catppuccin on-demand without relying on tmux hooks.

Important

As mentioned in the comments in the conf snippet above, you may find that you'll need to add to the list of @themux_* variables. Test your configuration by switching themes and noting what of the Tmux session isn't getting reset to an expected color.

Upgrading from v0.3

Breaking changes have been introduced since 0.3, to understand how to migrate your configuration, see pinned issue #487.

Recommended Default Configuration

This configuration shows some customisation options, that can be further extended as desired. This is what is used for the previews above.

# ~/.tmux.conf

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

# Configure the themux plugin
set -g @themux_theme "catppuccin_mocha"
set -g @themux_window_shape "rounded"

# Compose the status line. Modules are NAME tokens placed inside the row grammar
# ("<left> / windows / <right>"); see the Status Line guide for the full grammar.
set -g @themux_status_line_1 "windows / application cpu ram session uptime"

# Plugins via TPM. TPM exports TMUX_PLUGIN_MANAGER_PATH, so themux can find
# tmux-cpu — the cpu and ram modules read its live values.
set -g @plugin 'tmux-plugins/tpm'
set -g @plugin 'tmux-plugins/tmux-cpu'
set -g @plugin 'jals1212/themux'

run '~/.config/tmux/plugins/tpm/tpm'

Documentation

Guides

• Getting Started
• Custom Status Line Segments
• Troubleshooting

Reference

• Status Line
• Configuration Options Reference
• Tmux Configuration Showcase

💝 Credits

themux is a multi-theme fork of catppuccin/tmux — the module system, status-line architecture, and the catppuccin palettes are their work (MIT, Copyright © Catppuccin Org).

The bundled palettes are derived from their upstream colour schemes: the catppuccin flavors (MIT, © Catppuccin), the kanagawa themes from rebelot/kanagawa.nvim (MIT, © rebelot), and the kanso themes from webhooked/kanso.nvim (MIT, © 2025 Webhooked).

Thanks to the original catppuccin/tmux contributors:

• Pocco81
• vinnyA3
• rogeruiz
• kales