macOS Terminal.app with tmux guide

macOS Terminal.app 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 (Terminal.app 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
Terminal.app window:

% echo $TERM
xterm-256color
% tmux
% echo $TERM
tmux-256color
% 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.app 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
on.

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 Terminal.app and do the following:

% cd
% curl -O https://raw.githubusercontent.com/mawww/kakoune/master/contrib/tmux-256color.terminfo
% /usr/bin/tic -x $HOME/tmux-256color.terminfo
% rm $HOME/tmux-256color.terminfo

NOTE: you must use the -x flag here when building for Terminal.app 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 (Terminal.app) 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.

1 Like

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.