Tools: tmux

tmux is a terminal multiplexer. It consists of a tmux server that is capable of handling multiple sessions and a tmux client that is the user interface to sessions. Each session consists of multiple windows and each window can have multiple panes. Each pane represents a seperate terminal. You can easily jump between sessions, windows, and panes. You connect to a session using the tmux client which is a CLI. You can disconnect from a session and allow that session to continue running in the backgroud which allows you to reconnect at a later time. You can also connect to a tmux server running on a different machine. It is wonderous stuff.

If you spend a good chunk of your day in front of a terminal using the command line, tmux will make you more productive. It’s another one of those tools that you don’t have to learn, but if you do it pays off in multiples.

The creation of tmux sessions can be scripted. A common setup is to create an alias to your common session configurations so that you can be ready to start working on your project by issuing a single short command that is aliased to your tmux script. The script that executes will either connect to an already running tmux session with that name or create the session with the desired windows and panes and also kick off any programs that need to be running (editor, webserver, etc.). No more spending a few minutes getting your windows set up and cd’ing around your code base like crazy, one short command and you are ready to go.

Sessions

Working with sessions from the command line

tmux -V display tmux version
tmux start tmux client and create a new session
exit from within tmux (if it is the last pane) will exit tmux and terminate the session.
tmux list-sessions list active tmux sessions. ls is alias for list-sessions
tmux new-session -s <sess-name> start tmux client and create new session with name <sess-name>. new is alias for new-session
tmux new-s <sess-name> -d create new session with name <sess-name> but do not attach (leave running in the background)
tmux attach start tmux client and attach to the most recently used session
tmux attach -t <sess-name> start tmux client and attach to session <sess-name>
tmux kill-session -t <sess-name> terminate tmux session with name <sess-name>

The Prefix: sending commands to tmux

In general, what you type into tmux is passed through to the underlying terminal. To allow passing commands to tmux itself you enter the <prefix> key combination followed by a tmux command.

The default prefix is <ctrl>+b. It is easier to type <ctrl>+a (especially if you remap caps lock to ctrl) and you can set that up in the tmux configuration file (described below) using the following.

unbind C-b
set -g prefix C-a

The examples on this page use <prefix> to indicate entering the prefix key combination.

For example, <prefix>t displays the time in the center of the active panel.

To send <ctrl>+a itself to the underlying terminal (which you might want to do as <ctrl>+a does useful things like move to the start of the line when editing commands) add the following to your tmux configuration. Then enter the prefix twice, <prefix><prefix>.

bind C-a send-prefix

Working with sessions from within tmux

<prefix>r redraw screen
<prefix>s display list of sessions for you to select from
<prefix>( switch to previous session
<prefix>) switch to next session
<prefix>d detach from server and exit tmux client leaving the session running in the background
<prefix>$ rename current session

Windows

Each tmux session consists of multiple windows (you can think of windows like tabs). Windows are numbered starting from 0, but you can change this to start from 1 by adding the following to your tmux configuration file.

set -g base-index 1

Working with windows from the command line

tmux new -s <sess-name> -n <win-name> create new sessions named <sess-name> and name the first window <win-name>

Working with windows in tmux

The available windows, along with their numbers and names, are listed on the status line. The default window name is the name of the program that is executing in the active pane of the window.

<prefix><num> jump to window number <num>
<prefix>n move to next window
<prefix>p more to previous window
<prefix>w select from list of windows (across all sessions)
<prefix>f find window by searching for entered text that is either in the window’s name or the contents of the window.
<prefix>c create new window
<prefix>, rename window
<prefix>& close a window, you can also type exit at the command line
<prefix>. move window to new session

Panes

Panes are used to break a window into multiple areas. Each pane is a seperate terminal.

Working with panes in tmux

<prefix>% split window/pane vertically into two panes
<prefix>" split window/pane horizontally into two panes
<prefix>o cycle between the panes
<prefix><arrow keys> move between panes
<prefix><space> cycle through default pane layouts
<prefix>x close pane, will also close window if this is the last pane. You can also type exit at the command line, but if the pane is stuck this may be your only option.
<prefix>z zooms the active pane to occupy the entire window. This works as a toggle.
<prefix>! create a new window from the active pane and remove the pane from the existing window.
<prefix>q display pane numbers briefly, you can move to a specific pane by entering its number (see below for a useful configuration setting to make this a little easier)
<prefix>{ swap pane with pane above
<prefix>} swap pane with pane below

The following configuration setting is useful to display pane numbers long enough that you can actually select the one you want to jump to (value is in milliseconds).

set -g display-panes-time 3000

Command mode

<prefix>: will enter command mode. Here you can type tmux commands. The shortcuts above are a convenient way to issue these commands. However, many commands take options which can’t be supplied using the shortcuts so you will need to enter command mode for some types of work.

tmux key bindings

<prefix>? will display all valid key bindings. Use <space> to page through the results and q to quit.

tmux configuration

tmux configuration is handled using the .tmux.conf file in your home directory. I keep tmux configuration very light (mostly because I have not dug that deep) and there are a few examples from my configuration in this post.

You can see my current .tmux.conf file on Github. This is largely inspired from the tmux 2 book referenced below, but includes various “tricks” discovered on sources like StackExchange.

tmux scripts

tmux scripts are insanely useful. They are really shell scripts that issue a number of tmux commands to establish a tmux session.

My canonical use case is to create a tmux script for each project I am working on. This script will check if the tmux session already exists and attach to the session if it exists. If the session does not exist, it will create the session with two named windows. The first window is named editor and the script will move to the project root directory and open Vim with a directory listing of the project root directory. The second window will have three panes. A left side pane which I typically use to interact with Git (and issue the git status command as a starte) and two stacked panes on the right side. The top pane will be the command line of the project root and the bottom pane will often be running a server of some type. I then create an alias in my shell configuration to execute this script.

If I’m working on project X, I might have an alias tpx (tmux project X) that executes the tmux script and lands me at the editor (or wherever I left off) ready to go. I am working in seconds with minimal thinking required.

You can see my tmux script template on Github.

Resources

$ man tmux the man page for tmux is great,

<prefix>? lists all the tmux keybindings (<space> to page down and q to quit)

tmux 2: Productive Mouse-Free Development, by Brian P. Hogan
https://learning.oreilly.com/library/view/tmux-2/9781680502374/
This was the book that got me using tmux well. It’s a wealth of information and many of the ways I use tmux were inspired from the ideas in this book.

Tools