TopolearnBroken colours, odd keys in vim and laggy Esc inside tmux all come from the terminal layer, and fixing them needs this model.
tmux is a terminal emulator running inside another terminal. Programs in panes talk to tmux, and tmux redraws to your real terminal. So there are two terminal descriptions:
- Inside panes,
TERMcomes fromdefault-terminal. Usetmux-256color(orscreen-256colorif the host lacks that terminfo entry), neverxterm-256colorinside tmux: tmux does not implement everything xterm does. - For the outer terminal, tmux reads its terminfo entry and adds terminal features. If your terminal supports 24-bit colour but its terminfo does not say so, add
set -as terminal-features ',xterm-256color:RGB'(3.2+; older configs usedterminal-overrides ...:Tc). Check what tmux detected withtmux info.
escape-time is how long tmux waits after Esc to see if it starts an Alt/escape sequence. The old default of 500 ms made Esc in vim feel sluggish; tmux 3.5 lowered the default to 10 ms, and many configs set escape-time 0 or 10 explicitly.
Keys: by default, combinations like Ctrl-Shift-x or Ctrl-Enter cannot be distinguished. With set -s extended-keys on and a terminal that supports the CSI u or modifyOtherKeys protocols, tmux passes them through to applications that request them. focus-events on forwards focus in/out so editors can autoreload files.
When something looks wrong, compare echo $TERM inside and outside tmux and run tmux info | grep -i rgb.
Example
# ~/.tmux.conf
set -g default-terminal "tmux-256color"
set -as terminal-features ",xterm-256color:RGB" # true colour in outer terminal
set -s escape-time 10
set -s extended-keys on
set -g focus-events on
# checks from a shell
echo $TERM # inside tmux: tmux-256color
tmux info | grep -i -e rgb -e Tc # what tmux thinks the outer terminal supports
infocmp tmux-256color >/dev/null && echo "terminfo present"Remember
- default-terminal sets TERM inside panes: use tmux-256color
- terminal-features RGB enables true colour on the outer terminal
- Low escape-time keeps Esc snappy in editors
Watch out for
- Setting default-terminal to xterm-256color, which makes programs use features tmux does not support.