🔄 Hot-Reloading Without Session Loss
Never terminate running build jobs to test a config edit. Add this hotkey to reload changes instantly:
bind r source-file ~/.tmux.conf \; display-message "✅ Config reloaded!"
Configuration Reference & Builder
Master Your tmux Configuration
The ~/.tmux.conf file is the brain of your terminal environment. It controls everything from
your prefix key and mouse behaviour to status bar content, TrueColor rendering, and copy-mode keybindings.
Use our interactive generator or choose from battle-tested production snippets below.
Production Tested for tmux v3.6a · macOS, Linux & WSL Compatible
Config File Location & Reloading
Where tmux looks for its configuration file and how to apply changes without restarting.
📁 File Locations
tmux looks for configuration in these locations, in order:
~/.tmux.conf— user config (most common)$XDG_CONFIG_HOME/tmux/tmux.conf— XDG path~/.config/tmux/tmux.conf— XDG fallback/etc/tmux.conf— system-wide config
🔄 Reload Without Restarting
After editing your config, reload it inside tmux without losing sessions:
bash / tmux command mode
# From outside tmux
$ tmux source-file ~/.tmux.conf
# From inside tmux (command mode)
$ Ctrl+b : source-file ~/.tmux.conf
# Bind reload to Ctrl+b r (add to .tmux.conf)
bind r source-file ~/.tmux.conf \; display "Config reloaded!"
Interactive .tmux.conf Generator
Tweak the controls and get a live, syntax-highlighted .tmux.conf preview. Copy or download your config in one click.
⚙ Options
~/.tmux.conf
Complete Option Reference
Every commonly used set-option and set-window-option documented with type, default, and description.
| Option | Command | Default | Description |
|---|---|---|---|
prefix | set -g prefix C-b | C-b | The key combination used to send commands to tmux. |
mouse | set -g mouse on | off | Enable mouse support: click to select panes/windows, scroll, resize panes. |
base-index | set -g base-index 1 | 0 | Starting index for window numbers. 1 is more ergonomic for keyboard switching. |
pane-base-index | setw -g pane-base-index 1 | 0 | Starting index for pane numbers within windows. |
history-limit | set -g history-limit 50000 | 2000 | Number of lines to keep in scrollback buffer per pane. |
status | set -g status on | on | Show or hide the status bar. |
status-position | set -g status-position top | bottom | Position of the status bar (top or bottom). |
status-interval | set -g status-interval 5 | 15 | How often (seconds) to refresh the status bar. |
status-left | set -g status-left " #S " | varies | Content displayed on the left side of the status bar. Supports format variables. |
status-right | set -g status-right " %H:%M %d-%b " | varies | Content displayed on the right side of the status bar. |
status-style | set -g status-style "bg=#1e1e2e,fg=#cdd6f4" | varies | Colour and attributes of the status bar background. |
window-status-format | setw -g window-status-format " #I:#W " | varies | Format string for inactive window entries in the status bar. |
window-status-current-format | setw -g window-status-current-format " #I:#W* " | varies | Format string for the active window entry in the status bar. |
pane-border-style | set -g pane-border-style "fg=#3b4261" | default | Visual style of inactive pane borders. |
pane-active-border-style | set -g pane-active-border-style "fg=#7aa2f7" | default | Visual style of the active (focused) pane border. |
message-style | set -g message-style "bg=#f38ba8,fg=#1e1e2e" | default | Style of command-mode and message prompts. |
mode-keys | setw -g mode-keys vi | emacs | Key mode for copy mode and command mode (emacs or vi). |
escape-time | set -sg escape-time 0 | 500 | Time (ms) tmux waits after Escape to determine if it is part of a key sequence. Set to 0 for neovim. |
default-terminal | set -g default-terminal "tmux-256color" | screen | The TERM value set inside tmux. Use tmux-256color for true-color support. |
terminal-overrides | set -ga terminal-overrides ",*256col*:Tc" | — | Override terminal capabilities. Add Tc for true-color in terminals that support it. |
renumber-windows | set -g renumber-windows on | off | Automatically renumber windows when one is closed, keeping numbers sequential. |
aggressive-resize | setw -g aggressive-resize on | off | Resize window to the smallest attached client only when viewing that window. |
Popular Config Snippets
Ready-to-copy blocks for the most common configuration patterns.
🏠 Sensible Defaults
.tmux.conf
set -g mouse on
set -g history-limit 50000
set -g base-index 1
setw -g pane-base-index 1
set -g renumber-windows on
set -sg escape-time 0
set -g default-terminal "tmux-256color"
set -ga terminal-overrides ",*256col*:Tc"
⌨️ Change Prefix to Ctrl+a
.tmux.conf
# Change prefix to Ctrl+a
unbind C-b
set -g prefix C-a
bind C-a send-prefix
🖱️ Enable Mouse Mode
.tmux.conf
# Click to select panes and windows
set -g mouse on
📋 Vi Copy Mode
.tmux.conf
# Vi-style navigation in copy mode
set-window-option -g mode-keys vi
bind-key -T copy-mode-vi v send-keys -X begin-selection
bind-key -T copy-mode-vi y send-keys -X copy-selection-and-cancel
🔀 Pane Navigation (Alt+Arrow)
.tmux.conf
💾 Resurrect + Continuum
.tmux.conf
# Session persistence across reboots
set -g @plugin 'tmux-plugins/tmux-resurrect'
set -g @plugin 'tmux-plugins/tmux-continuum'
set -g @continuum-restore 'on'
🎨 24-Bit TrueColor Support
.tmux.conf
# Enable RGB TrueColor for Alacritty, Kitty & iTerm2
set -g default-terminal "tmux-256color"
set -ag terminal-overrides ",xterm-256color:RGB"
set -s escape-time 0
📋 Cross-Platform OS Clipboard Sync
.tmux.conf
# macOS (pbcopy)
bind -T copy-mode-vi y send -X copy-pipe-and-cancel "pbcopy"
# Linux Wayland (wl-clipboard)
bind -T copy-mode-vi y send -X copy-pipe-and-cancel "wl-copy"
# Windows WSL (clip.exe)
bind -T copy-mode-vi y send -X copy-pipe-and-cancel "clip.exe"
🐱 Catppuccin Mocha Theme
.tmux.conf
# Catppuccin Mocha status bar
set -g @plugin 'catppuccin/tmux'
set -g @catppuccin_flavor 'mocha'
set -g @catppuccin_window_status_style 'rounded'
🌃 Tokyo Night Theme
.tmux.conf
# Tokyo Night theme preset
set -g @plugin 'fabioluciano/tmux-tokyo-night'
set -g @theme_variation 'moon'
set -g @theme_plugins 'datetime,battery'
🧛 Dracula Theme
.tmux.conf
set -g @plugin 'dracula/tmux'
set -g @dracula-show-powerline true
set -g @dracula-plugins "cpu-usage ram-usage time"
💾 Resurrect + Continuum
.tmux.conf
# Session persistence across reboots
set -g @plugin 'tmux-plugins/tmux-resurrect'
set -g @plugin 'tmux-plugins/tmux-continuum'
set -g @continuum-restore 'on'
Debugging & Best Practices
Crucial .tmux.conf Configuration Gotchas
Avoid the most common configuration pitfalls when setting up your terminal multiplexer.
⚠️ Status Bar Interval CPU Spikes
Setting status-interval 1 runs status line shell scripts every second. On battery power, this can drain CPU. Use 5 to 15 seconds for ideal balance.
set -g status-interval 10
📦 Plugin Loading Order Rule
When using TPM (Tmux Plugin Manager), the line run '~/.tmux/plugins/tpm/tpm' MUST always be the very last line of ~/.tmux.conf. Any options declared after it will be ignored by plugins.
Advanced Configuration Guides
⚡ Neovim + tmux Setup
Configure seamless Ctrl-hjkl split navigation, 24-bit TrueColor, OSC 52 clipboard, and eliminate vim escape delay.
🚀 Workspace Automation Scripts
Write reusable shell scripts with new-session, split-window, and send-keys to launch dev layouts instantly.
🤖 Claude Code in tmux
Run autonomous coding agents in persistent background sessions with multi-pane log monitoring.