終端機設定

Pi 使用 Kitty keyboard protocol 進行可靠的修飾鍵檢測。大多數現代終端機都支援此協議，但有些需要設定。

開箱即用。

Pi 會在可用時啟用增強按鍵上報。如果 Terminal.app 仍然為 Shift+Enter 傳送普通 Return，pi 會使用本機 macOS modifier fallback，將該 Return 視為 Shift+Enter。

只有當 pi 與 Terminal.app 執行在同一台 Mac 上時，此 fallback 才有效。它無法透過遠端 SSH 檢測本機鍵盤。

新增到你的 Ghostty 設定（macOS 上為 ~/Library/Application Support/com.mitchellh.ghostty/config，Linux 上為 ~/.config/ghostty/config）：

keybind = alt+backspace=text:\x1b\x7f

較舊版本的 Claude Code 可能新增過這個 Ghostty 映射：

keybind = shift+enter=text:\n

該映射傳送一個原始換行字節。在 pi 內部，它與 Ctrl+J 無法區分，因此 tmux 和 pi 不再看到真正的 shift+enter 按鍵事件。

如果 Claude Code 2.x 或更新版本是你新增該映射的唯一原因，你可以將其刪除，除非你想在 tmux 中使用 Claude Code，因為它仍然需要 Ghostty 映射。

Pi 將 Ctrl+J 綁定為預設換行符別名，因此 Shift+Enter 透過重新映射繼續在 tmux 中工作，無需額外的 pi 設定。

WezTerm 通常透過 xterm modifyOtherKeys 開箱即用地執行 Shift+Enter。要顯式使用 Kitty 鍵盤協議，請建立 ~/.wezterm.lua：

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

在 macOS 上，WezTerm 預設將 Option+Enter 綁定到全螢幕。若要將 Option+Enter 用於 pi 的 follow-up 佇列，請新增這個按鍵覆蓋：

local wezterm = require 'wezterm'
local config = wezterm.config_builder()
config.keys = {
  {
    key = 'Enter',
    mods = 'ALT',
    action = wezterm.action.SendString('\x1b[13;3u'),
  },
}
return config

如果你已有一個 config.keys 表，請向其中新增條目。

在 WSL 上，WezTerm 可能需要可見的硬體游標來定位 IME 候選視窗。如果 CJK IME 候選項不跟隨文字游標，請在執行 pi 之前設定 PI_HARDWARE_CURSOR=1 或在設定中將 showHardwareCursor 設定為 true。

Alacritty 通常開箱即可支援 Shift+Enter。在 macOS 上，Option+Enter 可能會以普通 Enter 形式傳入。若要將 Option+Enter 用於 pi 的 follow-up 佇列，請將以下設定新增到 ~/.config/alacritty/alacritty.toml：

[[keyboard.bindings]]
key = "Enter"
mods = "Alt"
chars = "\u001b[13;3u"

更改設定後重新啟動 Alacritty。

VS Code 1.109.5 及更高版本預設在整合終端機中啟用 Kitty 鍵盤協議，因此 Shift+Enter 應該可以開箱即用。

早於 1.109.5 的 VS Code 版本需要 Shift+Enter 的顯式終端機鍵綁定。

keybindings.json 位置：

• macOS：~/Library/Application Support/Code/User/keybindings.json
• Linux：~/.config/Code/User/keybindings.json
• Windows：%APPDATA%\\Code\\User\\keybindings.json

新增到 keybindings.json：

{
  "key": "shift+enter",
  "command": "workbench.action.terminal.sendSequence",
  "args": { "text": "\u001b[13;2u" },
  "when": "terminalFocus"
}

將以下內容新增到 settings.json（Ctrl+Shift+, 或 Settings → Open JSON file），以轉發 pi 使用的 modified Enter 按鍵：

{
  "actions": [
    {
      "command": { "action": "sendInput", "input": "\u001b[13;2u" },
      "keys": "shift+enter"
    },
    {
      "command": { "action": "sendInput", "input": "\u001b[13;3u" },
      "keys": "alt+enter"
    }
  ]
}

• Shift+Enter 插入新行。
• Windows Terminal 預設將 Alt+Enter 綁定到全螢幕。這會阻止 pi 接收用於 follow-up 佇列的 Alt+Enter。
• 將 Alt+Enter 重新映射到 sendInput 會把真實的組合鍵轉發給 pi。

如果已有 actions 陣列，請將這些物件新增進去。如果舊的全螢幕行為仍然存在，請完全停用並重新開啟 Windows Terminal。

這些終端機的轉義序列支援有限。修改後的 Enter 鍵（如 Ctrl+Enter 和 Shift+Enter）無法與普通的 Enter 區分開來，從而阻止自訂鍵綁定（如 submit: ["ctrl+enter"]）工作。

為了獲得最佳體驗，請使用支援 Kitty 鍵盤協議的終端機：

• Kitty
• Ghostty
• WezTerm
• iTerm2
• Alacritty（需要編譯時啟用 Kitty 協議支援）

內建終端機對轉義序列的支援有限。在 IntelliJ 的終端機中，Shift+Enter 無法與 Enter 區分。

如果需要顯示硬體游標，請在執行 pi 之前設定 PI_HARDWARE_CURSOR=1（預設出於相容性停用）。

考慮使用專用的終端機模擬器以獲得最佳體驗。