Skills › Scientific Agent Skills › pi-agent › tmux.md

tmux.md

46 lines · skills/pi-agent/references/tmux.md at 5f2bc03

1# tmux Setup

3Source: https://pi.dev/docs/latest/tmux

5Reviewed against Pi 0.99.2 and the package versions listed in `../SKILL.md` on 2026-09-30.

7tmux strips modifier information from some keys by default, so without configuration `Shift+Enter` and `Ctrl+Enter` are indistinguishable from plain `Enter`.

tmux Setup

Source: https://pi.dev/docs/latest/tmux

Reviewed against Pi 0.99.2 and the package versions listed in ../SKILL.md on 2026-09-30.

tmux strips modifier information from some keys by default, so without configuration Shift+Enter and Ctrl+Enter are indistinguishable from plain Enter.

Raw lines 1 to 8

9## Recommended Configuration

11Add to `~/.tmux.conf`:

13```tmux

14set -g extended-keys on

15set -g extended-keys-format csi-u

16```

18Save work and close existing sessions before restarting. `tmux kill-server` terminates every session on that server:

20```bash

21tmux kill-server

22tmux

23```

25Pi requests extended key reporting automatically when the Kitty keyboard protocol is unavailable. `extended-keys-format csi-u` requires **tmux 3.5 or later** (check with `tmux -V`). With tmux 3.2–3.4, omit that line; Pi still supports tmux's default xterm `modifyOtherKeys` format.

Recommended Configuration

Add to ~/.tmux.conf:

set -g extended-keys on
set -g extended-keys-format csi-u

Save work and close existing sessions before restarting. tmux kill-server terminates every session on that server:

tmux kill-server
tmux

Pi requests extended key reporting automatically when the Kitty keyboard protocol is unavailable. extended-keys-format csi-u requires tmux 3.5 or later (check with tmux -V). With tmux 3.2–3.4, omit that line; Pi still supports tmux's default xterm modifyOtherKeys format.

Raw lines 9 to 26

27## Why csi-u

29With only `set -g extended-keys on`, tmux defaults to `extended-keys-format xterm` and forwards modified keys as `modifyOtherKeys` sequences — `Ctrl+C` as `ESC [27;5;99~`, `Ctrl+Enter` as `ESC [27;5;13~`. With `csi-u` the same keys arrive as `ESC [99;5u` and `ESC [13;5u`. Pi supports both formats; `csi-u` is the recommended setup.

Why csi-u

With only set -g extended-keys on, tmux defaults to extended-keys-format xterm and forwards modified keys as modifyOtherKeys sequences — Ctrl+C as ESC [27;5;99~, Ctrl+Enter as ESC [27;5;13~. With csi-u the same keys arrive as ESC [99;5u and ESC [13;5u. Pi supports both formats; csi-u is the recommended setup.

Raw lines 27 to 30

31## What It Fixes

33`ESC` below is the escape byte (`0x1b`).

35| Key | Without extended keys | With `csi-u` |

36|---|---|---|

37| Enter | `CR` | `CR` |

38| Shift+Enter | `CR` | `ESC [13;2u` |

39| Ctrl+Enter | `CR` | `ESC [13;5u` |

40| Alt/Option+Enter | `ESC CR` | `ESC [13;3u` |

42This affects the default bindings (Enter to submit, Shift+Enter for newline) and any custom keybindings using modified Enter.

What It Fixes

ESC below is the escape byte (0x1b).

Key	Without extended keys	With `csi-u`
Enter	`CR`	`CR`
Shift+Enter	`CR`	`ESC [13;2u`
Ctrl+Enter	`CR`	`ESC [13;5u`
Alt/Option+Enter	`ESC CR`	`ESC [13;3u`

This affects the default bindings (Enter to submit, Shift+Enter for newline) and any custom keybindings using modified Enter.

Raw lines 31 to 43

44## Requirements

46tmux 3.5+ for `extended-keys-format csi-u`, plus a terminal emulator that supports extended keys: Ghostty, Kitty, iTerm2, WezTerm, or Windows Terminal.

Requirements

tmux 3.5+ for extended-keys-format csi-u, plus a terminal emulator that supports extended keys: Ghostty, Kitty, iTerm2, WezTerm, or Windows Terminal.

Raw lines 44 to 46