macOS with tmux guide

macOS specific

Setting correct $TERM value

Select the menu Terminal->Preferences->Profiles->Advanced tab, and make sure
the “Declare terminal as:” value is set to ‘xterm-256color’.

IMPORTANT: do not set $TERM value in any .bashrc/.zshrc/.fishrc, etc.; do it
at the terminal emulator level ( preferences menu) only! The issue
many people encounter is they have been told to set $TERM somewhere in a
bash/zsh script; the issue with this, among others, is that when you run tmux
it sources your ‘rc’ scripts (bash/zsh/fish/etc.) and if a $TERM value is set
in them they it overrides what we want, namely $TERM value inside tmux to be
set to ‘tmux-256color’.

To test everything is setup correctly do the following, after opening a new window:

% echo $TERM
% tmux
% echo $TERM
% exit

If when inside tmux, echo $TERM gives you something other than
‘tmux-256color’, then it means one of your startup scripts is setting it
AFTER we have set it in our $HOME/.tmux.conf file.

Enable Alt-key Support

If you are using macOS’s terminal emulator, you’ll need to make
sure “Use Option as Meta Key” is checked under the Edit menu. Without this
setting you will not be able to use the Alt+ combinations Kakoune relies

It can also be enabled by checking “Use Option as Meta Key” under the
Terminal->Preferences->Profiles->Keyboard tab, to save the option to the
active profile.

Better tmux support

macOS, as of 11.1 (January 2021) still ships with an older version of the
ncurses library (5.7) which does not contain a terminal info database
entry for ‘tmux-256color’. You can choose to use ‘screen-256color’ in your
.tmux.conf but the colors will be slightly off and a few other textual
features are not supported, e.g., italicized text and xterm cursor shapes.
Thankfully, we can build a new terminfo file and compile it ourselves for
better tmux support.

Open and do the following:

% cd
% curl -O
% /usr/bin/tic -x $HOME/tmux-256color.terminfo
% rm $HOME/tmux-256color.terminfo

NOTE: you must use the -x flag here when building for to
support “unknown capabilities as user-defined” (man tic).

set -g default-terminal "tmux-256color"

If you have the following anywhere in your .tmux.conf file:

set -ga terminal-overrides ",*col*:Tc"

Remove or comment out the line. This line is telling tmux that the ‘outside’
terminal emulator ( supports true color (‘Tc’ flag) which is
does not. Setting this will leave you with incorrect colorschemes in
Kakoune, and other places.

Finally, quit all existing sessions (tmux kill-server), and restart tmux.


Some images to illustrate:

Left: tmux with macOS provided ‘screen-256color’ terminfo. :colorscheme github
Right: no tmux. macOS provided ‘xterm-256color’ terminfo. :colorscheme github

Left: tmux with custom-built ‘tmux-256color’ terminfo installed. :colorscheme github
Right: no tmux. macOS provided ‘xterm-256color’ terminfo. :colorscheme github

As good as I’ve gotten it so far, colours are slightly different but better than they were
when using ‘screen-256color’ terminfo inside tmux, and supports more textual features.

Left: tmux with macOS provided ‘screen-256color’ terminfo. :colorscheme solarized
Right: no tmux. macOS provided ‘xterm-256color’ terminfo. :colorscheme solarized

Colouring differences more pronounced here.