Terminal Setup

Source: https://pi.dev/docs/latest/terminal-setup

Pi uses the Kitty keyboard protocol for reliable modifier detection. Most modern terminals support it; some need setup.

Works Out of Box

Kitty and iTerm2 work out of the box. Apple Terminal uses enhanced key reporting when available and a local macOS fallback for Shift+Enter when running on the same Mac.

Ghostty

Add:

text

keybind = alt+backspace=text:

Remove older shift+enter=text: mappings unless needed for other tools. If keeping that mapping for tmux, add ctrl+j to Pi's newline keybinding.

WezTerm

Usually works. To force Kitty keyboard:

lua

local wezterm = require 'wezterm'
local config = wezterm.config_builder()
config.enable_kitty_keyboard = true
return config

On macOS, remap Option+Enter to send [13;3u if you want follow-up queueing.

Alacritty

On macOS, add Alt+Enter binding to send [13;3u.

VS Code Integrated Terminal

VS Code 1.109.5+ enables Kitty keyboard by default. Older versions need a Shift+Enter workbench.action.terminal.sendSequence keybinding sending [13;2u.

Windows Terminal

Add actions for Shift+Enter ([13;2u) and Alt+Enter ([13;3u). Fully restart if old fullscreen behavior persists.

Limited Terminals

xfce4-terminal, terminator, and IntelliJ's integrated terminal cannot distinguish modified Enter keys reliably. Use a terminal with Kitty keyboard support for the best experience.