Core Concepts

The server: what keeps everything running

When you run tmux for the first time, it starts a background process called the tmux server. The server owns every session, window, and pane, and the programs running inside them. Your terminal app is only a client that connects to the server and draws what it sends.

This split is the whole trick. Because your shells belong to the server and not to the terminal window, closing the window or losing an SSH connection only removes a client. The server, and everything in it, carries on. The server stops when its last session ends, or when you run tmux kill-server. Restarting the computer also stops it, so tmux protects you from disconnects, not from reboots.

Clients and the server talk through a socket file, by default in a private folder under /tmp. You can run completely separate servers with tmux -L name, each with its own sessions, which is handy for testing a config without touching your real work.

Sessions in depth

A session is the unit you attach to and detach from. Most people keep one session per project or task, named after it, so tmux attach -t api always brings back the same set of windows. Sessions without a name are numbered 0, 1, 2, and so on.

Several clients can attach to the same session at once. They see the same windows and the same cursor, which makes pairing easy. If two people want to look at different windows of the same project, use a session group instead: create a second session with tmux new -s second -t api. Grouped sessions share their windows but each keeps its own current window.

Switch between sessions without leaving tmux using Ctrl+b s (an interactive picker), Ctrl+b ( and ) for previous and next, or Ctrl+b L for the last session you used.

Windows and the status line

Each window has an index (its number) and a name. By default windows are numbered from 0 and named after the program running in them, so you will see names like zsh, vim, or htop change as you work. Rename a window with Ctrl+b , to make the name stick.

The status line at the bottom lists every window in the session. A symbol after the name tells you more about it:

A window can belong to more than one session at the same time. That is how session groups share windows, and it is why closing a window from one session can make it disappear from another.

Panes and layouts

Every pane is a full, separate terminal with its own program, scrollback history, and working directory. Exactly one pane in each window is active: it gets your keystrokes and has the highlighted border.

The way panes are arranged is called the layout. tmux has seven preset layouts. Press Ctrl+b Space to cycle through them, or jump to one directly with Ctrl+b then Alt+1 to Alt+7:

• even-horizontal and even-vertical: equal panes side by side, or stacked.
• main-horizontal and main-vertical: one large pane on top or on the left, with the rest sharing the remaining space. The mirrored versions put the large pane at the bottom or on the right.
• tiled: every pane gets roughly the same size, in a grid.

tmux 3.7 also added floating panes, created with Ctrl+b *. They sit above the layout like a popup but behave like normal panes. See the new-pane reference for details.

Naming things: targets

Most tmux commands accept -t to say which session, window, or pane they should act on. The format reads from big to small: session:window.pane.

tmux select-window -t api:2        # window 2 in the api session
tmux send-keys -t api:server.1 ls  # pane 1 of the window named server
tmux kill-pane -t :.0              # pane 0 of the current window
tmux switch-client -t api          # just the session

Names can be shortened as long as they are unique: -t ap finds a session called api. Put = in front to insist on an exact match, as in -t =api. There are also handy tokens, such as {last} for the window or pane you were in before and + and - for the next and previous window.

Numbers and names can change as you open, close, and rename things. Scripts should use IDs instead, which never change while tmux runs: sessions look like $1, windows like @4, and panes like %7. Print the current pane's ID with tmux display -p '#{pane_id}'.

Detaching versus killing

This is the distinction that trips up most new users:

• Detaching (Ctrl+b d, or just closing the terminal) disconnects your client. Every program keeps running and you can attach again later.
• Killing (kill-pane, kill-window, kill-session, kill-server) ends the programs for good. Unsaved work in them is lost.
• Exiting the program in a pane, for example typing exit in its shell, closes that pane. When the last pane goes, the window goes; when the last window goes, the session ends.