Tmux

tmux is a terminal multiplexer. It creates, manages, and persists multiple terminal sessions within a single terminal connection. Sessions survive disconnection. Windows and panes subdivide the terminal into simultaneous workspaces. All state is managed by a server process running independently of any attached client.

tmux operates entirely within the terminal. It requires no graphical environment, no display server, and no vendor account. Configuration is a plaintext file. The tooling is FOSS, maintained independently, and produces no telemetry.

Installation

Platform	Command
Arch Linux	`sudo pacman -S tmux`
Alpine Linux	`apk add tmux`
Ubuntu / Debian	`sudo apt install tmux`
Rocky Linux / RHEL	`sudo dnf install tmux`

Verify the installation and version:

tmux -V

The configuration file path is ~/.tmux.conf. tmux reads it on server start. Apply changes to a running server with:

prefix + :source-file ~/.tmux.conf

Or from the shell:

tmux source-file ~/.tmux.conf

Core Architecture

tmux operates across four distinct layers. Understanding the hierarchy is prerequisite to using the tool correctly.

Layer	Definition
Server	A background process managing all sessions. Starts automatically on first `tmux` invocation. Persists until all sessions are destroyed or the server is explicitly killed.
Session	A named collection of windows. Sessions persist after client detachment. A session is the primary unit of work organisation.
Window	A single screen within a session. Windows contain one or more panes. A session holds any number of windows.
Pane	A subdivision of a window. Each pane runs an independent shell or process. Panes are created by splitting windows horizontally or vertically.

The relationship is strictly hierarchical: server contains sessions, sessions contain windows, windows contain panes.

A client attaches to a session. Detaching a client leaves the session and all its processes running. Re-attaching from any terminal resumes exactly where the session was left.

The Prefix Key

Every tmux key binding consists of two steps: press the prefix key, release it, then press the command key. The default prefix is Ctrl-b.

This manual uses prefix to denote the prefix key throughout.

Action	Keys
Send prefix to shell	`prefix prefix`
Enter command mode	`prefix :`
List all key bindings	`prefix ?`

The prefix is configurable. The most common alternative is Ctrl-a, which matches the GNU Screen convention. Changing it is covered in the configuration section.

Sessions

Creating Sessions

Command	Action
`tmux`	Start tmux with an unnamed session
`tmux new`	Create a new session
`tmux new -s {name}`	Create a named session
`tmux new -s {name} -d`	Create a named session in the background (detached)
`prefix :new-session -s {name}`	Create named session from within tmux
`prefix $`	Rename current session

Naming sessions is a discipline worth adopting immediately. Unnamed sessions are numbered sequentially and become indistinguishable in long-running server states.

Attaching and Detaching

Command	Action
`prefix d`	Detach current client from session
`tmux attach`	Attach to most recent session
`tmux attach -t {name}`	Attach to named session
`tmux attach -d -t {name}`	Attach and detach all other clients from session
`tmux a`	Shorthand for `tmux attach`

Listing and Navigating Sessions

Command	Action
`tmux ls`	List all sessions from the shell
`prefix s`	Open interactive session tree
`prefix (`	Switch to previous session
`prefix )`	Switch to next session
`prefix L`	Switch to last (most recently used) session
`prefix $`	Rename current session

The interactive session tree (prefix s) shows sessions, windows, and panes in a navigable tree. Use arrow keys to expand nodes and Enter to switch.

Killing Sessions

Command	Action
`prefix :kill-session`	Kill current session
`tmux kill-session -t {name}`	Kill named session from shell
`tmux kill-server`	Kill the server and all sessions

Windows

Creating and Navigating Windows

Command	Action
`prefix c`	Create a new window
`prefix ,`	Rename current window
`prefix n`	Next window
`prefix p`	Previous window
`prefix {N}`	Go to window N (0-indexed)
`prefix w`	Open interactive window list
`prefix '`	Prompt for window index to switch to
`prefix l`	Switch to last (most recently used) window
`prefix f`	Search for window by name

Moving and Managing Windows

