tmux The Ultimate Terminal Multiplexer (Complete, Skimmable Guide)

TL;DR Summary

• What it is: tmux lets you split your terminal into panes, manage multiple windows, and keep sessions running even if SSH drops.

• Why it matters: Perfect for long-running jobs, remote admin, and organized workflows (logs, editors, shells) -- all in one screen.

• Core ideas: Sessions contain Windows, which contain Panes. Default prefix is Ctrl+b.

• Fast start: tmux new -s work, then split (Ctrl+b % or "), switch panes (Ctrl+b arrows), detach (Ctrl+b d), reattach (tmux a).

• Power-ups: Enable mouse, persistent history, copy to system clipboard, and plugins with TPM.

• Ops tip: Use tmux new -As main in SSH profile so you always drop into your main session automatically.

---

What is tmux

tmux is a terminal multiplexer that lets you:

• Run multiple terminals inside one window

• Split your screen into panes (vertical/horizontal)

• Detach/reattach to long-running sessions

• Share a terminal session with teammates

• Persist your environment across SSH disconnects

Think of tmux as a window manager for your terminal.

---

Core Concepts (Most Important)

• Session Top-level workspace (e.g., dev, logs, prod).

• Window A tab inside a session (e.g., api, db).

• Pane A split inside a window (e.g., editor left, logs right).

Default prefix: Ctrl+b (you press this before most tmux commands).

---

Installation

• Debian/Ubuntu: sudo apt-get install tmux

• RHEL/CentOS/Rocky/Alma: sudo dnf install tmux (or yum install tmux)

• Arch: sudo pacman -S tmux

• macOS (Homebrew): brew install tmux

• Windows: Use WSL (install in Linux), or Git Bash/MSYS2 (limited), or Windows Terminal with WSL.

Check: tmux -V

---

Daily Driver: Essential Key Bindings

(All start with Ctrl+b unless noted)

Action	Keys
Help (list keys)
Create new session	tmux new -s NAME (shell cmd)
List sessions	tmux ls (shell cmd)
Attach last session	tmux a (shell cmd)
Detach	d
New window	c
Next/Prev window	n / p
Rename window	,
Split pane vertical	%
Split pane horizontal	"
Switch pane	Arrow keys
Resize pane	Ctrl+b then Ctrl + arrows (or Alt + arrows)
Close pane	exit (inside pane) or x (kill-pane)
Move pane to new window	!
Zoom pane	z (toggle)
Copy mode (scroll/search)	[ (exit with q)

Super-habit: tmux new -As main -- reattach if exists, else create. Put this in ~/.bashrc/~/.zshrc for auto-persisted SSH.

---

Navigation, Search & Copy Like a Pro

• Scrollback: Ctrl+b [ then use arrows/PageUp/PageDown.

• Search: In copy mode, press / to search forward, backward; n/N to repeat.

• Copy to tmux buffer (vim-like): In copy mode, space (start), move, enter (copy).

• Paste: Ctrl+b ].

Copy to System Clipboard (optional)

• Linux (X11): xclip or xsel

• Wayland: wl-copy

• macOS: pbcopy

• WSL: clip.exe

Example mapping (puts selection into system clipboard automatically -- see config below):

bind -T copy-mode-vi y send-keys -X copy-pipe-and-cancel "pbcopy" # macOS
# or: "xclip -selection clipboard -i" / "wl-copy" / "clip.exe"

---

Mouse, Status Bar & Quality of Life

Enable selection, clicking panes, and resizing with mouse:

set -g mouse on

Nice status bar (24h clock, host, session, battery if available):

set -g status-interval 5
set -g status-left "#[bold]#S"
set -g status-right "#(date '+%Y-%m-%d %H:%M') | #H"

Persistent scrollback (bigger history):

set -g history-limit 100000

Faster escape + better responsiveness:

set -sg escape-time 0
set -g focus-events on

---

A Clean, Modern ~/.tmux.conf (Drop-in)

Safe defaults for Linux/macOS/WSL -- copy/paste as-is, then restart tmux: tmux kill-server (ends all tmux) or apply with Ctrl+b : source-file ~/.tmux.conf

##### Prefix & Behavior
set -g prefix C-b
unbind C-b
set -g prefix C-b
bind C-b send-prefix

set -g history-limit 100000
set -sg escape-time 0
set -g mouse on
set -g focus-events on
set -g renumber-windows on

##### Windows & Panes
bind | split-window -h
bind - split-window -v
unbind '"'
unbind %
bind -r H resize-pane -L 5
bind -r J resize-pane -D 3
bind -r K resize-pane -U 3
bind -r L resize-pane -R 5
bind z resize-pane -Z

##### Statusline
set -g status-interval 5
set -g status-left-length 20
set -g status-right-length 80
set -g status-left "#[bold]#S "
set -g status-right "#(date '+%a %d %b %H:%M') | #H"

##### Copy-mode (vi-like)
setw -g mode-keys vi
bind -T copy-mode-vi v send-keys -X begin-selection
bind -T copy-mode-vi y send-keys -X copy-selection-and-cancel

# Uncomment ONE based on your system clipboard:
# bind -T copy-mode-vi y send-keys -X copy-pipe-and-cancel "pbcopy" # macOS
# bind -T copy-mode-vi y send-keys -X copy-pipe-and-cancel "xclip -sel clip -i" # Linux X11
# bind -T copy-mode-vi y send-keys -X copy-pipe-and-cancel "wl-copy" # Wayland
# bind -T copy-mode-vi y send-keys -X copy-pipe-and-cancel "clip.exe" # WSL

##### Quality-of-life
setw -g automatic-rename on
set -g allow-rename off
set -g base-index 1
setw -g pane-base-index 1

##### Quick session attach-or-create
# usage (shell): tmux new -As main

Prefer Ctrl+a Add:

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

---

Real-World Workflows (Hosting/DevOps)

1) Logs + Editor + Shell in one window

• Ctrl+b " (horizontal split): top = editor (nvim), bottom = logs

• In bottom, Ctrl+b % (vertical split): right pane = tail -f /var/log/nginx/access.log, left = sudo journalctl -fu php-fpm

• Zoom any pane with z.

2) Docker/Compose Monitoring

