SOP-006: Configuration

Fresh

Field	Value
Document ID	SOP-006
Version	1.1
Status	Active
tmux Version	3.6b
Last Updated	2026-05-26

Purpose

Customize tmux behavior, keybindings, and appearance through configuration.

Prerequisites

• tmux installed (SOP-001)
• Text editor access

Configuration File

tmux reads configuration from ~/.tmux.conf at startup.

Procedure

Creating Configuration File

# Create or edit config file
touch ~/.tmux.conf

# Edit with your preferred editor
vim ~/.tmux.conf
# or
nano ~/.tmux.conf

Reloading Configuration

After changes, reload without restarting:

# From command line
tmux source-file ~/.tmux.conf

# From within tmux
:source-file ~/.tmux.conf

# Or with a keybinding (add to config):
bind r source-file ~/.tmux.conf \; display "Reloaded!"

Then press Ctrl+b r to reload instantly.

Essential Configuration

Change Prefix Key

The default Ctrl+b can be changed:

# Change to Ctrl+a (screen-style)
unbind C-b
set-option -g prefix C-a
bind-key C-a send-prefix

# Or Ctrl+Space
# unbind C-b
# set-option -g prefix C-Space
# bind-key C-Space send-prefix

Enable Mouse Support

set -g mouse on

This enables:

• Pane selection by clicking
• Pane resizing by dragging borders
• Window selection from status bar
• Scrolling in copy mode

Vi Mode Keys

setw -g mode-keys vi

Start Windows/Panes at 1

set -g base-index 1
setw -g pane-base-index 1

Auto-renumber Windows

set -g renumber-windows on

Keybinding Configuration

# Split panes with | and -
bind | split-window -h
bind - split-window -v
unbind '"'
unbind %

# Navigate panes with vim keys
bind h select-pane -L
bind j select-pane -D
bind k select-pane -U
bind l select-pane -R

# Resize panes with vim keys
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

# Quick reload
bind r source-file ~/.tmux.conf \; display "Reloaded!"

The -r flag

The -r flag makes a keybinding "repeatable" - you can press it multiple times without the prefix.

Status Bar Configuration

# Status bar position
set -g status-position bottom

# Status bar colors
set -g status-style 'bg=#333333 fg=#ffffff'

# Left side: session name
set -g status-left '#[fg=#000000,bg=#10b981] #S #[bg=#333333] '
set -g status-left-length 40

# Right side: date and time
set -g status-right '#[fg=#ffffff] %Y-%m-%d %H:%M '
set -g status-right-length 40

# Window status
setw -g window-status-format ' #I:#W '
setw -g window-status-current-format '#[fg=#000000,bg=#10b981] #I:#W '

Complete Starter Configuration

# ~/.tmux.conf - Comprehensive starter config

# ========== General Settings ==========
set -g default-terminal "screen-256color"
set -g history-limit 50000
set -g display-time 4000
set -g status-interval 5
set -g focus-events on
set -sg escape-time 0

# ========== Prefix Key ==========
# Change to Ctrl+a
unbind C-b
set -g prefix C-a
bind C-a send-prefix

# ========== Mouse ==========
set -g mouse on

# ========== Indexing ==========
set -g base-index 1
setw -g pane-base-index 1
set -g renumber-windows on

# ========== Vi Mode ==========
setw -g mode-keys vi

# ========== Key Bindings ==========
# Reload config
bind r source-file ~/.tmux.conf \; display "Reloaded!"

# Better splits
bind | split-window -h -c "#{pane_current_path}"
bind - split-window -v -c "#{pane_current_path}"
unbind '"'
unbind %

# Vim-style pane navigation
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

# Window navigation
bind -r C-h previous-window
bind -r C-l next-window

# ========== Copy Mode ==========
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

# ========== Status Bar ==========
set -g status-position bottom
set -g status-style 'bg=#1e1e2e fg=#cdd6f4'

set -g status-left '#[fg=#1e1e2e,bg=#89b4fa,bold] #S #[bg=#1e1e2e] '
set -g status-left-length 40

set -g status-right '#[fg=#cdd6f4] %H:%M #[fg=#1e1e2e,bg=#89b4fa] %d-%b '
set -g status-right-length 40

setw -g window-status-format ' #I:#W '
setw -g window-status-current-format '#[fg=#1e1e2e,bg=#a6e3a1,bold] #I:#W '

# ========== Pane Borders ==========
set -g pane-border-style 'fg=#45475a'
set -g pane-active-border-style 'fg=#89b4fa'

Configuration Options Reference

Option	Description	Example
set -g	Set global option	set -g mouse on
setw -g	Set window option	setw -g mode-keys vi
bind	Create keybinding	bind r reload
unbind	Remove keybinding	unbind C-b
bind -r	Repeatable keybinding	bind -r H resize

New Options in tmux 3.6 New in 3.6

# Pane scrollbars: off | on | modal
set -g pane-scrollbars modal
set -g pane-scrollbars-position right
set -g pane-scrollbars-style 'fg=#89b4fa,bg=#313244,width=1,pad=0'

# Cap columns in the tiled layout (0 = unlimited)
setw -g tiled-layout-max-columns 3

# Clock with seconds
set -g clock-mode-style 24-with-seconds

# Pane borders drawn with spaces
set -g pane-border-lines spaces

# Style the command prompt cursor (replaces the emulated cursor)
set -g prompt-cursor-style blinking-bar
set -g prompt-cursor-colour '#89b4fa'

# Longer first repeat for repeatable keys, then reduced
set -g initial-repeat-time 400

Option	Values / Notes
pane-scrollbars	off, on, modal
pane-scrollbars-position	left, right
pane-scrollbars-style	style string with width and pad attributes
tiled-layout-max-columns	number, 0 = unlimited
clock-mode-style	12, 24, 12-with-seconds, 24-with-seconds
pane-border-lines	adds a spaces value
prompt-cursor-style / prompt-cursor-colour	command prompt cursor
initial-repeat-time	first repeat time for -r keys (ms)
codepoint-widths	override the width of individual Unicode codepoints
input-buffer-size	size of the input buffer
no-detach-on-destroy	client option for detach-on-destroy
default-client-command	command used when tmux runs without one

Style attributes

3.6 adds a set-default style attribute that fully replaces the default colours and attributes, and a noattr attribute (usable in mode-style) to control whether attributes are applied or ignored.

Verification

Check configuration syntax:

# Try loading config (errors will show)
tmux source-file ~/.tmux.conf

# Check specific option
tmux show-options -g prefix

Troubleshooting

Config not loading on startup

Solution

Ensure file is named correctly and in home directory:

ls -la ~/.tmux.conf

Syntax error in config

Solution

tmux will show error messages. Common issues:

• Missing quotes around strings
• Typos in option names
• Using = instead of space for values

Keybinding conflicts

Solution

List current bindings to find conflicts:

tmux list-keys | grep <key>

Use unbind to remove conflicting bindings.

Colors not working

Solution

Ensure terminal supports 256 colors:

set -g default-terminal "screen-256color"
# or
set -g default-terminal "tmux-256color"

See Also

• Quick Reference: Shortcuts
• Quick Reference: Commands
• Workflow: Multi-Project Setup