Frank
02883d3ed2
Copy of the legacy ~/.pi/agent/docs tree rebuilt as the command-center knowledge base: concept files promoted to path identity, index listings stripped of frontmatter, all wikilinks/relative links resolved, every checkable claim verified against the live fleet (Dankserver = Ryzen 7 7700X + RTX 3090; Strix Halo is Dankclaw), unverifiable claims tagged. kb-lint exits 0.
410 lines
9.8 KiB
Markdown
410 lines
9.8 KiB
Markdown
---
|
||
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*
|