🔄 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.
Every snippet on this page loads without errors in tmux 3.7c (checked October 2026)
tmux config essentials
A tmux config is just a list of options in ~/.tmux.conf. The four most common are turning on the mouse, starting window numbering at 1, raising the scrollback limit, and lowering escape-time so Vim and Neovim respond instantly to Esc (tmux 3.5 and newer already default to 10 ms). The popular snippets below cover these and more, and the config generator writes the file for you if you would rather not edit it by hand.
Config File Location & Reloading
Where tmux looks for its configuration file and how to apply changes without restarting.
📁 File Locations
When the server starts, tmux first loads the system-wide file (if present), then the first user file it finds:
/etc/tmux.conf— system-wide (Homebrew:$(brew --prefix)/etc/tmux.conf)~/.tmux.conf— user config (most common)$XDG_CONFIG_HOME/tmux/tmux.conf— XDG path~/.config/tmux/tmux.conf— XDG fallback (tmux 3.1+)
Config is read once, when the server starts. Edits do nothing until you reload or run tmux kill-server.
🔄 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. Also needed to move and resize floating panes (3.7+). |
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 " | [#{session_name}] | Content displayed on the left side of the status bar. Supports format variables. |
status-right | set -g status-right " %H:%M %d-%b " | pane title + time + date | Content displayed on the right side of the status bar. Supports strftime codes such as %H:%M. |
status-style | set -g status-style "bg=#1e1e2e,fg=#cdd6f4" | bg=green,fg=black | Colour and attributes of the status bar background. |
window-status-format | setw -g window-status-format " #I:#W " | #I:#W#F (index:name+flags) | Format string for inactive window entries in the status bar. |
window-status-current-format | setw -g window-status-current-format " #I:#W* " | #I:#W#F | 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" | green (yellow in copy mode, red when synchronized) | Visual style of the active (focused) pane border. |
message-style | set -g message-style "bg=#f38ba8,fg=#1e1e2e,fill=#f38ba8" | bg=yellow,fg=black,fill=yellow | Style of messages and the command prompt. tmux 3.7+: include fill= or the colour only covers the message text, not the whole status line. |
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 10 | 10 (500 before tmux 3.5) | Time (ms) tmux waits after Escape to tell it apart from a key sequence. On tmux 3.4 and older, set it to 10 to remove the Vim/Neovim Esc lag; raise it a little on slow SSH links. |
default-terminal | set -g default-terminal "tmux-256color" | tmux-256color if installed, else screen (tmux 3.3+) | The TERM value inside tmux. tmux-256color enables italics and 256 colours; use screen-256color on old systems without that terminfo entry. |
terminal-features | set -as terminal-features ",xterm-256color:RGB" | — | Tell tmux the outside terminal supports 24-bit colour (tmux 3.2+). On older versions use set -ga terminal-overrides ",*256col*:Tc". |
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 10
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
# 24-bit colour when the outer TERM is xterm-256color (iTerm2, Ghostty, WezTerm, Windows Terminal…)
# tmux 3.6+ also enables RGB automatically when COLORTERM=truecolor
set -g default-terminal "tmux-256color"
set -as terminal-features ",xterm-256color:RGB"
set -s escape-time 10
📋 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
# Pin a release, as the Catppuccin README recommends
set -g @plugin 'catppuccin/tmux#v2.3.1'
set -g @catppuccin_flavor 'mocha'
set -g @catppuccin_window_status_style 'rounded'
🌃 Tokyo Night Theme
.tmux.conf
# Tokyo Night via tmux-powerkit (formerly tmux-tokyo-night)
set -g @plugin 'fabioluciano/tmux-powerkit'
set -g @powerkit_theme 'tokyo-night'
set -g @powerkit_theme_variant 'storm'
set -g @powerkit_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"
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.