command-center/omp-docs/tools/tmux.md

type, title, description, tags, timestamp

type	title	description	tags	timestamp
reference	tmux	Terminal multiplexer configuration, extended-keys setup, keyboard input best practices, and reload/restart procedures.	terminal multiplexer tmux	2026-08-06

tmux Configuration Guide

Complete reference for tmux keyboard configuration, extended-keys, and best practices.

Verified for tmux 3.6 (June 2026)

---

Table of Contents

1. Extended Keys Configuration
2. Best Practices for Keyboard Input
3. Reloading vs. Restarting tmux
4. Essential Configuration Reference
5. Troubleshooting

---

Extended Keys Configuration

What is extended-keys?

The extended-keys option enables tmux to forward modified key combinations (keys pressed with Shift, Ctrl, Alt/Meta, or other modifiers) to applications running inside tmux. Without this configuration, tmux strips modifier information from certain keys by default.

Why is it needed?

By default, tmux cannot distinguish between many modified key combinations:

Key	Without extended-keys	With extended-keys (csi-u)
Enter	\r	\r
Shift+Enter	\r (indistinguishable!)	\x1b[13;2u
Ctrl+Enter	\r (indistinguishable!)	\x1b[13;5u
Alt/Option+Enter	\x1b\r	\x1b[13;3u

This affects:

• Applications that rely on modified Enter keys (like Pi, Neovim, etc.)
• Custom keybindings using Shift+Enter, Ctrl+Enter, etc.
• Any application using the Kitty keyboard protocol or CSI-u format

The Recommended Configuration

Add these lines to ~/.tmux.conf:

# Enable extended key reporting
set -g extended-keys on

# Use CSI-u format (requires tmux 3.5+)
set -g extended-keys-format csi-u

Why csi-u format is recommended

tmux supports two formats for extended keys:

1. xterm (default): Uses modifyOtherKeys format

   • Ctrl+C → \x1b[27;5;99~
   • Ctrl+D → \x1b[27;5;100~
   • Ctrl+Enter → \x1b[27;5;13~

2. csi-u (recommended): Uses CSI-u format

   • Ctrl+C → \x1b[99;5u
   • Ctrl+D → \x1b[100;5u
   • Ctrl+Enter → \x1b[13;5u

The csi-u format is more reliable and is the modern standard. Applications like Pi automatically request extended key reporting when Kitty keyboard protocol is not available.

Requirements

• tmux 3.5 or later for extended-keys-format csi-u
  • Check version: tmux -V
  • For tmux 3.2–3.4, omit the extended-keys-format line. The default xterm format still works
• A terminal emulator that supports extended keys:
  • Ghostty
  • Kitty
  • iTerm2
  • WezTerm
  • Windows Terminal

---

Best Practices for Keyboard Input and Keybindings

Essential Settings

# Fix Vim ESC delay (tmux 3.5+ already defaults to 10ms)
set -sg escape-time 0

# Increase scrollback buffer
set -g history-limit 50000

# Start windows and panes at 1, not 0
set -g base-index 1
setw -g pane-base-index 1

# Enable mouse support
set -g mouse on

# Enable focus events for vim autoread
set -g focus-events on

# Set terminal with proper colors
set -g default-terminal "tmux-256color"
set -as terminal-features ",xterm-256color:RGB"

# Aggressive resize for multi-client
setw -g aggressive-resize on

Prefix Key Customization

The default prefix C-b is awkward. Common alternatives:

# Option 1: Change to Ctrl+a (common, but conflicts with readline)
unbind C-b
set -g prefix C-a
bind-key C-a send-prefix

# Option 2: Use Alt+w or another comfortable combination
set -g prefix M-w
bind-key M-w send-prefix

Intuitive Split Commands

Replace the default " and % with visual separators:

# Split panes using | and -
bind | split-window -h -c "#{pane_current_path}"
bind - split-window -v -c "#{pane_current_path}"
unbind '"'
unbind %

Vim-Style Pane Navigation

# Switch panes using Alt+arrow without prefix
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

# Or use vim-style hjkl (requires prefix)
bind h select-pane -L
bind j select-pane -D
bind k select-pane -U
bind l select-pane -R

Copy Mode Configuration

# Use vi keys in copy mode
setw -g mode-keys vi

# Vi-style copy bindings
bind -T copy-mode-vi v send -X begin-selection
bind -T copy-mode-vi y send -X copy-pipe-and-cancel "xclip -selection clipboard -i"  # Linux
# bind -T copy-mode-vi y send -X copy-pipe-and-cancel "pbcopy"  # macOS

Quick Config Reload Binding

# Reload config with C-a r (or your prefix + r)
bind r source-file ~/.tmux.conf \; display-message "Config reloaded!"

---

Reloading vs. Restarting tmux

Reloading Configuration (Preserves Sessions)

For most configuration changes, you can reload without losing sessions:

Method 1: Command-line

tmux source-file ~/.tmux.conf

Method 2: From within tmux

1. Press your prefix key (default C-b)
2. Type : to open the command prompt
3. Enter: source-file ~/.tmux.conf

Method 3: Using a keybinding (recommended)

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

Then press C-b r (or your configured prefix + r).

When Full Restart is Required

Some changes require a complete tmux server restart:

• extended-keys and extended-keys-format changes
• default-terminal changes
• Server-level options like message-limit
• Changes to terminal features

Full restart procedure:

# 1. Detach from current session (if attached)
# Press: C-b d

# 2. Kill the tmux server (ends all sessions)
tmux kill-server

# 3. Start fresh
tmux

Alternative: Restart while preserving sessions (tmux 3.2+)

# 1. Save session state (requires tmux-resurrect plugin)
# Press: C-a C-s

# 2. Kill server
tmux kill-server

# 3. Restart and restore
tmux
# Press: C-a C-r (to restore sessions)

Quick Reference: Reload vs. Restart

Change Type	Reload OK?	Restart Required?
Keybindings	✅ Yes	❌ No
Status bar styles	✅ Yes	❌ No
Mouse settings	✅ Yes	❌ No
Copy mode bindings	✅ Yes	❌ No
extended-keys	❌ No	✅ Yes
extended-keys-format	❌ No	✅ Yes
default-terminal	❌ No	✅ Yes
escape-time	⚠️ Sometimes	✅ Yes (for full effect)

---

Essential Configuration Reference

Complete Production-Ready ~/.tmux.conf

# ============================================
# ESSENTIAL SETTINGS
# ============================================

# Extended keys (required for modern applications)
set -g extended-keys on
set -g extended-keys-format csi-u

# Fix Vim ESC delay
set -sg escape-time 0

# Increase scrollback buffer
set -g history-limit 50000

# Start windows and panes at 1, not 0
set -g base-index 1
setw -g pane-base-index 1

# Enable mouse support
set -g mouse on

# Enable focus events for vim autoread
set -g focus-events on

# Set terminal with proper colors
set -g default-terminal "tmux-256color"
set -as terminal-features ",xterm-256color:RGB"

# Aggressive resize for multi-client
setw -g aggressive-resize on

# ============================================
# KEY BINDINGS
# ============================================

# Change prefix to Ctrl+a (more ergonomic)
unbind C-b
set -g prefix C-a
bind C-a send-prefix

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

# Better pane splitting (and keep current path)
bind | split-window -h -c "#{pane_current_path}"
bind - split-window -v -c "#{pane_current_path}"
bind c new-window -c "#{pane_current_path}"

# 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

# ============================================
# COPY MODE
# ============================================

# Use vi keys
setw -g mode-keys vi

# Vi-style copy bindings
bind -T copy-mode-vi v send -X begin-selection
# Linux:
bind -T copy-mode-vi y send -X copy-pipe-and-cancel "xclip -selection clipboard -i"
# macOS:
# bind -T copy-mode-vi y send -X copy-pipe-and-cancel "pbcopy"

---

Troubleshooting

Modified keys still not working

1. Check tmux version:

   tmux -V
   

   Must be 3.5+ for extended-keys-format csi-u.

2. Verify configuration is loaded:

   tmux show-options -g extended-keys
   tmux show-options -g extended-keys-format
   

3. Ensure terminal supports extended keys:

   • Test in Ghostty, Kitty, iTerm2, WezTerm, or Windows Terminal
   • Some older terminals do not support the CSI-u format

4. Full restart required:

   tmux kill-server
   tmux
   

Configuration changes not taking effect

• Most changes: Use tmux source-file ~/.tmux.conf
• Extended keys changes: Must restart with tmux kill-server
• Check for errors: Look at the first session created after restart for error messages

Escape key delay

If you experience delay when pressing Escape:

set -sg escape-time 0

Mouse scrolling not working in copy mode

bind -n WheelUpPane copy-mode -e
bind -n WheelDownPane copy-mode -e

Clipboard not working

For Linux:

bind -T copy-mode-vi y send -X copy-pipe-and-cancel "xclip -selection clipboard -i"

For macOS:

bind -T copy-mode-vi y send -X copy-pipe-and-cancel "pbcopy"

---

References

• tmux Manual Page
• tmux GitHub Wiki
• Pi tmux Setup Documentation

---

Documentation last updated: June 2026 Tested with tmux 3.6b