Configuração do terminal

Pi usa Kitty keyboard protocol para detecção confiável de tecla modificadora. A maioria dos terminais modernos suporta este protocolo, mas alguns requerem configuração.

Trabalhe fora da caixa.

Pi permite relatórios de chaves aprimorados quando disponíveis. Se Terminal.app ainda enviar Return simples para Shift+Enter, pi usará um modificador local do macOS para tratar esse Return como Shift+Enter.

Este substituto só funciona quando pi é executado no mesmo Mac que Terminal.app. Ele não consegue detectar o teclado local no SSH remoto.

Adicione à configuração do Ghostty (~/Library/Application Support/com.mitchellh.ghostty/config no macOS, ~/.config/ghostty/config no Linux):

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

Versões mais antigas do Claude Code podem ter adicionado este mapeamento Ghostty:

keybind = shift+enter=text:\n

Esse mapeamento envia um byte de avanço de linha bruto. Dentro de pi, isso é indistinguível de Ctrl+J, então tmux e pi não veem mais um evento chave shift+enter real.

Se o Claude Code 2.x ou mais recente for o único motivo pelo qual você adicionou esse mapeamento, você poderá removê-lo, a menos que queira usar o Claude Code em tmux, onde ainda requer o mapeamento do Ghostty.

Pi vincula Ctrl+J como um alias de nova linha padrão, então Shift+Enter continua trabalhando em tmux por meio desse remapeamento sem configuração extra de pi.

WezTerm geralmente funciona imediatamente para Shift+Enter via xterm modificarOtherKeys. Para usar o protocolo de teclado Kitty explicitamente, crie ~/.wezterm.lua:

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

No macOS, o WezTerm vincula Option+Enter à tela cheia por padrão. Para usar Option+Enter para enfileiramento de acompanhamento pi, adicione esta substituição de chave:

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

Se você já possui uma tabela config.keys, adicione a entrada a ela.

No WSL, o WezTerm pode exigir um cursor de hardware visível para o posicionamento da janela candidata ao IME. Se os candidatos CJK IME não seguirem o cursor de texto, defina PI_HARDWARE_CURSOR=1 antes de executar pi ou defina showHardwareCursor para true nas configurações.

Alacritty geralmente funciona imediatamente por Shift+Enter. No macOS, Option+Enter pode chegar como Enter simples. Para usar Option+Enter para fila de acompanhamento pi, adicione a ~/.config/alacritty/alacritty.toml:

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

Reinicie o Alacritty após alterar a configuração.

O VS Code 1.109.5 e mais recente habilitam o protocolo de teclado Kitty no terminal integrado por padrão, então Shift+Enter deve funcionar imediatamente.

Versões do VS Code anteriores a 1.109.5 precisam de um atalho de teclado explícito para Shift+Enter.

keybindings.json locais:

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

Adicione a keybindings.json:

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

Adicione a settings.json (Ctrl+Shift+ ou Configurações → Abrir arquivo JSON) para encaminhar as 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 insere uma nova linha.
• O Terminal do Windows vincula Alt+Enter à tela inteira por padrão. Isso evita que pi receba Alt+Enter para enfileiramento de acompanhamento.
• Remapear Alt+Enter para sendInput encaminha o acorde real para pi.

Se você já possui um array actions, adicione os objetos a ele. Se o antigo comportamento de tela cheia persistir, feche totalmente e reabra o Terminal do Windows.

Esses terminais têm suporte limitado à sequência de escape. As teclas Enter modificadas como Ctrl+Enter e Shift+Enter não podem ser distinguidas do Enter simples, impedindo que atalhos de teclado personalizados como submit: ["ctrl+enter"] funcionem.

Para obter a melhor experiência, use um terminal que suporte o protocolo de teclado Kitty:

• Kitty
• Ghostty
• WezTerm
• iTerm2
• Alacritty (requer compilação com suporte ao protocolo Kitty)

O terminal integrado possui suporte limitado à sequência de escape. Shift+Enter não pode ser diferenciado de Enter no terminal do IntelliJ.

Se você quiser que o cursor do hardware fique visível, defina PI_HARDWARE_CURSOR=1 antes de executar o pi (desativado por padrão para compatibilidade).

Considere usar um emulador de terminal dedicado para obter a melhor experiência.