Command	Action
`prefix .`	Move window to specified index
`prefix :swap-window -t {N}`	Swap current window with window N
`prefix :move-window -t {session}:{N}`	Move window to another session
`prefix &`	Kill current window (with confirmation)
`prefix :kill-window`	Kill current window

Window Layouts

tmux provides five built-in pane layout presets. Apply them with prefix Space to cycle through, or directly:

Layout	Command
Even horizontal	`prefix :select-layout even-horizontal`
Even vertical	`prefix :select-layout even-vertical`
Main horizontal	`prefix :select-layout main-horizontal`
Main vertical	`prefix :select-layout main-vertical`
Tiled	`prefix :select-layout tiled`
Cycle layouts	`prefix Space`

Panes

Splitting Panes

Command	Action
`prefix %`	Split current pane vertically (left and right)
`prefix "`	Split current pane horizontally (top and bottom)
`prefix :split-window -v`	Split vertically (explicit)
`prefix :split-window -h`	Split horizontally (explicit)
`prefix :split-window -v -p 30`	Split vertically, new pane takes 30%

Navigating Panes

Command	Action
`prefix o`	Cycle to next pane
`prefix {arrow key}`	Move to pane in arrow direction
`prefix q`	Display pane numbers briefly; press number to jump
`prefix ;`	Switch to last active pane
`prefix {`	Swap current pane with previous
`prefix }`	Swap current pane with next

Resizing Panes

Command	Action
`prefix Ctrl-{arrow}`	Resize pane by one cell in arrow direction
`prefix Alt-{arrow}`	Resize pane by five cells in arrow direction
`prefix :resize-pane -D {N}`	Resize down by N cells
`prefix :resize-pane -U {N}`	Resize up by N cells
`prefix :resize-pane -L {N}`	Resize left by N cells
`prefix :resize-pane -R {N}`	Resize right by N cells

Pane Operations

Command	Action
`prefix z`	Toggle current pane fullscreen (zoom)
`prefix x`	Kill current pane (with confirmation)
`prefix !`	Break pane out into a new window
`prefix :join-pane -t {window}`	Pull a pane from another window
`prefix :rotate-window`	Rotate panes within window

Copy Mode

Copy mode suspends input to the active pane and enters a scroll and selection interface. It uses either Emacs or vi key bindings, configurable in tmux.conf.

Entering and Exiting Copy Mode

Command	Action
`prefix [`	Enter copy mode
`prefix PgUp`	Enter copy mode and scroll up one page
`q` or `Escape`	Exit copy mode

Key	Action
`h j k l`	Move cursor
`w / b`	Next / previous word
`f{char}`	Jump to char on line
`0 / $`	Start / end of line
`g`	Top of history
`G`	Bottom of history
`Ctrl-d / Ctrl-u`	Scroll half-screen down / up
`Ctrl-f / Ctrl-b`	Scroll full-screen down / up
`/{pattern}`	Search forward
`?{pattern}`	Search backward
`n / N`	Next / previous search match

Selecting and Copying Text (vi bindings)

Key	Action
`Space`	Begin selection
`v`	Begin selection (alternative)
`V`	Select entire line
`Ctrl-v`	Toggle block (rectangle) selection
`Enter` or `y`	Copy selection and exit copy mode
`A`	Append selection to paste buffer

Pasting

Command	Action
`prefix ]`	Paste most recent paste buffer
`prefix :choose-buffer`	Select from all paste buffers
`prefix =`	Open paste buffer list interactively

With set-clipboard on and a terminal that supports OSC 52, tmux synchronises its paste buffer with the system clipboard automatically.

Command Mode

prefix : opens tmux command mode, equivalent to Vim's :. Any tmux command runs here directly.

Useful Direct Commands

Command	Action
`prefix :new-window -n {name}`	Create named window
`prefix :split-window -h -c "#{pane_current_path}"`	Split, inherit current directory
`prefix :send-keys -t {pane} "{keys}" Enter`	Send keystrokes to a specific pane
`prefix :set -g {option} {value}`	Set a global option at runtime
`prefix :setw -g {option} {value}`	Set a window option at runtime
`prefix :show-options -g`	Display all global options
`prefix :list-keys`	Display all key bindings
`prefix :list-commands`	Display all tmux commands
`prefix :info`	Display server and session information

