fix(tui,coding-agent): handle tmux xterm extended keys and warn on tmux setup fixes #1872

packages/coding-agent/docs/terminal-setup.md

@@ -8,13 +8,30 @@ Work out of the box.
 
 ## Ghostty
 
-Add to your Ghostty config (`~/.config/ghostty/config`):
+Add to your Ghostty config (`~/Library/Application Support/com.mitchellh.ghostty/config` on macOS, `~/.config/ghostty/config` on Linux):
 
 ```
 keybind = alt+backspace=text:\x1b\x7f
+```
+
+Older Claude Code versions may have added this Ghostty mapping:
+
+```
 keybind = shift+enter=text:\n
 ```
 
+That mapping sends a raw linefeed byte. Inside pi, that is indistinguishable from `Ctrl+J`, so tmux and pi no longer see a real `shift+enter` key event.
+
+If Claude Code 2.x or newer is the only reason you added that mapping, you can remove it, unless you want to use Claude Code in tmux, where it still requires that Ghostty mapping.
+
+If you want `Shift+Enter` to keep working in tmux via that remap, add `ctrl+j` to your pi `newLine` keybinding in `~/.pi/agent/keybindings.json`:
+
+```json
+{
+  "newLine": ["shift+enter", "ctrl+j"]
+}
+```
+
 ## WezTerm
 
 Create `~/.wezterm.lua`: