tmux - Terminal Multiplexer Guide

When working over SSH, one of the most frustrating experiences is a dropped connection killing a long-running process. tmux (terminal multiplexer) solves this - and much more. It lets you run persistent sessions, split your terminal into panes, and detach/reattach from anywhere.

---

Why tmux Over SSH

Without tmux, every SSH session is tied to your connection. If the network drops, the process dies. With tmux:

• Sessions persist on the remote machine even after you disconnect
• Re-attach from any client, any time
• Multiple windows and panes in a single SSH connection - no need to open extra terminals
• Run long builds, downloads, or scripts without babysitting the connection

---

Installation

# Debian / Ubuntu
sudo apt install tmux

---

Core Concepts

Concept	Description
Session	A top-level container that persists independently of your terminal
Window	A full-screen tab inside a session
Pane	A split subdivision within a window

The default prefix key is Ctrl+b - press it before every tmux command.

---

Session Management

Start a Named Session

tmux new -s mysession

Always name your sessions - it makes reattaching much easier.

Detach from a Session

Ctrl+b  d

The session keeps running in the background. You can now safely close the SSH connection.

List All Sessions

tmux ls

Reattach to a Session

tmux attach -t mysession

If there is only one session running:

tmux attach

Kill a Session

tmux kill-session -t mysession

---

Typical SSH Workflow

[Local Machine] ──SSH──> [Remote Server]
                              │
                         tmux new -s work
                              │
                    ┌─────────┴──────────┐
                    │   long build run   │
                    │  (safe to detach)  │
                    └────────────────────┘
                              │
                       Ctrl+b  d  (detach)
                              │
              [SSH connection drops  -  no problem]
                              │
                    [Reconnect later via SSH]
                              │
                   tmux attach -t work

This is the core use case: start a job, detach, close your laptop, come back the next day and reattach.

---

Window Management

Action	Keys
New window	Ctrl+b c
Next window	Ctrl+b n
Previous window	Ctrl+b p
Switch by number	Ctrl+b 0-9
Rename window	Ctrl+b ,
Close window	Ctrl+b &

---

Pane Management

Split the current window to run multiple things side-by-side in one SSH connection:

Action	Keys
Split horizontally (left/right)	Ctrl+b %
Split vertically (top/bottom)	Ctrl+b "
Navigate between panes	Ctrl+b Arrow keys
Resize pane	Ctrl+b Ctrl+Arrow keys
Close pane	Ctrl+b x
Zoom pane (toggle fullscreen)	Ctrl+b z

Example: monitor a log in one pane while editing in another, all over a single SSH connection:

┌──────────────────┬──────────────────┐
│                  │                  │
│   vim main.c     │  tail -f app.log │
│                  │                  │
└──────────────────┴──────────────────┘

---

Copy Mode (Scrollback)

SSH terminals often have limited scrollback. tmux has its own scrollback buffer:

Ctrl+b  [        # Enter copy mode
Arrow keys        # Scroll up/down
q                 # Exit copy mode

To scroll with the mouse wheel, add this to ~/.tmux.conf:

set -g mouse on

---

Useful Configuration (~/.tmux.conf)

# Enable mouse support
set -g mouse on

# Start window and pane numbering from 1 (easier to reach on keyboard)
set -g base-index 1
set -g pane-base-index 1

# Increase scrollback buffer
set -g history-limit 10000

# Reload config without restarting
bind r source-file ~/.tmux.conf \; display "Config reloaded"

Apply changes to a running session:

tmux source-file ~/.tmux.conf
# or inside tmux: Ctrl+b  r  (if you added the bind above)

---