Most .tmux.conf files you find online are a decade old, riddled with options that have been renamed, deprecated, or silently ignored. This guide gives you a modern baseline — every line justified, nothing cargo-culted — that works on tmux 3.3+ without warnings.
The full config first
Paste this into ~/.tmux.conf. The sections below explain each block.
# ── server options ───────────────────────────────────────────────
set -sg escape-time 10
set -g default-terminal "tmux-256color"
set -ga terminal-overrides ",*:Tc"
set -g set-clipboard on
set -g allow-passthrough all
# ── session / window options ──────────────────────────────────────
set -g history-limit 50000
set -g mouse on
set -g base-index 1
setw -g pane-base-index 1
set -g window-size latest
# ── keybindings ───────────────────────────────────────────────────
unbind C-b
set -g prefix C-a
bind C-a send-prefix
bind | split-window -h -c "#{pane_current_path}"
bind - split-window -v -c "#{pane_current_path}"
unbind '"'
unbind %
bind r source-file ~/.tmux.conf ; display "Config reloaded."
# ── status bar (minimal baseline) ─────────────────────────────────
set -g status-interval 15
set -g status-left " #S "
set -g status-right " %H:%M "
# ── plugins (TPM — must be last) ──────────────────────────────────
# set -g @plugin 'tmux-plugins/tpm'
# run '~/.tmux/plugins/tpm/tpm'Server options: escape-time and scope
The single most common source of tmux startup warnings is escape-time set with the wrong scope.
set -sg escape-time 10escape-time is a server option, not a session option. You need the -s flag. Without it, modern tmux prints a deprecation warning every time you reload the config. The -g flag (global) is also required, giving you -sg. The value 10 ms is plenty — the historical default of 500 ms makes Vim/Neovim feel sluggish when you press Escape.
True color
set -g default-terminal "tmux-256color"
set -ga terminal-overrides ",*:Tc"Two lines, both required. The first tells tmux what $TERM to advertise inside panes. tmux-256color has a proper terminfo entry on modern distros and supports 256 colors natively. The second line appends the Tc (true color) capability to every terminal. The -ga flag appends rather than overwriting, so it stacks with any other overrides you add later.
Without Tc, tools like Neovim, bat, and delta fall back to 256 colors even though your terminal supports millions.
OSC 52 clipboard
set -g set-clipboard onOSC 52 is the escape sequence that lets a program inside a pane write to your system clipboard over SSH without any extra daemon. With set-clipboard on, tmux passes those sequences through to your terminal emulator, which handles the actual clipboard write.
One consequence: right-click paste becomes system-clipboard paste (owned by the terminal), not tmux paste-buffer. That is the right behavior when you want copy-out to feel native. If you layer tmux-yank on top later, set @yank_action 'copy-pipe' so the plugin writes to the system clipboard rather than the tmux buffer.
allow-passthrough
set -g allow-passthrough allSome programs — notably the Claude Code statusline and certain terminal multiplexer integrations — emit OSC or DCS sequences that tmux would otherwise eat. allow-passthrough all lets those sequences reach the outer terminal. The value all enables passthrough in all panes; the alternative on enables it only for the active pane.
History, mouse, base index
set -g history-limit 50000
set -g mouse on
set -g base-index 1
setw -g pane-base-index 1history-limit: 2000 lines (the default) runs out fast when you tail logs. 50 000 is a reasonable upper bound without blowing RAM on a typical server.
mouse on: lets you click to select panes, scroll with the wheel, and resize splits by dragging. You can still hold Shift to pass mouse events through to the program inside a pane (useful for terminal browsers or interactive TUIs).
base-index 1: windows start at 1, not 0. On a keyboard, 1 is immediately reachable with your left hand. 0 is at the far right of the number row. Apply the same shift to panes with pane-base-index 1.
window-size latest
set -g window-size latestOlder configs use aggressive-resize to prevent a small client from constraining the window size for all attached clients. That option is deprecated. window-size latest is the modern replacement: the window takes the size of the most recently active client rather than the smallest one. When you work from a large monitor and occasionally glance at a small terminal, the layout stays sane.
Prefix and split bindings
unbind C-b
set -g prefix C-a
bind C-a send-prefix
bind | split-window -h -c "#{pane_current_path}"
bind - split-window -v -c "#{pane_current_path}"
unbind '"'
unbind %Prefix: C-a is easier to reach than C-b and familiar to screen veterans. The bind C-a send-prefix line lets you press C-a C-a to send a literalC-a to the inner shell (useful for navigating to the start of a line inside a pane).
Splits: | for vertical divider (horizontal split), - for horizontal divider (vertical split). The -c "#{pane_current_path}" flag opens the new pane in the same directory as the current one — without this, splits always start in $HOME.
Reloading without restarting
bind r source-file ~/.tmux.conf ; display "Config reloaded."Press prefix r to reload the config in the running server. The display call shows a one-line confirmation in the status bar so you know it ran. Indispensable while you are iterating on the config.
Plugins block (commented out by default)
The plugin lines at the bottom are commented out intentionally. A clean config starts without TPM; you add plugins only when you have a specific need. See the plugins guide for when to uncomment them and which ones are worth it.
One rule: if you do enable TPM, the run '~/.tmux/plugins/tpm/tpm' line must be the last line in .tmux.conf. Anything after it may not be processed.
Verify the config loads cleanly
# from a new terminal (no tmux running)
tmux new-session
# or from inside tmux, reload and check for errors
prefix rIf tmux prints any warnings on startup, they will appear briefly in the status bar or be visible if you run tmux new-session from a plain terminal. The only warning you should not see after applying this config is the escape-time scope warning — that is the one -sg fixes.