Sessions and Clients

Detaching, the Whole Point

Detaching leaves the server and every process running. This is what separates tmux from terminal tabs.

tmux new -A -s main          # the one-liner worth aliasing
alias tm='tmux new -A -s main'

Clients and Sizing

Several clients can attach to one session, and by default the session is sized to the smallest attached client. That is why a session sometimes looks squeezed after you reattach from a different machine.

tmux list-clients
tmux list-clients -F '#{client_name} #{client_width}x#{client_height}'
tmux refresh-client -S              # redraw the status line
tmux refresh-client -C 200,50       # force a client size
tmux resize-window -A               # size to the largest client (3.1+)

setw -g aggressive-resize on

With aggressive-resize on, each window is sized to the clients actually looking at it rather than to every client on the session, which usually fixes the squeezed-window problem.

Grouped Sessions

Two people, or two monitors, can view the same windows independently: same windows, separate current-window state.

tmux new-session -t work            # a new session grouped with 'work'
tmux new-session -s view -t work    # named, grouped

Both sessions share the window list, so a window created in one appears in the other, but each can be looking at a different window. Kill the grouped session and the original is untouched.

Read-Only Sharing

tmux attach -r -t demo              # watch, cannot type

For pairing over SSH with someone on a different account, both users need access to the same socket:

tmux -S /tmp/shared new -s pair     # create on a shared socket
chmod 777 /tmp/shared
# the other user, in the same group:
tmux -S /tmp/shared attach -t pair

This is a real security boundary: anyone who can read that socket can type into your shells. Use it deliberately, on trusted machines, and remove the socket afterwards.

Multiple Servers

Each socket is an independent tmux server with its own sessions and its own config state.

tmux -L work new -s main         # socket named 'work'
tmux -L work ls
tmux -S /tmp/mysock new          # explicit socket path
tmux -L work kill-server
ls /tmp/tmux-$(id -u)/           # the default socket directory

Separate servers are useful when you want a scratch environment with a different config, or a long-lived server that a config reload cannot disturb.

Persistence Across Reboots

tmux does not survive a reboot on its own. Processes die with the machine, and the server goes with them.

set -g @plugin 'tmux-plugins/tmux-resurrect'
set -g @plugin 'tmux-plugins/tmux-continuum'
set -g @continuum-restore 'on'
set -g @continuum-save-interval '15'
set -g @resurrect-capture-pane-contents 'on'
set -g @resurrect-strategy-vim 'session'
set -g @resurrect-strategy-nvim 'session'

Resurrect restores the session, window, and pane structure plus working directories. It restores programs only for a configured allowlist, so a npm run dev pane comes back as a shell in the right directory, not as a running server. That is usually what you want.

Systemd or launchd

For a server that starts at boot and holds a session for background work:

# ~/.config/systemd/user/tmux.service
[Unit]
Description=tmux server
[Service]
Type=forking
ExecStart=/usr/bin/tmux new-session -d -s bg
ExecStop=/usr/bin/tmux kill-server
Restart=on-failure
[Install]
WantedBy=default.target

systemctl --user enable --now tmux.service
loginctl enable-linger "$USER"    # so it survives logout

Note that enable-linger is the part people miss: without it, systemd kills the user's services when the last login session ends, taking tmux with it.

Attaching From a Script

# Only attach when we are in an interactive terminal and not already inside tmux
if [ -z "$TMUX" ] && [ -t 1 ] && command -v tmux >/dev/null; then
  tmux new -A -s main
fi

Guarding on $TMUX prevents infinite nesting, and guarding on -t 1 prevents the line from breaking scp, rsync, and any non-interactive SSH command, which is a classic way to make a machine hard to automate against.