tmux without the cargo cult
Most tmux introductions open with forty keybindings. The useful part is smaller than that, and it starts with the object model, because every command follows from it.
There is one server per user. It owns sessions. A session owns windows (full-screen, like tabs). A window owns panes (splits). Your terminal is attached to a session; the server keeps running when it is not.
That last sentence is the whole product. Your SSH connection drops, your laptop sleeps, you close the terminal by accident — the processes keep running because they belong to the server, not to your terminal.
The commands that matter
tmux new -s site # start a named session
tmux ls # list sessions
tmux attach -t site # reattach
tmux kill-session -t site
Name your sessions. tmux ls showing 0, 1, 2 is useless within a day; showing site, db, logs still makes sense next week.
Inside, everything goes through the prefix, C-b by default:
prefix d detach (the important one)
prefix c new window
prefix n / p next / previous window
prefix 0-9 window by number
prefix , rename window
prefix % split vertically
prefix " split horizontally
prefix o cycle panes
prefix z zoom the current pane, and again to restore
prefix [ copy mode; q to leave
prefix z is the one people discover last and use most. Splits are good for watching two things and bad for reading one thing; zoom lets you have both without rearranging.
The config worth having
set -g mouse on
set -sg escape-time 0
set -g base-index 1
setw -g pane-base-index 1
set -g renumber-windows on
set -g history-limit 50000
escape-time 0 is the one that fixes an actual bug. tmux waits 500ms after ESC to see whether it is the start of an escape sequence. In vim that is a half-second pause every time you leave insert mode, and it feels like the editor is broken rather than the multiplexer.
base-index 1 and pane-base-index 1 move numbering to match the keyboard, so prefix 1 is the first window instead of prefix 0.
renumber-windows on closes the gaps when you kill a window, so you do not end up with windows 1, 2, 5, 9.
mouse on is not cheating. Scrollback, pane resizing, and pane selection by click are all things the keyboard does worse.
Reload without restarting
bind r source-file ~/.tmux.conf \; display "reloaded"
Editing the config does nothing to a running server. Without this you learn to kill the server to test a change, which discourages you from tuning it at all.
tmux is not a session manager for other people
Two things it is genuinely good at beyond surviving disconnects:
- A long job you want to check on. Start it in a named session, detach, come back tomorrow from a different machine.
- A per-project layout. One session per project, windows for editor, shell, logs. Attaching drops you back exactly where you were, including scrollback.
Two things it is not: a supervisor, and a way to run production services. A process in tmux dies with the server, the server dies with the machine, and nothing restarts it. If it needs to be running, it belongs to systemd or a container, not to a detached session that happens to still be alive.