tmux: Detach from Session Without Killing It

## The core distinction tmux (terminal multiplexer) decouples your shell processes from the terminal emulator you happen to be typing into. A tmux session is owned by a long-running tmux server, not by your login shell, so you can walk away from the terminal and come back later — or from a different machine over SSH — without losing state. The critical action is *detach*, not *exit*: - **Detach** (`prefix` + `d`) — disconnect your client from the session. Processes keep running, panes keep their scrollback, background jobs continue. You drop back to the parent shell. - **Exit / `Ctrl+D`** — closes the shell in the current pane. When the last pane in the last window of a session exits, the session is destroyed and everything in it dies. Mixing these up is the #1 way people lose long-running builds, training runs, or SSH-tunneled work. ## The prefix key Every tmux keybinding starts with a prefix key, which signals "the next keystroke is for tmux, not for the program in the pane." The default is `Ctrl+B`, chosen because it rarely conflicts with shell or editor bindings. Many users find it awkward to chord and rebind it to `Ctrl+A` (matching GNU Screen) or `Ctrl+Space`: ``` # ~/.tmux.conf unbind C-b set -g prefix C-a bind C-a send-prefix # press Ctrl+A twice to send a literal Ctrl+A ``` Whenever a tmux tutorial says "`prefix` + `d`", substitute whatever you bound. ## Session / window / pane hierarchy tmux has a strict three-level structure: - **Session** — top-level container. Persists across client disconnects. One named workspace. - **Window** — like a tab inside a session. Each window is full-screen by default. - **Pane** — a split region inside a window. Created with `prefix` + `"` (horizontal) or `prefix` + `%` (vertical) by default. The corresponding `kill-*` commands destroy that level and everything below it: `kill-pane`, `kill-window`, `kill-session`, `kill-server` (nukes every session and shuts the daemon down). ## Full lifecycle ``` # Start a named session (always name them — `tmux ls` becomes useless otherwise) tmux new -s work # Do stuff. Then detach: # Press prefix + d # Back at the parent shell. List what's running: tmux ls # work: 1 windows (created Mon Apr 13 14:22:01 2026) [80x24] # Reattach to the most recent session: tmux attach # or `tmux a` for short # Reattach to a specific named session: tmux attach -t work # Switch to an existing session if you're already inside tmux, or create it if not: tmux new -A -s work # Kill a specific session by name: tmux kill-session -t work # Kill everything (every session, the server itself): tmux kill-server ``` `tmux ls` is short for `list-sessions`. From inside tmux, `prefix` + `s` opens an interactive tree mode for jumping between sessions, windows, and panes. ## Reattaching over SSH from another machine The canonical tmux workflow on remote servers: ``` ssh user@server tmux new -A -s main # attach if exists, create otherwise # ... run long-lived process ... # prefix + d to detach # Ctrl+D or `exit` to leave the SSH session — tmux keeps running on the server ``` Next day from a different laptop: ``` ssh user@server -t 'tmux attach -t main' ``` The `-t` flag forces a pseudo-TTY allocation, which tmux needs. Multiple clients can attach to the same session simultaneously — useful for pair programming. To force everyone else to disconnect when you attach, use `tmux attach -d`. ## SSH keep-alive pairing tmux protects you if the SSH connection drops, but a half-dead connection that hangs for minutes before timing out is its own annoyance. Add to `~/.ssh/config`: ``` Host * ServerAliveInterval 30 ServerAliveCountMax 3 ``` This sends a keepalive probe every 30 seconds and gives up after three failures (~90s), letting your local SSH client release the terminal quickly so you can reattach. If you're hitting `kex_exchange_identification` errors on reconnect, see SSH kex_exchange_identification Connection Reset: Troubleshooting. ## Common gotchas - **Mouse mode is off by default.** You can't click panes to focus them, scroll with the wheel, or drag pane borders until you add `set -g mouse on` to `~/.tmux.conf`. Once enabled, holding Shift while selecting text usually bypasses tmux and uses the native terminal selection. - **Copy-paste needs a bridge to the system clipboard.** tmux's internal paste buffer is separate from the OS clipboard. On Linux, pipe copy-mode selections through `xclip` or `wl-copy` (Wayland); on macOS, `pbcopy`. tmux 3.2+ exposes a `copy-command` option to centralize this. For remote sessions, the OSC 52 terminal escape sequence (enabled with `set -g set-clipboard on`) tells the local terminal emulator to put text on the local clipboard — works through SSH without X11 forwarding. - **Scrollback lives in copy mode.** Enter with `prefix` + `[`, scroll with arrows or Page-Up, exit with `q`. The terminal's own scrollback usually only shows what's currently rendered. - **Nested tmux** (tmux inside tmux, common when SSHing into a remote tmux from a local tmux) requires sending the prefix twice or rebinding the inner session. The conventional fix is `bind-key -n C-Space send-prefix` plus a different outer prefix. - **Config reload** does not happen automatically. After editing `~/.tmux.conf`, either restart the server or run `tmux source ~/.tmux.conf` (often bound to `prefix` + `r`). ## Common tmux.conf customizations Beyond the prefix swap and mouse mode, frequent additions: - Intuitive split bindings: `bind | split-window -h` and `bind - split-window -v` (the defaults `"` and `%` are mnemonically opaque). - Alt-arrow pane navigation without the prefix: `bind -n M-Left select-pane -L`, etc. - Bigger scrollback: `set -g history-limit 50000`. - 1-based window/pane numbering (`set -g base-index 1`, `setw -g pane-base-index 1`) so the leftmost window matches the `1` key. - 256-color / true-color: `set -g default-terminal "tmux-256color"` plus `set -ga terminal-overrides ',*256col*:Tc'`. ## Plugins: tpm, resurrect, continuum The tmux plugin manager (tpm) lives at `~/.tmux/plugins/tpm` and is bootstrapped from one line at the bottom of `~/.tmux.conf`. Plugins are declared with `set -g @plugin 'owner/repo'` and installed with `prefix` + `I`. The two near-universal plugins: - **tmux-resurrect** — snapshots sessions, windows, pane layouts, working directories, and (optionally) running programs. Save with `prefix` + `Ctrl+s`, restore with `prefix` + `Ctrl+r`. State files live in `~/.local/share/tmux/resurrect/`. - **tmux-continuum** — builds on resurrect to save automatically every 15 minutes and optionally restore on tmux startup (`set -g @continuum-restore 'on'`). Removes the "I lost my whole workspace after a reboot" failure mode. Other popular plugins include `tmux-yank` (clipboard helpers), `tmux-sensible` (defaults that almost everyone wants anyway), and themed status bars like `catppuccin/tmux`. ## tmux vs screen vs Zellij - **GNU Screen** (1987) is the original Unix terminal multiplexer. Single-process model, no client-server split. Still ships on many systems and works without configuration, but its keybindings are dated and it lacks vertical splits in some older builds. Use it when you can't install anything else and just need a process to outlive your SSH connection. - **tmux** (2007) uses a client-server architecture so multiple clients can attach to one session, is scriptable via the `tmux` command, and has the largest plugin ecosystem. The de facto power-user choice on servers. - **Zellij** (2021, written in Rust) is the modern entrant. Shows keybinding hints on screen, ships sensible defaults, supports WebAssembly plugins, and has built-in layouts. Higher baseline memory use than tmux but more discoverable for newcomers. Lacks tmux's two decades of plugin lore. All three solve the same core problem: detaching long-lived shell sessions from the terminal that started them. Pick tmux if you want maximum control and ubiquity, Zellij if you want a friendlier learning curve, Screen if you're stuck on a legacy system.