Modern tmux Configuration (2026)

A clean, opinionated tmux setup with session persistence, Catppuccin theming, and sensible defaults.

Features

• Ctrl-a prefix - Easier to reach than Ctrl-b
• Vi keybindings - In copy mode and command prompt
• Session persistence - Auto-save every 15 minutes, auto-restore on start
• Catppuccin mocha theme - Pretty colors without requiring Nerd Fonts
• Manual window naming - Names stick when you set them
• 50k scrollback - Generous history for long build logs

Prerequisites

Install TPM (Tmux Plugin Manager):

git clone https://github.com/tmux-plugins/tpm ~/.tmux/plugins/tpm

Installation

Save the config below as ~/.tmux.conf, then:

1. Start tmux: tmux
2. Install plugins: Ctrl-a I (capital I)
3. Reload: Ctrl-a :source-file ~/.tmux.conf

The Config

# =============================================================================
# PLUGINS (via TPM)
# =============================================================================
# Plugin ordering matters! Continuum must be last (uses status-right hook)

set -g @plugin 'tmux-plugins/tpm'
set -g @plugin 'tmux-plugins/tmux-resurrect'
set -g @plugin 'catppuccin/tmux'
set -g @plugin 'tmux-plugins/tmux-continuum'

# -----------------------------------------------------------------------------
# Resurrect: save/restore sessions
# -----------------------------------------------------------------------------
# Optional: restore neovim sessions (requires neovim session plugin)
# set -g @resurrect-strategy-nvim 'session'

# -----------------------------------------------------------------------------
# Catppuccin theme
# -----------------------------------------------------------------------------
set -g @catppuccin_flavor "mocha"

# Window tabs: show window name so manual renames (Ctrl-a ,) work
set -g @catppuccin_window_text " #W"
set -g @catppuccin_window_current_text " #W"

# -----------------------------------------------------------------------------
# Continuum: auto-save/restore (MUST BE LAST - uses status-right hook)
# -----------------------------------------------------------------------------
set -g @continuum-restore 'on'       # Auto-restore when tmux starts
set -g @continuum-save-interval '15' # Auto-save every 15 minutes

# =============================================================================
# PREFIX KEY
# =============================================================================
# Ctrl-a is easier to reach than Ctrl-b
unbind C-b
set -g prefix C-a
bind C-a send-prefix  # Press Ctrl-a twice to send Ctrl-a to nested tmux/app

# =============================================================================
# GENERAL SETTINGS
# =============================================================================
set -g mouse on
set -g renumber-windows on           # No gaps in window numbering
set -g allow-rename off              # Don't let programs rename windows
set -g automatic-rename off          # Don't auto-rename; manual names stick
set -g clock-mode-style 24           # 24-hour clock
set -g history-limit 50000           # Generous scrollback

# Vi keybindings
set -g status-keys vi                # Vi keys in command prompt (Ctrl-a :)
set -g mode-keys vi                  # Vi keys in copy mode (Ctrl-a [)

# Modern terminal integration
set -g focus-events on               # Pass focus events to apps (neovim)
set -s escape-time 10                # Responsive Esc key (ms)
set -g default-terminal "tmux-256color"

# Truecolor support
set -ag terminal-overrides ",xterm-256color:RGB"

# =============================================================================
# STATUS BAR (right side)
# =============================================================================
# Two pills: date (darker) and time (lighter) using Catppuccin mocha colors
# surface0 = #313244, surface1 = #45475a, text = #cdd6f4
set -g status-right "#[fg=#cdd6f4,bg=#313244] %d/%m #[fg=#cdd6f4,bg=#45475a] %H:%M:%S "

# =============================================================================
# INITIALIZE TPM (keep at very bottom)
# =============================================================================
run '~/.tmux/plugins/tpm/tpm'

Key Bindings Cheat Sheet

Binding	Action
Ctrl-a	Prefix (was Ctrl-b)
Ctrl-a c	New window
Ctrl-a ,	Rename window
Ctrl-a n/p	Next/previous window
Ctrl-a [	Enter copy mode (vi keys)
Ctrl-a ]	Paste
Ctrl-a :	Command prompt (vi keys)
Ctrl-a d	Detach
Ctrl-a $	Rename session
Ctrl-a I	Install plugins (TPM)
Ctrl-a Ctrl-s	Manual save (resurrect)
Ctrl-a Ctrl-r	Manual restore (resurrect)

Copy Mode (Vi)

Enter with Ctrl-a [, then:

Key	Action
hjkl	Navigate
v	Start selection
y	Yank (copy)
/	Search forward
?	Search backward
q	Exit copy mode

Notes

• Session persistence: Your windows, panes, and working directories are saved automatically every 15 minutes and restored when you start tmux.
• No Nerd Fonts required: This config intentionally avoids icons that need special fonts.
• Neovim sessions: Uncomment @resurrect-strategy-nvim if you have neovim session management configured.

Troubleshooting

Plugins not loading?

• Make sure TPM is installed: ls ~/.tmux/plugins/tpm
• Install plugins: Ctrl-a I
• Reload config: Ctrl-a :source-file ~/.tmux.conf

Theme looks wrong?

• Kill tmux server and restart: tmux kill-server && tmux