docs: rebuild KB in OKF v0.1 with live-verified facts
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.
This commit is contained in:
Frank
@@ -0,0 +1,409 @@
|
||||
---
|
||||
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*
|
||||
Reference in New Issue
Block a user