This document describes how best to use the tmux integration feature for common use cases. There are a number of settings in far-flung places that are worth customizing.
What tmux command should I use?
Most users have one tmux session per machine that they wish to either create (if needed) or attach to (if possible). Use this command:
tmux -CC new -A -s mainWhat ssh command should I use?
If you wish to run tmux on a remote host over ssh, use this command:
ssh -t example.com 'tmux -CC new -A -s main'The -t argument says to use a TTY, which tmux needs to be happy.
I keep having to reattach because my ssh connection dies when my IP address changes
Use Eternal Terminal. It tunnels ssh connections over a more reliable transport and just works. Then the command is:
et -c "tmux -CC new -A -s main" example.comI want to use mosh
Don't use mosh for tmux integration. It's not meant to tunnel traffic, and will cause you horrible agony.
How do I use shell integration?
Shell integration works with tmux integration, but does not work well with plain-old-tmux (henceforth, POT). For that reason, it is disabled by default. You can enable shell integration in tmux by adding this to your login script (.bash_profile, .profile, .zshrc, .config/fish/config.fish, or .login) prior to where shell integration is loaded:
export ITERM_ENABLE_SHELL_INTEGRATION_WITH_TMUX=YEStcsh and fish users should modify the above as needed for their shells.
In tmux 3.3 and later, you must also add set-option -g allow-passthrough on to ~/.tmux.conf.
I get random commands after tmux detaches
When you run tmux -CC at the command line, iTerm2 communicates with tmux using in-band signaling. This means that if tmux suddenly exits or your ssh session dies, iTerm2 will send commands that reach the shell rather than tmux. While there are mitigations in place to minimize the extent of this problem it cannot be completely fixed.
To prevent it, do not run tmux -CC from the command line. Instead, configure your profile to run it. See below.
How do I configure my profile?
Use iTerm2 version 3.3.6 or later. To run tmux locally set the profile’s command like this:
For remote hosts, create a new profile for each machine you run tmux on. Set the profile’s command like this:
If you use ssh instead of Eternal Terminal, configure the session to restart automatically:
What other settings are relevant?
Check Prefs > General > tmux. Here's how I like to configure it:
Buried sessions are removed from the window and go in the menu under Session > Buried Sessions. You probably don't need to interact with the tmux gateway session (the one where tmux -CC was run) very often, so it's nice to hide it away.
I have a lot of windows. How can I get them all to open?
If you have more than ten tabs or windows, the dashboard will open instead of your windows. If you have a thousand windows, this is probably convenient. If you have eleven, it might just be annoying. The threshold is adjustable in the dashboard itself:
I want to see tmux window titles as tab/window titles in iTerm2
The way tmux uses window names and window titles is confusing and kind of an impedance mismatch for iTerm2. First, tmux makes a distinction between window names and window titles, which is surprising. The window name is its identifier for applying changes to the window via tmux commands. The window title is meant to be the human-readable name that's present in the user interface.
Prior to iTerm2 3.3.0, only the window name was ever used in the UI.
In iTerm2 3.3.0 and later with tmux 2.9 or later, you can choose to show tmux window titles in native tab and window titles. Put this in your ~/.tmux.conf file:
set-option -g set-titles on
set-option -g set-titles-string '#T'After changing the value of set-titles you must detach and reattach to tmux for the change to take effect, as it's only checked once by iTerm2 when tmux integration is begun.
The tmux option set-titles-string defines the contents of the title. The default value doesn't make much sense in tmux integration since it includes a bunch of information you might not care about, like the window number. See the tmux man page for more information on this.
If you have an older version of tmux you can show window names in tab titles, and you can change them with a control sequence. Put this in your ~/.tmux.conf:
set -g allow-rename onAnd then you can use this control sequence to set the title:
echo -ne "\033kYour title goes here\007”How do session names work?
The previous section described window names and window titles. Tmux has a concept of a "window pane" which maps onto an iTerm2 "session", sometimes referred to as a "split pane". In iTerm2, a session has a name. In tmux, a window pane has a name. You can edit the name of both in Edit Session > Session Name. In a tmux integration session this is surfaced in the per-pane titlebar, which is visible only when there are split panes (if the feature is enabled).
When you open Edit Session in tmux integration, you can choose to edit either the Session Name or the Tab Title. Editing the Session Name will not have an effect on the tab title.
Control sequences in tmux (like \e]0;title\\\e) modify the session name.
Italics show up as reverse video, whole-screen reverse video isn't working, or my $TERM variable is not what I wish
Note: this applies to tmux 3.2 and earlier. In 3.3, it uses a new terminfo entry named tmux-256color which doesn't have the oddities of screen described below.
First, some background:
- Your terminal type is determined by the
TERMenvironment variable. - There are two families of terminals: xterm and screen. They vary in small ways. For example, the control sequence that indicates italic text in
xtermis used for reverse video inscreen. - iTerm2 supports xterm-family control sequences.
- By default
tmuxusesscreen. - Within tmux integration, iTerm2 attempts to detect your
TERMand translatescreen-style codes intoxterm-style codes before processing them. For example, it rewrites italic -> reverse video.
Some users prefer to use TERM=xterm-256color (or any other xterm-family terminal) in tmux. In order for this to work well, you'll want to disable the screen->xterm translation in iTerm2.
iTerm2 automatically determines what terminal tmux is configured to use by querying tmux's default-terminal setting. If it contains the string "screen" then control sequences get translated.
If you change your TERM to xterm (or an xterm-family terminal) in your .bashrc or equivalent, neither tmux nor iTerm2 will be aware of it. Consequently, it will appear to be screen to iTerm2 but xterm to the program that is sending control sequences. iTerm2 will the translate them when it oughtn’t.
To set your TERM properly you should set tmux's default-terminal property, ideally in ~/.tmux.conf. This makes it visible to iTerm2 and solves the problem. To do so, place this in your ~/.tmux.conf:
set -g default-terminal "xterm-256color"You can also globally disable the screen-to-xterm translation in tmux integration with Prefs > Advanced > Convert italics to reverse video in tmux integration?.
Shell Integration and iTerm2 Utilities Broke in tmux 3.3
You must add this to your ~/.tmux.conf:
set-option -g allow-passthrough on