Status Bar

The status bar sits at the bottom of the tmux screen by default. It displays session name, window list, and configurable status fields.

Status Bar Anatomy

Region	Default Content
Left	Session name
Centre	Window list with active window highlighted
Right	Date and time

All three regions are configurable with format strings. Format strings use #{} variable interpolation.

Common Format Variables

Variable	Value
`#{session_name}`	Current session name
`#{window_index}`	Current window index
`#{window_name}`	Current window name
`#{pane_index}`	Current pane index
`#{pane_current_path}`	Current pane working directory
`#{pane_current_command}`	Command running in current pane
`#{host}`	Hostname
`#{client_width}`	Terminal width
`#(command)`	Output of shell command

Configuration — `tmux.conf` Annotated

Configuration file location: ~/.tmux.conf

# PREFIX

# remap prefix from ctrl-b to ctrl-a
# ctrl-a is reachable without moving the left hand
unbind C-b
set-option -g prefix C-a
bind-key C-a send-prefix


# TERMINAL

# set terminal type for 24-bit colour support
set -g default-terminal "tmux-256color"
set -ag terminal-overrides ",xterm-256color:RGB"

# reduce escape key delay to zero
# non-zero delays break vim mode-switching latency
set -sg escape-time 0

# extend scrollback buffer to 10000 lines
set -g history-limit 10000

# enable focus events for vim autoread compatibility
set -g focus-events on

# start window and pane numbering at 1 (0 is too far from the prefix key)
set -g base-index 1
setw -g pane-base-index 1

# renumber windows sequentially after closing one
set -g renumber-windows on


# STATUS BAR

# position the status bar at the top
set -g status-position top

# refresh interval in seconds
set -g status-interval 5

# STATUS BAR COLOURS
# pure black background, white text, dark green accent
set -g status-style "bg=#000000 fg=#ffffff"
set -g window-status-current-style "bg=#005F00 fg=#ffffff bold"
set -g window-status-style "bg=#000000 fg=#ffffff"
set -g message-style "bg=#005F00 fg=#ffffff"
set -g pane-border-style "fg=#ffffff"
set -g pane-active-border-style "fg=#005F00"

# STATUS BAR CONTENT
set -g status-left " #S "
set -g status-left-length 20
set -g status-right " #{pane_current_path} | %H:%M "
set -g status-right-length 60
setw -g window-status-format " #I:#W "
setw -g window-status-current-format " #I:#W "


# KEY BINDINGS

# vi key bindings in copy mode
setw -g mode-keys vi

# split panes with | and -; inherit current directory
bind | split-window -h -c "#{pane_current_path}"
bind - split-window -v -c "#{pane_current_path}"
unbind '"'
unbind %

# open new windows in current directory
bind c new-window -c "#{pane_current_path}"

# vim-style pane navigation without prefix
bind h select-pane -L
bind j select-pane -D
bind k select-pane -U
bind l select-pane -R

# vim-style pane resizing
bind -r H resize-pane -L 5
bind -r J resize-pane -D 5
bind -r K resize-pane -U 5
bind -r L resize-pane -R 5

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

# toggle synchronise-panes: send input to all panes simultaneously
bind S setw synchronize-panes \; display "synchronise toggled"


# COPY MODE

# begin selection with v (vi visual mode convention)
bind -T copy-mode-vi v send-keys -X begin-selection

# copy with y; route to system clipboard via wl-clipboard (wayland)
# for x11, replace wl-copy with: xclip -selection clipboard
bind -T copy-mode-vi y send-keys -X copy-pipe-and-cancel "wl-copy"

# rectangle selection with ctrl-v
bind -T copy-mode-vi C-v send-keys -X rectangle-toggle

# mouse support
set -g mouse on


# CLIPBOARD

# allow tmux to set the terminal clipboard via osc 52
set -g set-clipboard on


# PLUGINS (if using tpm)
# set -g @plugin 'tmux-plugins/tpm'
# set -g @plugin 'tmux-plugins/tmux-resurrect'
# run '~/.tmux/plugins/tpm/tpm'

