Configuración de terminales

Pi usa Kitty keyboard protocol para una detección confiable de la tecla modificadora. La mayoría de los terminales modernos admiten este protocolo, pero algunos requieren configuración.

Trabaje fuera de la caja.

Pi habilita informes clave mejorados cuando estén disponibles. Si Terminal.app aún envía un retorno simple para Shift+Enter, pi usa un modificador alternativo de macOS local para tratar ese retorno como Shift+Enter.

Este respaldo solo funciona cuando pi se ejecuta en la misma Mac que Terminal.app. No puede detectar el teclado local a través del control remoto SSH.

Agregue a su configuración de Ghostty (~/Library/Application Support/com.mitchellh.ghostty/config en macOS, ~/.config/ghostty/config en Linux):

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

Es posible que las versiones anteriores de Claude Code hayan agregado este mapeo Ghostty:

keybind = shift+enter=text:\n

Ese mapeo envía un byte de avance de línea sin formato. Dentro de pi, eso es indistinguible de Ctrl+J, por lo que tmux y pi ya no ven un evento clave shift+enter real.

Si Claude Code 2.x o posterior es la única razón por la que agregó ese mapeo, puede eliminarlo, a menos que desee usar Claude Code en tmux, donde todavía requiere ese mapeo Ghostty.

Pi vincula Ctrl+J como alias de nueva línea predeterminado, por lo que Shift+Enter sigue trabajando en tmux a través de esa reasignación sin configuración pi adicional.

WezTerm generalmente funciona de inmediato para Shift+Enter a través de xtermmodifyOtherKeys. Para utilizar el protocolo de teclado Kitty explícitamente, cree ~/.wezterm.lua:

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

En macOS, WezTerm vincula Option+Enter a pantalla completa de forma predeterminada. Para usar Option+Enter para la cola de seguimiento de pi, agregue esta anulación de clave:

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 tiene una tabla config.keys, agréguele la entrada.

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

Alacritty generalmente funciona de inmediato para Shift+Enter. En macOS, Option+Enter puede llegar como Enter simple. Para usar Option+Enter para la cola de seguimiento de pi, agregue a ~/.config/alacritty/alacritty.toml:

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

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

VS Code 1.109.5 y versiones más recientes habilitan el protocolo de teclado Kitty en el terminal integrado de forma predeterminada, por lo que Shift+Enter debería funcionar de inmediato.

Las versiones de VS Code anteriores a 1.109.5 necesitan una combinación de teclas de terminal explícita para Shift+Enter.

keybindings.json ubicaciones:

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

Añadir a keybindings.json:

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

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

{
  "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 vincula Alt+Enter a pantalla completa de forma predeterminada. Eso evita que pi reciba Alt+Enter para la cola de seguimiento.
• Reasignar Alt+Enter a sendInput reenvía el acorde clave real a pi.

Si ya tiene una matriz actions, agréguele los objetos. Si el antiguo comportamiento de pantalla completa persiste, cierre completamente y vuelva a abrir Windows Terminal.

Estos terminales tienen soporte limitado para secuencias de escape. Las teclas Enter modificadas como Ctrl+Enter y Shift+Enter no se pueden distinguir de las simples Enter, lo que impide que funcionen combinaciones de teclas personalizadas como submit: ["ctrl+enter"].

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

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

El terminal incorporado tiene soporte limitado para secuencias de escape. Shift+Enter no se puede distinguir de Enter en la terminal de IntelliJ.

Si desea que el cursor de hardware esté visible, configure PI_HARDWARE_CURSOR=1 antes de ejecutar pi (deshabilitado de forma predeterminada por compatibilidad).

Considere utilizar un emulador de terminal dedicado para obtener la mejor experiencia.