• Left pane: docker compose logs -f api

• Right-top: htop or glances

• Right-bottom: docker ps --format 'table {{.Names}}\t{{.Status}}\t{{.Ports}}'

3) Deploy & Watch

• Pane 1: git pull && docker compose up -d --build api

• Pane 2: docker compose logs -f api

• Pane 3: curl -I https://yourapp/health (repeat)

• Pane 4: tmux capture-pane -S -2000 -p > deploy.log (save scrollback)

4) SSH Resilience

Put this in your shell rc:

# Always land in a persistent session on SSH
[ -z "$TMUX" ] && tmux new -As main

---

Pairing & Session Sharing (Securely)

1. SSH into the same server as two users.

2. One user: tmux new -s pair

3. Grant access (same UNIX group, or chmod tmux socket if needed).

4. Second user: tmux a -t pair

Security tip: Restrict who can access the tmux socket (usually in /tmp/tmux-UID/); avoid sharing root's session; consider read-only with tmux attach -r for demos.

---

Plugins with TPM (tmux plugin manager)

Install TPM:

git clone https://github.com/tmux-plugins/tpm ~/.tmux/plugins/tpm

Add to ~/.tmux.conf:

set -g @plugin 'tmux-plugins/tpm'
set -g @plugin 'tmux-plugins/tmux-sensible'
# Examples:
# set -g @plugin 'tmux-plugins/tmux-resurrect'
# set -g @plugin 'tmux-plugins/tmux-continuum'
run '~/.tmux/plugins/tpm/tpm'

Reload & install: Ctrl+b I (capital i)

Resurrection/Continuum: auto-save/restore sessions on reboot -- great for servers.

---

Troubleshooting & Gotchas

• Mouse scroll doesn't work: Ensure set -g mouse on. In some terminals, hold Shift while scrolling or use copy-mode (Ctrl+b [).

• Clipboard not syncing: Use the correct pbcopy/xclip/wl-copy/clip.exe pipe.

• Weird key delays: Add set -sg escape-time 0.

• SSH drops kill work: Always use tmux (and tmux new -As main).

• Locale issues/box-drawing glitches: Set a UTF-8 locale in your shell (export LC_ALL=en_US.UTF-8 or equivalent) and use a font that supports line chars.

---

Useful Commands (Shell-Level)

tmux ls # list sessions
tmux new -s dev # create session 'dev'
tmux a -t dev # attach to 'dev'
tmux kill-session -t dev # kill a session
tmux switch -t dev # switch sessions while attached
tmux list-keys # show key bindings
tmux show -g # show global options
tmux capture-pane -S -10000 -p > out.txt # dump scrollback

---

Power Moves (Once You're Comfortable)

• Choose-tree (visual switcher): Ctrl+b w

• Move pane to its own window: Ctrl+b !

• Join panes between windows: join-pane -s :1.2 -t :2

• Sync panes (broadcast typing): Ctrl+b : then setw synchronize-panes on

• Named windows on creation: new-window -n logs 'journalctl -fu nginx'

---

tmux vs. screen (Quick Take)

• tmux: modern, plugins, richer statusline, better scripting & layouts.

• screen: older, still available everywhere.

New setups should prefer tmux.

---

Backup/Restore Your Setup

• Keep ~/.tmux.conf in Git.

• If using TPM + Resurrect/Continuum, sessions persist across reboots.

• Export key tmux options: tmux show -g > tmux.snapshot.conf

---

FAQ

Q: How do I change prefix to Ctrl+a (like screen)
A: See the Prefix snippet above -- unbind C-b, set prefix to C-a.

Q: How do I keep processes running after SSH disconnect
A: Start them inside tmux. Detach with Ctrl+b d. Reattach with tmux a.

Q: Can I scroll without mouse
A: Ctrl+b [ then PageUp/PageDown; exit with q.

Q: How do I copy text into my OS clipboard
A: Use copy-pipe-and-cancel with pbcopy/xclip/wl-copy/clip.exe as shown.

Q: Best way to always land in tmux on servers
A: Add [ -z "$TMUX" ] && tmux new -As main to your shell rc.

---

Quick Start Checklist

• Install tmux and check tmux -V

• Create ~/.tmux.conf from the template above

• Enable mouse, large history, and vi-copy mode

• Map clipboard for your OS (pbcopy/xclip/wl-copy/clip.exe)

• Add tmux new -As main to your shell rc for resilience

• (Optional) Install TPM + tmux-sensible + tmux-resurrect

---

Handy Callouts

Tip: Zoom any pane with Ctrl+b z -- great for quick focus.

Ops Safety: Always do risky commands in a separate pane or window; keep a monitoring pane (logs/metrics) visible.

Repeatable Layouts: Consider tmuxp or tmuxinator to define YAML layouts (projects spin up the same way every time).

CI/Build Machines: Use tmux for ephemeral runners or during long compiles to avoid losing state on SSH drop.