Keep Work Alive with tmux Sessions and Panes

tmux keeps a shell session alive on the server even after your SSH connection drops, because the server and your terminal are two separate things. This guide creates a named session, runs work in it, detaches without stopping anything, reconnects, and splits a window into panes. About fifteen minutes.

Uses tmux 3.4 from package tmux 3.4-1ubuntu0.1. You need a shell and tmux installed; none of these commands needs sudo. The guide uses a disposable session, so it never touches a service or a persistent config file.

1. Check the installed command

Confirm the executable and version before relying on key bindings or flags:

$ command -v tmux
/usr/bin/tmux
$ tmux -V
tmux 3.4

The manpage describes tmux as a server, clients, sessions, windows and panes. A session survives an SSH disconnect or a deliberate detach because the server keeps running independently of whichever client is attached to your terminal.

2. Create a named session

Start a detached session called work with one window. The shell command at the end becomes the first pane's program:

$ tmux new-session -d -s work -n shell /bin/sh
$ tmux list-sessions
work: 1 windows (created ...)

Date and time in the listing will vary; what matters is the session name and 1 windows. Because -d was given, tmux creates the session without taking over your current terminal.

• Skip -d and new-session attaches the new client immediately.
• Skip -s and tmux picks a session name for you, fine for a quick experiment but unclear in scripts and recovery notes.

3. Reconnect to the session

Attach the current terminal to the named session:

$ tmux attach-session -t work

You are now looking at the shell running inside the tmux window. The default prefix is Ctrl-b: hold Ctrl, press b, release both, then press the command key. Ctrl-b followed by d detaches; the shell and its session keep running underneath.

Outside tmux, the shorter equivalent works too:

$ tmux attach -t work

SSH connection drops? Reconnect to the host and run the same attach command. If the session still exists, the shell state and any running foreground program should still be there. This protects against a lost client connection, not against a host reboot or a process that exits on its own.

4. Split the window into panes

With the session running, create a second pane through the command interface, easier to reproduce than keyboard input:

$ tmux split-window -h -t work:0.0 -c /tmp
$ tmux list-panes -t work:0 -F '#{session_name}:#{window_index}.#{pane_index} #{pane_width}x#{pane_height} #{pane_current_command}'
work:0.0 40x24 sh
work:0.1 39x24 bash

Exact dimensions depend on the client terminal; what matters is two panes, numbered from zero. -h makes a left/right split, omitting it makes the default top/bottom split, and -c /tmp sets the new pane's starting directory.

Inside an attached client the default keys are Ctrl-b then % for left/right, Ctrl-b then double quote for top/bottom. Ctrl-b then an arrow moves between panes, and Ctrl-b then z toggles the current pane between normal and zoomed.

5. Choose a layout and inspect it

With several panes, apply a preset layout. This changes pane sizes and positions, not the programs running in them:

$ tmux select-layout -t work:0 tiled
$ tmux list-windows -t work
0: shell* (2 panes) [80x24] [layout ...]

Layout string and dimensions vary. The installed manpage lists even-horizontal, even-vertical, main-horizontal, main-vertical and tiled. Inside tmux, Ctrl-b then a number from 1 to 5 selects those five presets, and Ctrl-b then Space cycles through them.

Layout makes a pane awkward to use? Pick another preset, for example tmux select-layout -t work:0 even-vertical. It is fully reversible; there is no need to recreate the session.

6. Find and remove a session safely

Check for the exact session before attaching to it or deleting it:

$ tmux has-session -t work
$ printf 'status: %s\n' "$?"
status: 0

Status zero means the session exists; non-zero means that target does not. This makes has-session useful in a script that should create a session only when one is absent.

$ tmux list-sessions
$ tmux kill-session -t work
$ tmux has-session -t work
no server running on /tmp/tmux-UID/default
$ printf 'status: %s\n' "$?"
status: 1

The socket diagnostic varies, and the command returns non-zero once the session is gone. There is no undo for a killed session. If a pane held important work, recover it from the program's own files, logs or source control instead. To undo only a detach, attach to the still-existing session.

Common traps

• Attaching to the wrong session. Run tmux list-sessions and use an explicit -t NAME rather than trusting the most recently used one.
• Assuming tmux is a backup. A session does not survive a machine shutdown, a killed process or data loss. Save files normally.
• Confusing panes and windows. Panes share one window; windows are separate full-screen views. Ctrl-b then c makes a new window, Ctrl-b then n moves to the next one.
• Using a broad kill command. kill-server destroys every session that server manages. Prefer the named kill-session form.