Basics

What tmux Is

tmux is a terminal multiplexer. It runs a server that owns your shells, so those shells survive when your terminal window closes or your SSH connection drops. You detach, go home, reattach, and everything is exactly where you left it.

The three-level hierarchy is the thing to internalize:

One tmux server holds many sessions, a session holds many windows, and a window holds many panes. Detaching leaves the server running.

tmux                     # start a session with a generated name
tmux new -s work         # start a named session
tmux new -s work -n edit # name the session and its first window
tmux ls                  # list sessions
tmux attach              # attach to the most recent session
tmux attach -t work      # attach to a named session
tmux a -t work           # same, abbreviated
tmux kill-session -t work
tmux kill-server         # stop everything

Installing

brew install tmux                 # macOS
sudo apt install tmux             # Debian, Ubuntu
sudo dnf install tmux             # Fedora
sudo pacman -S tmux               # Arch
tmux -V                           # check the version

Version matters: options and flag names changed at 2.1, 2.9, and 3.0. If a config line errors out, check your version against the docs for that option.

The Prefix

Every tmux keybinding starts with a prefix chord. The default is Ctrl-b. Press and release the prefix, then press the command key.

Ctrl-b then c      # new window
Ctrl-b then %      # split vertically

Throughout this reference prefix means that first chord. Many people remap it to Ctrl-a (closer to the home row, matching GNU screen) or Ctrl-Space.

# ~/.tmux.conf
unbind C-b
set -g prefix C-a
bind C-a send-prefix    # so Ctrl-a still reaches the inner program

If you remap to Ctrl-a, note that Ctrl-a is also "start of line" in readline, which is why the send-prefix line matters: pressing it twice sends it through.

First Ten Bindings

These cover most of daily use.

prefix ? is the built-in cheat sheet. It reflects your actual config, including remappings, which makes it more trustworthy than any list.

Sessions From the Shell

tmux new -s api                    # create
tmux new -s api -d                 # create detached (do not attach)
tmux new -s api -c ~/projects/api  # set the starting directory
tmux attach -t api                 # attach
tmux attach -d -t api              # attach and detach other clients
tmux switch -t api                 # switch, from inside tmux
tmux rename-session -t api backend
tmux kill-session -t api
tmux kill-session -a               # kill all sessions but the current one
tmux has-session -t api 2>/dev/null   # exit 0 if it exists

A common shell function: attach if the session exists, create it otherwise.

# ~/.bashrc or ~/.zshrc
ta() {
  tmux has-session -t "$1" 2>/dev/null \
    && tmux attach -t "$1" \
    || tmux new -s "$1"
}

Session Bindings

prefix w is the one to remember when you have several projects open: it shows the entire tree, and you can navigate and select from it.

Why It Beats Tabs

A terminal emulator's tabs die with the emulator. tmux panes do not, which changes what you can do:

• SSH resilience. Run tmux on the remote host, then a dropped connection costs you nothing. Reconnect and tmux attach.
• Long jobs. Start a build or a migration, detach, and check back later without nohup or a job scheduler.
• Reproducible layouts. A script can build the exact windows and panes a project needs.
• Pair debugging. Two people attached to one session see the same screen.
• One keyboard grammar across every machine, local or remote, GUI or console.