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 main
What 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.com
I 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:
tcsh and fish users should modify the above as needed for their shells.
How do I configure my profile?
I recommend using version 3.3.0 of iTerm2 (in beta at the time of this writing). 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. 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:
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 on
And 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 "split pane". In iTerm2, a split pane 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.
I want tabs/windows of different sizes.
Turn on Prefs > Advanced > Allow variable window sizes in tmux integration. Ensure you have the most recent version of tmux installed. As of the 10/31/2019 nightly build or 3.3.7beta3 this should work reasonably well but there might be bugs. Please report them at https://iterm2.com/bugs and attach an as-minimal-as-possible debug log.