Keep Work Alive with tmux Sessions and Panes

You will create a named tmux session, run work inside it, detach without stopping the work, reconnect later, and split the window into panes. The examples use tmux 3.4 from package tmux 3.4-1ubuntu0.1 on the machine where this guide was checked.

Allow about fifteen minutes. You need a shell and tmux installed. These commands are ordinary user commands; none needs sudo. The guide uses a disposable session for examples, so it does not alter a service or a persistent configuration file.

1. Check the installed command

Confirm the executable and version before relying on key bindings or command 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 an intentional detach because the server continues running separately from the client attached to your terminal.

Checkpoint: if tmux -V fails, install tmux through your normal distribution package process before continuing. Do not copy a configuration file from an unrelated machine to work around a missing executable.

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 ...)

The date and time in the listing are variable. The useful result is the session name and 1 windows. Because -d was supplied, tmux creates the session without taking over your current terminal.

Without -d, new-session attaches the new client immediately. Without -s, tmux chooses a session name, which is convenient for a quick experiment but less clear in scripts and recovery instructions.

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 key is Ctrl-b: hold Ctrl and press b, release both, then press the command key. For example, press Ctrl-b followed by d to detach. The shell and its session remain running.

When you are outside tmux, the equivalent command is shorter:

$ tmux attach -t work

When an SSH connection drops, reconnect to the host and run the same attach command. If the session 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 by itself.

4. Split the window into panes

With the session running, create a second pane using the command interface. This is easier to reproduce than relying on 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

The exact dimensions depend on the client terminal. The important result is two panes, numbered from zero. -h makes a left and right split; omitting it makes the default top and bottom split. The -c /tmp option sets the starting directory for the new pane.

Inside the attached client, the default keys are Ctrl-b then % for a left and right split, and Ctrl-b then double quote for a top and bottom split. Ctrl-b followed by an arrow key moves to the adjacent pane. Ctrl-b then z toggles the current pane between normal and zoomed size.

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 ...]

The layout string and terminal dimensions vary. The installed manpage lists even-horizontal, even-vertical, main-horizontal, main-vertical and tiled. Inside tmux, Ctrl-b followed by a number from 1 to 5 selects those five preset layouts, and Ctrl-b followed by Space cycles through them.

If a layout makes a pane awkward to use, select another preset. The command tmux select-layout -t work:0 even-vertical is a reversible adjustment. There is no need to recreate the session.

6. Find and remove a session safely

Check for the exact session before attaching or deleting it:

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

A status of zero means the session exists. A non-zero status means that target does not exist. This makes has-session suitable for a script that should create a session only when 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 after the session is gone. There is no tmux undo command for a killed session. If a pane contained important work, recover it from the program's own files, logs or source-control history. To undo only a detach, attach to the still-existing session instead.

Common traps

• Attaching to the wrong session: run tmux list-sessions and use an explicit -t NAME instead of trusting the most recently used session.
• 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 terminal views. Use Ctrl-b then c for a new window and Ctrl-b then n for the next one.
• Using a broad kill command: kill-server destroys every session managed by that server. Prefer the named kill-session form.