TMUX

This page explains how tmux works, why it is useful on WI‑HPC, and lists common commands and keybindings. Use tmux for interactive work on allocated nodes (salloc, srun) to keep sessions persistent across disconnects.

Overview — how tmux works

• tmux is a terminal multiplexer: one terminal process (the tmux server) manages multiple sessions, windows (tabs) and panes (splits).
• Each session can have multiple windows; each window can be split into multiple panes. Sessions persist on the cluster node even if your SSH connection drops; you can reattach later.
• tmux has a command mode started with a prefix (leader) key. Default prefix: Ctrl‑b (written as C-b).

Why use tmux on WI‑HPC

• Keep interactive environments persistent during network interruptions.
• Run multiple monitors, editors and shells in one allocation.
• Reattach to long-running interactive work without losing state.
• Share a session with collaborators for debugging or teaching.
• Combine with salloc/srun to get an interactive node, then start tmux inside the allocation so processes run on the compute node.

Where to start your tmux session

start tmux after obtaining an interactive allocation (salloc/srun) when you want processes to run on compute nodes. A tmux session started on the login node will not follow your jobs on an allocated compute node.

Basic workflows

Start a named session:

tmux new -s mysession

To detach (leave session running) from inside tmux: Press prefix, then d (default: C-b d)

List sessions:

tmux ls

Attach to a session:

tmux attach -t mysession
# short: tmux a -t mysession

Kill a session:

tmux kill-session -t mysession

Run a command in a new session (detached):

tmux new -d -s jobwatch 'top'

Send a command to an existing session/pane:

tmux send-keys -t mysession:0.0 'module load python; python script.py' Enter

Combine with SLURM:

• srun --pty /bin/bash
• inside the allocation: tmux new -s work
• run interactive processes inside tmux

Common tmux commands (CLI)

Command	Description
tmux new -s name	Create and attach a new session
tmux new -d -s name cmd	Create a detached session running cmd
tmux ls	List sessions
tmux attach -t name	Attach to a session
tmux kill-session -t name	Kill a session
tmux kill-server	Stop tmux server (closes all sessions)
tmux rename-session -t old new	Rename a session
tmux new-window -n name	Create a new window in the current session
tmux split-window -h	Split current pane vertically (side-by-side)
tmux split-window -v	Split current pane horizontally (top/bottom)
tmux select-pane -L/R/U/D	Move focus between panes (left/right/up/down)
tmux resize-pane -L/-R/-U/-D [count]	Resize pane by direction; optional [count] steps
tmux list-windows	Show windows in a session
tmux list-panes	Show panes in the current window
tmux capture-pane -p -t target > out.txt	Save pane content to out.txt

Default keybindings (prefix explained)

Prefix (leader): Ctrl‑b (C-b). Press and release the prefix, then press the next key(s) for the command. Essential bindings (after pressing prefix):

Keybind	Action
C-b c	Create a new window (new-window)
C-b ,	Rename current window (rename-window)
C-b &	Kill current window (kill-window)
C-b %	Split pane vertically (left/right) (split-window -h)
C-b "	Split pane horizontally (top/bottom) (split-window -v)
C-b o	Move to next pane (rotate)
C-b ;	Toggle to last (previous) window
C-b n / C-b p	Next / previous window
C-b w	List windows (choose with arrows)
C-b q	Show pane numbers briefly
C-b x	Kill current pane (confirm)
C-b { / C-b }	Swap panes left / right
C-b [	Enter copy/scrollback mode (Space to start, Enter to copy)
C-b ]	Paste buffer into current pane
C-b d	Detach from session
C-b :	Enter tmux command prompt
C-b ?	Show full list of key bindings

How to use copy mode

Move cursor to start, press Space, move to end, press Enter. Then C-b ] to paste.

Changing prefix (example in ~/.tmux.conf):

unbind C-b
set -g prefix C-a
bind C-a send-prefix

This sets the prefix to Ctrl‑a (useful for users migrating from screen).

Enable mouse (optional, in ~/.tmux.conf):

set -g mouse on

This allows clicking to select panes, windows, and scroll.

Tips and best practices

• Start tmux inside an interactive allocation if you need compute-node resources.
• Name sessions to make reattachment easy (tmux new -s jobname).
• Use separate windows for editor, monitoring (htop, nvidia-smi), and job control.
• Use tmux logging or capture-pane to save terminal output before detaching.
• If your SSH connection is unstable, tmux prevents losing interactive state.
• For reproducible environment, include module loads and environment setup inside the session or a startup script.

Troubleshooting

• "can't connect to /tmp/tmux-UID/default" — tmux server not running or permission issue; try tmux ls or restart with tmux -S /tmp/...
• Detached but can't see processes — ensure tmux started inside the allocation where the processes run.
• Reclaim resources: remember to kill sessions when no longer needed (tmux kill-session -t name).

Further reading: tmux man page (man tmux) and the tmux wiki.