---
type: reference
title: tmux
description: Terminal multiplexer configuration, extended-keys setup, keyboard input best practices, and reload/restart procedures.
tags:
  - terminal
  - multiplexer
  - tmux
timestamp: 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](#extended-keys-configuration)
2. [Best Practices for Keyboard Input](#best-practices-for-keyboard-input)
3. [Reloading vs. Restarting tmux](#reloading-vs-restarting-tmux)
4. [Essential Configuration Reference](#essential-configuration-reference)
5. [Troubleshooting](#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`:

```tmux
# 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

```tmux
# 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:

```tmux
# 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:

```tmux
# 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

```tmux
# 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

```tmux
# 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

```tmux
# 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**
```bash
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)
```tmux
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:**
```bash
# 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+)
```bash
# 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`

```tmux
# ============================================
# 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:**
   ```bash
   tmux -V
   ```
   Must be 3.5+ for `extended-keys-format csi-u`.

2. **Verify configuration is loaded:**
   ```bash
   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:**
   ```bash
   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:
```tmux
set -sg escape-time 0
```

### Mouse scrolling not working in copy mode

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

### Clipboard not working

For Linux:
```tmux
bind -T copy-mode-vi y send -X copy-pipe-and-cancel "xclip -selection clipboard -i"
```

For macOS:
```tmux
bind -T copy-mode-vi y send -X copy-pipe-and-cancel "pbcopy"
```

---

## References

- [tmux Manual Page](https://man7.org/linux/man-pages/man1/tmux.1.html)
- [tmux GitHub Wiki](https://github.com/tmux/tmux/wiki)
- [Pi tmux Setup Documentation](https://pi.dev/docs/latest/tmux)

---

*Documentation last updated: June 2026*
*Tested with tmux 3.6b*