mirror of
https://github.com/badlogic/pi-mono.git
synced 2026-05-03 00:30:21 +00:00
5b84152b17
This reverts 3929e0c181.
The Zellij-specific Kitty-query skip regresses Shift+Enter newline handling in Zellij. Restoring the previous behavior for now while we work on a safer fix that preserves both Alt and modified Enter handling.\n\nContext: https://github.com/badlogic/pi-mono/issues/3259
106 lines
3.4 KiB
Markdown
106 lines
3.4 KiB
Markdown
# Terminal Setup
|
|
|
|
Pi uses the [Kitty keyboard protocol](https://sw.kovidgoyal.net/kitty/keyboard-protocol/) for reliable modifier key detection. Most modern terminals support this protocol, but some require configuration.
|
|
|
|
## Kitty, iTerm2
|
|
|
|
Work out of the box.
|
|
|
|
## Ghostty
|
|
|
|
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`:
|
|
|
|
```lua
|
|
local wezterm = require 'wezterm'
|
|
local config = wezterm.config_builder()
|
|
config.enable_kitty_keyboard = true
|
|
return config
|
|
```
|
|
|
|
## VS Code (Integrated Terminal)
|
|
|
|
`keybindings.json` locations:
|
|
- macOS: `~/Library/Application Support/Code/User/keybindings.json`
|
|
- Linux: `~/.config/Code/User/keybindings.json`
|
|
- Windows: `%APPDATA%\\Code\\User\\keybindings.json`
|
|
|
|
Add to `keybindings.json` to enable `Shift+Enter` for multi-line input:
|
|
|
|
```json
|
|
{
|
|
"key": "shift+enter",
|
|
"command": "workbench.action.terminal.sendSequence",
|
|
"args": { "text": "\u001b[13;2u" },
|
|
"when": "terminalFocus"
|
|
}
|
|
```
|
|
|
|
## Windows Terminal
|
|
|
|
Add to `settings.json` (Ctrl+Shift+, or Settings → Open JSON file) to forward the modified Enter keys pi uses:
|
|
|
|
```json
|
|
{
|
|
"actions": [
|
|
{
|
|
"command": { "action": "sendInput", "input": "\u001b[13;2u" },
|
|
"keys": "shift+enter"
|
|
},
|
|
{
|
|
"command": { "action": "sendInput", "input": "\u001b[13;3u" },
|
|
"keys": "alt+enter"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
- `Shift+Enter` inserts a new line.
|
|
- Windows Terminal binds `Alt+Enter` to fullscreen by default. That prevents pi from receiving `Alt+Enter` for follow-up queueing.
|
|
- Remapping `Alt+Enter` to `sendInput` forwards the real key chord to pi instead.
|
|
|
|
If you already have an `actions` array, add the objects to it. If the old fullscreen behavior persists, fully close and reopen Windows Terminal.
|
|
|
|
## xfce4-terminal, terminator
|
|
|
|
These terminals have limited escape sequence support. Modified Enter keys like `Ctrl+Enter` and `Shift+Enter` cannot be distinguished from plain `Enter`, preventing custom keybindings such as `submit: ["ctrl+enter"]` from working.
|
|
|
|
For the best experience, use a terminal that supports the Kitty keyboard protocol:
|
|
- [Kitty](https://sw.kovidgoyal.net/kitty/)
|
|
- [Ghostty](https://ghostty.org/)
|
|
- [WezTerm](https://wezfurlong.org/wezterm/)
|
|
- [iTerm2](https://iterm2.com/)
|
|
- [Alacritty](https://github.com/alacritty/alacritty) (requires compilation with Kitty protocol support)
|
|
|
|
## IntelliJ IDEA (Integrated Terminal)
|
|
|
|
The built-in terminal has limited escape sequence support. Shift+Enter cannot be distinguished from Enter in IntelliJ's terminal.
|
|
|
|
If you want the hardware cursor visible, set `PI_HARDWARE_CURSOR=1` before running pi (disabled by default for compatibility).
|
|
|
|
Consider using a dedicated terminal emulator for the best experience.
|