Scripting tmux

tmux accepts all its commands non-interactively from the shell. This enables full session scripting: reproducible workspace layouts that spin up with a single command.

Shell Command Syntax

Command	Action
`tmux new-session -d -s {name}`	Create detached session
`tmux new-window -t {session}:{N} -n {name}`	Create named window at index N
`tmux split-window -t {session}:{window}`	Split a window
`tmux send-keys -t {session}:{window}.{pane} "{cmd}" Enter`	Send command to pane
`tmux select-window -t {session}:{N}`	Set active window
`tmux attach -t {session}`	Attach to session

Example: Development Workspace Script

#!/usr/bin/env bash

# WORKSPACE SETUP
# launches a reproducible tmux layout for a project session

SESSION="dev"

# abort if session already exists
tmux has-session -t "$SESSION" 2>/dev/null && tmux attach -t "$SESSION" && exit 0

# create session, start detached
tmux new-session -d -s "$SESSION" -n "edit"

# EDITOR WINDOW
# start neovim in the project root
tmux send-keys -t "$SESSION:edit" "cd ~/projects/myproject && nvim ." Enter

# SHELL WINDOW
# clean shell for running commands
tmux new-window -t "$SESSION" -n "shell"
tmux send-keys -t "$SESSION:shell" "cd ~/projects/myproject" Enter

# LOGS WINDOW
# split: left for build output, right for service logs
tmux new-window -t "$SESSION" -n "logs"
tmux split-window -h -t "$SESSION:logs"
tmux send-keys -t "$SESSION:logs.left"  "journalctl -f -u myservice" Enter
tmux send-keys -t "$SESSION:logs.right" "tail -f /var/log/nginx/access.log" Enter

# MONITOR WINDOW
# split into four panes for system monitoring
tmux new-window -t "$SESSION" -n "monitor"
tmux split-window -h -t "$SESSION:monitor"
tmux split-window -v -t "$SESSION:monitor.left"
tmux split-window -v -t "$SESSION:monitor.right"
tmux send-keys -t "$SESSION:monitor.top-left"    "htop" Enter
tmux send-keys -t "$SESSION:monitor.bottom-left" "watch -n2 df -h" Enter
tmux send-keys -t "$SESSION:monitor.top-right"   "watch -n2 free -h" Enter
tmux send-keys -t "$SESSION:monitor.bottom-right" "watch -n2 ss -tulnp" Enter

# return to editor window on attach
tmux select-window -t "$SESSION:edit"

# attach
tmux attach -t "$SESSION"

Targeting Syntax Reference

tmux identifies targets with a {session}:{window}.{pane} format.

Target Format	Refers To
`myproject`	Session named `myproject`
`myproject:2`	Window 2 of session `myproject`
`myproject:edit`	Window named `edit` of session `myproject`
`myproject:2.1`	Pane 1 of window 2 of session `myproject`
`:`	Current session
`:.`	Current window

Conditional Session Attachment

A one-liner that creates a session if it does not exist and attaches if it does:

tmux has-session -t mysession 2>/dev/null \
  && tmux attach -t mysession \
  || tmux new-session -s mysession

Sending Keys to Multiple Panes

With synchronize-panes enabled, input goes to all panes in a window simultaneously. This is useful for running the same command across multiple servers over SSH.

# enable synchronise-panes on window "servers"
tmux setw -t mysession:servers synchronize-panes on

# send a command to all panes
tmux send-keys -t mysession:servers "uptime" Enter

# disable afterwards
tmux setw -t mysession:servers synchronize-panes off

Plugin Management with TPM

TPM (tmux Plugin Manager) installs and manages tmux plugins. It is optional. The core tmux configuration above requires nothing beyond tmux itself.

Installing TPM

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

Add to the end of ~/.tmux.conf:

# PLUGINS
set -g @plugin 'tmux-plugins/tpm'

# add plugins here
set -g @plugin 'tmux-plugins/tmux-resurrect'

# initialise tpm (keep this line at the very end)
run '~/.tmux/plugins/tpm/tpm'

TPM Commands

