sscoble/pi-mono
1
0
Fork 0
mirror of https://github.com/badlogic/pi-mono.git synced 2026-11-05 23:37:25 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 4
pi-mono/packages/coding-agent/docs/tmux.md
Petr Houška 6de14ec098
docs(coding-agent): note tmux 3.6 color reply leak in tmux guide (#11645) 
Adds a troubleshooting section to the tmux guide
(`packages/coding-agent/docs/tmux.md`, published at
https://pi.dev/docs/latest/tmux) for the color-code text that tmux 3.6
types into the editor at startup.

tmux 3.6 forwards Pi's palette queries to the outer terminal. When a
reply reaches tmux split across reads, tmux treats its bytes as key
presses and sends them to Pi as typed text. tmux 3.7 fixes this
([tmux#4749](https://github.com/tmux/tmux/issues/4749),
[tmux#4793](https://github.com/tmux/tmux/issues/4793)). Pi cannot filter
the text because it arrives exactly like typing.

The section also notes that switching to a fixed theme does not help:
`applyFromSettings()` queries terminal colors regardless of the theme,
which reporters confirmed in #10679 (`--use-theme dark`) and #10256
(`"theme": "dark"`).

Related: #10250, #10679, #10256.
2026-10-31 17:29:36 +01:00

2.1 KiB
Raw Blame History

Run Pi in tmux

Pi works inside tmux, but tmux can report Shift+Enter, Ctrl+Enter, and plain Enter as the same key. Enable extended keys so Pi can distinguish them.

Check your tmux version

tmux -V

For tmux 3.5 or newer, use the recommended CSI-u configuration below. For tmux 3.2 through 3.4, use the older-version configuration.

Enable extended keys in tmux 3.5 or newer

Add these lines to ~/.tmux.conf:

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

Pi requests extended-key reporting when the terminal does not provide the Kitty keyboard protocol directly. CSI-u is the most reliable format for forwarding modified keys through tmux.

Restart tmux

The configuration applies to the tmux server. To guarantee that it is active, close your tmux sessions and start a new server.

If you choose to stop the server from the command line, save your work first. This command terminates every session managed by that server:

tmux kill-server
tmux

Verify modified keys

Start Pi inside the new tmux session and check that:

  1. Shift+Enter inserts a new line in the editor.
  2. Enter submits the prompt.
  3. Alt+Enter queues a follow-up on macOS and Linux. Windows and WSL use Ctrl+Q by default.

If these keys still behave like plain Enter, verify that the terminal outside tmux can report modified keys. See Configure your terminal.

Use tmux 3.2 through 3.4

These versions support extended keys but not extended-keys-format csi-u. Add only:

set -g extended-keys on

Pi supports the xterm modifyOtherKeys format used by these versions. Restart tmux and repeat the verification steps.

For older versions, upgrade tmux or use Pi outside tmux rather than relying on modified Enter shortcuts.

Color codes appear in the editor with tmux 3.6

If text such as c0c/0c0c/0c0c appears in the editor at startup, upgrade tmux to 3.7 or newer. tmux 3.6 sometimes sends the terminal's color replies to Pi as typed text (tmux#4749). Changing Pi's theme does not help.