fix(tui): add modifyOtherKeys fallback for modified enter keys in tmux

When Kitty keyboard protocol is not available (e.g. inside tmux), fall
back to xterm modifyOtherKeys mode 2 so that Shift+Enter, Ctrl+Enter,
and other modified keys are distinguishable from plain Enter.

tmux users need to add to ~/.tmux.conf:
  set -g extended-keys on
  set -g extended-keys-format csi-u

closes #1872
This commit is contained in:
Mario Zechner
2026-03-06 16:02:17 +01:00
parent cb6aef2ffb
commit bdf482cefc
5 changed files with 65 additions and 1 deletions

View File

@@ -0,0 +1,39 @@
# tmux Setup
Pi works inside tmux, but tmux strips modifier information from certain keys by default. Without configuration, `Shift+Enter` and `Ctrl+Enter` are indistinguishable from plain `Enter`.
## Required Configuration
Add to `~/.tmux.conf`:
```tmux
set -g extended-keys on
set -g extended-keys-format csi-u
```
Then restart tmux (not just reload):
```bash
tmux kill-server
tmux
```
This tells tmux to forward modified key sequences in CSI-u format when an application requests extended key reporting. Pi requests this automatically when Kitty keyboard protocol is not available.
## What This Fixes
Without this config, tmux collapses modified enter keys to plain `\r`:
| Key | Without config | With config |
|-----|---------------|-------------|
| Enter | `\r` | `\r` |
| Shift+Enter | `\r` | `\x1b[13;2u` |
| Ctrl+Enter | `\r` | `\x1b[13;5u` |
| Alt/Option+Enter | `\x1b\r` | `\x1b[13;3u` |
This affects the default keybindings (`Enter` to submit, `Shift+Enter` for newline) and any custom keybindings using modified enter keys.
## Requirements
- tmux 3.2 or later (run `tmux -V` to check)
- A terminal emulator that supports extended keys (Ghostty, Kitty, iTerm2, WezTerm, Windows Terminal)