Configuration

tmux reads configuration from ~/.tmux.conf at startup. This file lets you customize:

• The prefix key
• Key bindings
• Status bar appearance
• Default behaviors

Location

Create or edit ~/.tmux.conf:

If it doesn't exist, create it. We'll build one step by step.

Remapping prefix

The default Ctrl-b is awkward. Remap to Ctrl-a (GNU screen's default):

# ~/.tmux.conf
unbind C-b
set-option -g prefix C-a
bind C-a send-prefix

Now Ctrl-a is your prefix. Ctrl-a Ctrl-a sends literal Ctrl-a (useful in emacs).

Alternative prefix: Ctrl-space

unbind C-b
set-option -g prefix C-Space
bind C-Space send-prefix

Sensible key bindings

# Split panes with | and -
bind | split-window -h  # vertical split
bind - split-window -v  # horizontal split

# Navigate panes with Alt-arrow
bind -n M-Left select-pane -L
bind -n M-Right select-pane -R
bind -n M-Up select-pane -U
bind -n M-Down select-pane -D

# Resize panes with Ctrl-Shift-arrow
bind -n C-S-Left resize-pane -L 5
bind -n C-S-Right resize-pane -R 5
bind -n C-S-Up resize-pane -U 5
bind -n C-S-Down resize-pane -D 5

# Reload config
bind r source-file ~/.tmux.conf \; display-message "Config reloaded"

# Kill session/window/pane with confirmation
bind X confirm-before -p "kill session #S? (y/n)" "kill-session"
bind K confirm-before -p "kill window #W? (y/n)" "kill-window"
bind x confirm-before -p "kill pane #P? (y/n)" "kill-pane"

Vi mode for copy mode

# Vi mode
set-window-option -g mode-keys vi

# Vi-style copy mode
bind -T copy-mode-vi v send-keys -X begin-selection
bind -T copy-mode-vi y send-keys -X copy-selection-and-cancel

Now use vi keys in copy mode: v to select, y to yank.

Status bar customization

# Status bar position (bottom/top)
set-option -g status-position bottom

# Status bar colors
set-option -g status-style bg=#1a1a1a,fg=#ffffff

# Left side: session name
set-option -g status-left-length 40
set-option -g status-left "#[fg=green,bold]#S #[fg=default]"

# Right side: date time
set-option -g status-right-length 60
set-option -g status-right "#{?pane_synchronized,#[fg=red]SYNC #[default],}%H:%M %d-%b-%y"

# Window list
set-window-option -g window-status-format "#[fg=#666666]#I:#W "
set-window-option -g window-status-current-format "#[fg=green,bold]#I:#W* "

# Window status alignment
set-option -g status-justify centre

Pane borders

# Pane border colors
set-option -g pane-border-style fg=#333333
set-option -g pane-active-border-style fg=green

# Pane indicators (show pane number briefly)
set-option -g display-panes-colour blue
set-option -g display-panes-active-colour green

Increase scrollback

# Increase scrollback history
set-option -g history-limit 10000

Enable mouse mode

# Mouse support
set-option -g mouse on

Now you can:

• Scroll with mouse wheel
• Click to position cursor
• Drag to select text
• Click windows/panes to switch

Session management

# Auto-renumber windows
set-option -g renumber-windows on

# Start window numbers at 1
set-option -g base-index 1
set-window-option -g pane-base-index 1

# Don't rename windows automatically
set-option -g allow-rename off

Display messages

# Longer display time
set-option -g display-time 2000

# Activity monitoring
set-window-option -g monitor-activity on
set-option -g visual-activity on

# Bell
set-window-option -g monitor-bell on
set-option -g visual-bell on

New window/pane defaults

# Open new window/pane in current directory
bind c new-window -c "#{pane_current_path}"
bind | split-window -h -c "#{pane_current_path}"
bind - split-window -v -c "#{pane_current_path}"

Synchronize panes

# Toggle synchronize panes
bind * set-window-option synchronize-panes

Press Ctrl-a * (or your prefix) to toggle typing into all panes.

Example complete config

# ~/.tmux.conf - sensible defaults

# Prefix
unbind C-b
set-option -g prefix C-Space
bind C-Space send-prefix

# Split panes
bind | split-window -h -c "#{pane_current_path}"
bind - split-window -v -c "#{pane_current_path}"

# Navigate panes
bind -n M-Left select-pane -L
bind -n M-Right select-pane -R
bind -n M-Up select-pane -U
bind -n M-Down select-pane -D

# Reload config
bind r source-file ~/.tmux.conf \; display-message "Config reloaded!"

# Vi mode
set-window-option -g mode-keys vi
bind -T copy-mode-vi v send-keys -X begin-selection
bind -T copy-mode-vi y send-keys -X copy-selection-and-cancel

# Status bar
set-option -g status-position bottom
set-option -g status-style bg=#1a1a1a,fg=#ffffff
set-option -g status-left-length 40
set-option -g status-left "#[fg=green,bold]#S "
set-option -g status-right "%H:%M %d-%b-%y"
set-window-option -g window-status-format "#[fg=#666666]#I:#W "
set-window-option -g window-status-current-format "#[fg=green,bold]#I:#W* "

# Panes
set-option -g pane-border-style fg=#333333
set-option -g pane-active-border-style fg=green

# History
set-option -g history-limit 10000

# Indexing
set-option -g base-index 1
set-window-option -g pane-base-index 1
set-option -g renumber-windows on

# New window/pane in current directory
bind c new-window -c "#{pane_current_path}"

# Mouse
set-option -g mouse on

Reloading configuration

After editing ~/.tmux.conf, reload:

Or in tmux:

Then type: source-file ~/.tmux.conf

Checking current settings

Show all options:

Show specific option:

Platform-specific config

For macOS vs Linux:

# macOS: use pbcopy/pbpaste for clipboard
if-shell "uname | grep -q Darwin" \
  'bind -T copy-mode-vi y send-keys -X copy-pipe-and-cancel "pbcopy"'

# Linux: use xclip
if-shell "uname | grep -q Linux" \
  'bind -T copy-mode-vi y send-keys -X copy-pipe-and-cancel "xclip -selection clipboard"'

Troubleshooting

Config not loading?

• Check syntax: tmux -V (version 2.1+)
• Reload manually: tmux source-file ~/.tmux.conf
• Check for errors: tmux start-server \; show-options -g

Key bindings not working?

• Check for conflicts: tmux list-keys | grep 'prefix KEY'
• Verify prefix: tmux show-options -g | grep prefix

Next: Step 8 → Session Management & Scripting — Advanced workflows