NAME & SYNOPSIS
tmux — terminal multiplexer
tmux [-2uUV] [-C] [-c shell-command] [-f file] [-L socket-name] [-S socket-path] [command [flags]]
CLIENT-SERVER ARCHITECTURE & UNIX SOCKET PROTOCOL
Unlike traditional terminal emulators or shell wrappers, tmux operates on a decoupled Client-Server architecture powered by asynchronous I/O multiplexing via libevent:
1. The Daemon Server
A single master tmux server process manages all sessions, windows, pseudo-terminals (PTYs), and history buffers. It runs in the background independently of any GUI or SSH session.
2. The Thin Client
When you run tmux attach or open a terminal, a lightweight client process connects to the server via a UNIX domain socket, passing terminal capabilities, window resize signals (SIGWINCH), and keystrokes.
3. Pseudo-Terminal (PTY) Multiplexing
The server allocates master/slave PTY pairs for every pane, executing your shell (zsh, bash, fish) and capturing output into ring buffers even when disconnected.
By default, the UNIX domain socket is located at /tmp/tmux-UID/default. Communication between the client and server uses a binary frame protocol carrying file descriptors via SCM_RIGHTS messages over the local socket.
DESCRIPTION & HIERARCHICAL CONCEPTS
tmux structures your terminal workflow into a three-tier hierarchy:
- Session: An isolated collection of one or more windows managed by the server. Sessions persist across network disconnections and can be named according to project or server tasks.
- Window: A single virtual workspace occupying the full terminal screen, equivalent to browser tabs. Each window is subdivided into one or more rectangular panes.
- Pane: An individual pseudo-terminal running an independent shell process, CLI editor, or monitoring utility. Panes can be split horizontally or vertically and dynamically resized.
COMMAND LINE FLAGS & SOCKET RECIPES
Global command line flags accepted when launching the tmux binary:
-2— Force tmux to assume the terminal emulator supports 256 colors. Essential when connecting from legacy SSH clients that do not exportCOLORTERM=truecolor.-u— Explicitly force UTF-8 character encoding support, preventing box-drawing characters from rendering as question marks or garbled symbols.-C— Start in Control Mode protocol client. Used by modern GUI emulators (such as iTerm2 and Ghostty) to render native tabs and split panes managed by a remote tmux server (iTerm2 Integration Guide).-f file— Specify an alternate configuration file instead of the default~/.tmux.confor$XDG_CONFIG_HOME/tmux/tmux.conf.-L socket-name— Specify an isolated socket name under/tmp/tmux-UID/. Enables running completely independent tmux instances with separate plugins, keybindings, and memory pools.-S socket-path— Specify an absolute socket file path for multi-user collaborative pair programming.-V— Print the installed tmux version string (e.g.,tmux 3.6a).
Practical Socket Isolation & Pair Programming Recipes
# 1. Run a sandbox test server that won't interfere with your main daily tmux sessions:
tmux -L test-server -f ~/.tmux.test.conf new-session -s sandbox
# 2. Host a shared pair-programming session with group permissions:
tmux -S /var/tmux/shared-pair new-session -s collaboration
chmod 770 /var/tmux/shared-pair && chgrp devteam /var/tmux/shared-pair
# 3. Junior developer or peer connects in read-only observation mode:
tmux -S /var/tmux/shared-pair attach-session -t collaboration -r
CORE LIFECYCLE CLI COMMANDS
| Command | Shorthand | Description & Use Case |
|---|---|---|
tmux new-session -s name |
tmux new -s name |
Create and attach to a new named session (Session Masterclass) |
tmux attach-session -t name |
tmux a -t name |
Attach to an existing active session |
tmux attach -t name -d |
tmux a -t name -d |
Attach to session and detach any other connected clients (force fullscreen) |
tmux list-sessions |
tmux ls |
List all running sessions with window count and creation timestamp |
tmux kill-session -t name |
— | Terminate a specific session and kill all associated child processes |
tmux kill-server |
— | Instantly terminate the tmux server daemon and all active sessions |
tmux source-file ~/.tmux.conf |
tmux source ... |
Hot-reload configuration file without restarting active sessions |
INTERACTIVE KEY BINDINGS & PREFIX CUSTOMIZATION
tmux commands are dispatched from within an attached client by pressing a prefix key (default: Ctrl+b) followed by an action key:
Prefix + c— Create a new window positioned after the current window.Prefix + %— Split active pane vertically (left and right panes).Prefix + "— Split active pane horizontally (top and bottom panes).Prefix + d— Detach client safely, keeping all scripts and servers running in the background.Prefix + z— Toggle Pane Zoom (temporarily expand active pane to fullscreen).Prefix + [— Enter Copy Mode for scrollback buffer navigation and text selection (Full Keybinding Matrix).Prefix + :— Open interactive command prompt to run any tmux subcommand live.Prefix + q— Display pane index numbers overlays on screen for quick switching.Prefix + {/Prefix + }— Swap the active pane position with the previous or next pane.
CONFIGURATION DIRECTIVES & SERVER OPTIONS
Options can be scoped globally (-g), per-session (-s), or per-window/pane in ~/.tmux.conf using the set-option (or set) command.
Production Recommended Base Configuration
# Enable TrueColor 24-bit RGB and 256 colors
set -g default-terminal "tmux-256color"
set -ag terminal-overrides ",xterm-256color:RGB"
# Eliminate Escape key latency in Neovim/Vim
set -s escape-time 0
# Increase history scrollback memory buffer (default is only 2000 lines)
set -g history-limit 50000
# 1-based indexing for windows and panes (matches keyboard row layout)
set -g base-index 1
setw -g pane-base-index 1
set -g renumber-windows on
# Full mouse support for resizing, scrolling, and clicking panes
set -g mouse on
FORMAT SPECIFIERS & CONDITIONAL EXPRESSIONS
Format specifiers allow dynamic content customization in the status line, window titles, and commands using #{variable} syntax.
| Specifier | Description | Example Output / Usage |
|---|---|---|
#{session_name} (or #S) |
Name of the active tmux session | production-api |
#{window_index} (or #I) |
Index number of the active window | 1 |
#{window_name} (or #W) |
Name or running command of the window | nvim / docker-compose |
#{pane_current_path} |
Absolute path of active pane working directory | /srv/apps/tmux-web |
#{pane_pid} |
PID of the foreground process inside pane | 8142 |
#{client_prefix} |
Returns 1 when Prefix key is pressed, else 0 |
Used for dynamic visual indicator |
#{host_short} (or #h) |
Short hostname of host machine | macbook-pro |
Advanced Conditional Format Syntax
Format strings support ternary evaluation via #{?condition,true_branch,false_branch}:
# Highlight status line in bright yellow when Prefix key is active:
set -g status-left "#{?client_prefix,#[bg=yellow]#[fg=black] PREFIX #[default],#[bg=blue]#[fg=white] TMUX #[default]} [#S] "
# Display pane zoom indicator '[Z]' only when active pane is zoomed:
set -g window-status-current-format "#I:#W#{?window_zoomed_flag, [Z],}"
EVENT HOOKS & AUTOMATION TRIGGERS
tmux hooks allow executing custom commands or external shell scripts automatically when internal server events trigger:
# Alert notification when a new client attaches:
set-hook -g client-attached 'display-message -d 3000 "New Client Connected from #{client_tty}"'
# Change active pane border color on focus change:
set-hook -g pane-focus-in 'set -g pane-active-border-style fg=cyan,bold'
# Auto-save session state on window close:
set-hook -g session-window-changed 'run-shell -b "~/scripts/tmux-save-state.sh"'
BUFFERS, COPY MODE & SYSTEM CLIPBOARD
tmux maintains an internal stack of paste buffers populated whenever text is copied in copy-mode. Modern workflows integrate with the system clipboard via OSC 52 escape sequences or native clipboard CLI utilities:
tmux list-buffers(ortmux ls-b) — List all saved copy buffers and character counts.tmux show-buffer -b buffer-name— Print the raw text contents of a specific buffer.tmux paste-buffer(orPrefix + ]) — Paste the most recent buffer into the active pane.tmux choose-buffer— Interactive visual menu allowing selection of any previous copy history entry.set -s set-clipboard on— Enable bidirectional OSC 52 clipboard synchronization over SSH (Clipboard Masterclass).
CONFIGURATION FILES & ENVIRONMENT VARIABLES
~/.tmux.conf— User-specific configuration file loaded on server startup.$XDG_CONFIG_HOME/tmux/tmux.conf— Modern XDG standard user configuration location./etc/tmux.conf— System-wide default configuration file evaluated before user config.$TMUX— Automatically exported inside all tmux panes (format:socket_path,server_pid,session_index). Useful for shell scripts to detect whether they are executing inside tmux.$TMUX_PANE— Unique pane identifier (e.g.,%0,%1) exported inside each pane.
FREQUENTLY ASKED QUESTIONS
What is the difference between tmux -L and -S?
-L <name> isolates the server into a named socket located in your user's protected runtime directory (/tmp/tmux-$UID/<name>). -S <path> allows specifying an absolute socket path anywhere on the filesystem, enabling custom POSIX group permissions (e.g. chmod 770) for multi-user collaboration.
How do format variables and conditionals work in tmux?
Format variables use #{variable} syntax to query real-time server state (session name, active command, PID, current working directory). Conditionals follow #{?condition,true_val,false_val} for dynamic status line styling and indicators.
How does tmux achieve persistent sessions across SSH disconnections?
The tmux server daemon runs in its own process group detached from the SSH daemon. When your network drops, the SSH client terminates, but the tmux server keeps the PTYs and background programs running indefinitely until you reconnect and run tmux attach.