Configuración del terminal

Pi usa el protocolo de teclado Kitty para una detección fiable de teclas modificadoras. La mayoría de terminales modernos admiten este protocolo, pero algunos requieren configuración.

Kitty, iTerm2

Funcionan sin configuración adicional.

Apple Terminal

Pi habilita informes de teclas mejorados cuando están disponibles. Si Terminal.app sigue enviando Return simple para Shift+Enter, pi usa un fallback local de modificadores de macOS para tratar ese Return como Shift+Enter.

Este fallback solo funciona cuando pi se ejecuta en el mismo Mac que Terminal.app. No puede detectar el teclado local por SSH remoto.

Ghostty

Añade a tu configuración de Ghostty (~/Library/Application Support/com.mitchellh.ghostty/config en macOS, ~/.config/ghostty/config en Linux):

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

Versiones antiguas de Claude Code pueden haber añadido este mapeo de Ghostty:

keybind = shift+enter=text:\n

Ese mapeo envía un byte de salto de línea crudo. Dentro de pi, es indistinguible de Ctrl+J, por lo que tmux y pi ya no ven un evento de tecla shift+enter real.

Si Claude Code 2.x o más reciente es la única razón por la que añadiste ese mapeo, puedes eliminarlo, a menos que quieras usar Claude Code en tmux, donde aún requiere ese mapeo de Ghostty.

Si quieres que Shift+Enter siga funcionando en tmux mediante ese remap, añade ctrl+j a tu atajo newLine de pi en ~/.pi/agent/keybindings.json:

{
  "newLine": ["shift+enter", "ctrl+j"]
}

WezTerm

WezTerm suele funcionar sin configuración para Shift+Enter vía xterm modifyOtherKeys. Para usar explícitamente el protocolo de teclado Kitty, crea ~/.wezterm.lua:

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

En macOS, WezTerm enlaza Option+Enter a pantalla completa por defecto. Para usar Option+Enter en la cola de seguimiento de pi, añade esta anulación de tecla:

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

Si ya tienes una tabla config.keys, añade la entrada a ella.

En WSL, WezTerm puede requerir un cursor de hardware visible para el posicionamiento de la ventana de candidatos IME. Si los candidatos IME CJK no siguen el cursor de texto, establece PI_HARDWARE_CURSOR=1 antes de ejecutar pi o configura showHardwareCursor en true en los ajustes.

Alacritty

Alacritty suele funcionar sin configuración para Shift+Enter. En macOS, Option+Enter puede llegar como plain Enter. Para usar Option+Enter en la cola de seguimiento de pi, añade a ~/.config/alacritty/alacritty.toml:

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

Reinicia Alacritty después de cambiar la configuración.

VS Code (terminal integrado)

VS Code 1.109.5 y posteriores habilitan el protocolo de teclado Kitty en el terminal integrado por defecto, por lo que Shift+Enter debería funcionar sin configuración.

Versiones de VS Code anteriores a 1.109.5 necesitan un atajo de terminal explícito para Shift+Enter.

Ubicaciones de keybindings.json:

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

Añade a keybindings.json:

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

Windows Terminal

Añade a settings.json (Ctrl+Shift+, o Configuración → Abrir archivo JSON) para reenviar las teclas Enter modificadas que pi usa:

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

• Shift+Enter inserta una nueva línea.
• Windows Terminal enlaza Alt+Enter a pantalla completa por defecto. Eso impide que pi reciba Alt+Enter para la cola de seguimiento.
• Remapear Alt+Enter a sendInput reenvía la combinación real a pi.

Si ya tienes un array actions, añade los objetos a él. Si persiste el comportamiento antiguo de pantalla completa, cierra y vuelve a abrir Windows Terminal por completo.

xfce4-terminal, terminator

Estos terminales tienen soporte limitado de secuencias de escape. Teclas Enter modificadas como Ctrl+Enter y Shift+Enter no se pueden distinguir de plain Enter, impidiendo atajos personalizados como submit: ["ctrl+enter"].

Para la mejor experiencia, usa un terminal que admita el protocolo de teclado Kitty:

• Kitty
• Ghostty
• WezTerm
• iTerm2
• Alacritty (requiere compilación con soporte del protocolo Kitty)

IntelliJ IDEA (terminal integrado)

El terminal integrado tiene soporte limitado de secuencias de escape. Shift+Enter no se puede distinguir de Enter en el terminal de IntelliJ.

Si quieres el cursor de hardware visible, establece PI_HARDWARE_CURSOR=1 antes de ejecutar pi (desactivado por defecto por compatibilidad).

Considera usar un emulador de terminal dedicado para la mejor experiencia.