Part 1 covered the basics -- sessions, windows, panes, the prefix key. If you have not read it, start there. This part is about making tmux behave. The defaults are functional. They are not comfortable. Comfort requires a config.
How I Structure My Config
One tmux.conf file sourcing smaller, focused files. Not because the config is enormous -- it is not -- but because a single flat file gets unreadable fast when you are trying to track down why something is not working.
My structure:
The main tmux.conf does almost nothing itself. It just pulls everything in:
source-file ~/.config/tmux/conf/opts.conf
source-file ~/.config/tmux/conf/skin.conf
One line per concern. If something breaks, you know immediately which file to look in.
TPM -- The Plugin Manager
Before the options or the theme, tmux.conf needs the plugin manager. TPM (Tmux Plugin Manager) handles installing and loading plugins so you are not manually cloning repositories and sourcing files yourself.
Since my config already lives in ~/.config/tmux/, I keep TPM there too -- no point splitting tmux-related files across two locations:
git clone https://github.com/tmux-plugins/tpm ~/.config/tmux/plugins/tpm
Then add this to the bottom of your tmux.conf -- it must be last:
set -g @plugin 'tmux-plugins/tpm'
set -g @plugin 'tmux-plugins/tmux-sensible'
run '~/.config/tmux/plugins/tpm/tpm'
tmux-sensible is a plugin that applies a set of baseline options that most people want and that do not conflict with anything else. Think of it as the sane defaults layer -- things like increasing the history limit and setting a reasonable escape time. Worth including.
After adding this, start a tmux session and press prefix + I (capital I) to install the plugins. TPM will pull them down. You will see output confirming it worked.
Any new plugin you add later follows the same pattern: add the @plugin line to tmux.conf, press prefix + I inside a session, done.
opts.conf
This is where the behaviour lives.
# True color settings
set-option -sa terminal-overrides ",xterm*:Tc"
set -g mouse on
# Windows & Panes starting at 1
set -g base-index 1
set -g pane-base-index 1
set-window-option -g pane-base-index 1
set-option -g renumber-windows on
# Status bar position
set-option -g status-position top
True Color
set-option -sa terminal-overrides ",xterm*:Tc"
Without this, colors inside tmux will not match what your terminal actually supports. Neovim themes will look wrong. The catppuccin theme will look wrong. Any tool that relies on 24-bit color will look wrong. This line tells tmux to pass true color through to the terminal instead of flattening it. Add it once, stop thinking about it.
Mouse
set -g mouse on
Lets you click between panes, scroll with the mouse wheel, and resize panes by dragging the borders. You still do everything with keys -- but sometimes you want to click. This does not cost you anything.
Starting at 1
set -g base-index 1
set -g pane-base-index 1
set-window-option -g pane-base-index 1
set-option -g renumber-windows on
By default, windows are numbered from 0. Your keyboard's number row starts at 1. prefix + 0 to jump to the first window means your hand is reaching for a key at the far end of the row every time. Starting at 1 means prefix + 1 goes to the first window, prefix + 2 to the second, and so on. The muscle memory is immediate.
renumber-windows on handles the gap problem. If you have windows 1, 2, and 3 and you close window 2, without this option you are left with windows 1 and 3. With it, they automatically renumber to 1 and 2. No gaps, no confusion.
Status Bar Position
set-option -g status-position top
By default the status bar sits at the bottom. Moving it to the top keeps it out of the way of terminal output and makes it easier to glance at without your eye having to travel down. Personal preference -- but once you try it at the top, the bottom feels wrong.
skin.conf -- The Catppuccin Theme
The theme is Catppuccin, applied through its tmux plugin. Add it to your plugin list in tmux.conf:
set -g @plugin 'catppuccin/tmux'
Then press prefix + I to install it.
The configuration in skin.conf controls what shows up in the status bar and how it looks:
set -g @catppuccin_window_left_separator ""
set -g @catppuccin_window_right_separator " "
set -g @catppuccin_window_middle_separator " █"
set -g @catppuccin_window_number_position "right"
set -g @catppuccin_window_default_fill "number"
set -g @catppuccin_window_default_text "#W"
set -g @catppuccin_window_current_fill "number"
set -g @catppuccin_window_current_text "#W"
set -g @catppuccin_status_modules_right "directory session"
set -g @catppuccin_status_left_separator " "
set -g @catppuccin_status_right_separator ""
set -g @catppuccin_status_fill "icon"
set -g @catppuccin_status_connect_separator "no"
set -g @catppuccin_directory_text "#{pane_current_path}"
The separators are Powerline-style characters -- the ones that look like arrows. They require a Nerd Font to render correctly. If you are seeing boxes or question marks where the separators should be, your terminal font is not a Nerd Font. Swap it and they will appear.
#W is the window name -- whatever the active process in that pane is called. status_modules_right "directory session" puts the current directory path and the session name on the right side of the status bar. Useful at a glance: you always know where you are and which session you are in.
The Full tmux.conf
For reference, everything together:
source-file ~/.config/tmux/conf/opts.conf
source-file ~/.config/tmux/conf/skin.conf
# Plugin Manager (Must be last)
set -g @plugin 'tmux-plugins/tpm'
set -g @plugin 'tmux-plugins/tmux-sensible'
set -g @plugin 'catppuccin/tmux'
run '~/.config/tmux/plugins/tpm/tpm'
Reload the config without restarting tmux:
tmux source ~/.config/tmux/tmux.conf
Or from inside a session:
prefix + :source ~/.config/tmux/tmux.conf
What Is Not Here
The keys.conf file exists in my config but is commented out. That was a deliberate decision -- one I made after SSHing into a machine and spending the first few minutes confused about which key did what. If your keybindings only work on your machine, they are a liability the moment you are on someone else's. The defaults are documented everywhere. Learn them once. That is the whole argument.
If you are on a machine you control permanently and you are certain you will never need to touch another box, remap to your heart's content. Otherwise: leave it alone.
Top comments (0)