Command	Action
`prefix I`	Install plugins declared in config
`prefix U`	Update all plugins
`prefix Alt-u`	Remove unlisted plugins

tmux-resurrect

tmux-resurrect saves and restores session state across server restarts and reboots. It records window layouts, pane contents, and running programmes.

set -g @plugin 'tmux-plugins/tmux-resurrect'

# restore neovim sessions (requires vim-obsession or similar)
set -g @resurrect-strategy-nvim 'session'

Command	Action
`prefix Ctrl-s`	Save session state
`prefix Ctrl-r`	Restore session state

Plugin choice should remain minimal. Each plugin adds a dependency and a maintenance surface. tmux's native scripting covers most automation needs without TPM.

Cheatsheet

Sessions

Command	Action
`tmux`	Start tmux
`tmux new -s {name}`	New named session
`tmux ls`	List sessions
`tmux attach -t {name}`	Attach to session
`tmux kill-session -t {name}`	Kill session
`tmux kill-server`	Kill all sessions
`prefix d`	Detach
`prefix s`	Session tree
`prefix (` / `)`	Previous / next session
`prefix $`	Rename session

Windows

Command	Action
`prefix c`	New window
`prefix ,`	Rename window
`prefix n` / `p`	Next / previous window
`prefix {N}`	Go to window N
`prefix w`	Window list
`prefix &`	Kill window
`prefix l`	Last window

Panes

Command	Action
`prefix \\|`	Split vertical (this config)
`prefix -`	Split horizontal (this config)
`prefix {arrow}`	Navigate pane
`prefix q`	Show pane numbers
`prefix z`	Zoom pane (toggle)
`prefix x`	Kill pane
`prefix !`	Break pane to window
`prefix Space`	Cycle layouts
`prefix {` / `}`	Swap pane with previous / next
`prefix Ctrl-{arrow}`	Resize pane (1 cell)
`prefix Alt-{arrow}`	Resize pane (5 cells)

Copy Mode (vi)

Key	Action
`prefix [`	Enter copy mode
`h j k l`	Navigate
`v`	Begin selection
`V`	Select line
`Ctrl-v`	Block selection
`y`	Copy and exit
`prefix ]`	Paste
`/ or ?`	Search forward / backward
`q`	Exit copy mode

This Config's Custom Bindings

Key	Action
`Ctrl-a`	Prefix (replaces Ctrl-b)
`prefix \\|`	Vertical split, current directory
`prefix -`	Horizontal split, current directory
`prefix h/j/k/l`	Navigate panes
`prefix H/J/K/L`	Resize panes (5 cells)
`prefix r`	Reload config
`prefix S`	Toggle synchronise-panes
`prefix c`	New window, current directory

Shell Commands

Command	Action
`tmux new -d -s {name}`	New detached session
`tmux send-keys -t {target} "{cmd}" Enter`	Send keys to pane
`tmux split-window -h -t {target}`	Split target window
`tmux select-window -t {target}`	Set active window
`tmux source-file ~/.tmux.conf`	Reload config
`tmux show-options -g`	Show all global options
`tmux list-keys`	List all bindings

Installation

Core Architecture

The Prefix Key

Sessions

Creating Sessions

Attaching and Detaching

Listing and Navigating Sessions

Killing Sessions

Windows

Creating and Navigating Windows

Moving and Managing Windows

Window Layouts

Panes

Splitting Panes

Navigating Panes

Resizing Panes

Pane Operations

Copy Mode

Entering and Exiting Copy Mode

Navigation in Copy Mode (vi bindings)

Selecting and Copying Text (vi bindings)

Pasting

Command Mode

Useful Direct Commands

Status Bar

Status Bar Anatomy

Common Format Variables

Configuration — tmux.conf Annotated

Scripting tmux

Shell Command Syntax

Example: Development Workspace Script

Targeting Syntax Reference

Conditional Session Attachment

Sending Keys to Multiple Panes

Plugin Management with TPM

Installing TPM

TPM Commands

tmux-resurrect

Cheatsheet

Sessions

Windows

Panes

Copy Mode (vi)

This Config's Custom Bindings

Shell Commands

Configuration — `tmux.conf` Annotated