터미널 설정

Pi는 안정적인 수정자 키 감지를 위해 Kitty keyboard protocol를 사용합니다. 대부분의 최신 터미널은 이 프로토콜을 지원하지만 일부는 구성이 필요합니다.

즉시 사용 가능

Pi 가능한 경우 향상된 키 보고를 활성화합니다. Terminal.app이 여전히 Shift+Enter에 대한 일반 Return을 보내는 경우 pi는 로컬 macOS 수정자 대체를 사용하여 해당 Return을 Shift+Enter로 처리합니다.

이 대체 방법은 pi가 Terminal.app과 동일한 Mac에서 실행되는 경우에만 작동합니다. 원격 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 이상이면 이를 제거할 수 있습니다. 단, 여전히 Ghostty 매핑이 필요한 tmux에서 Claude Code를 사용하려는 경우는 예외입니다.

Pi는 Ctrl+J를 기본 개행 별칭으로 바인딩하므로 Shift+Enter는 추가 Pi 구성 없이 다시 매핑을 통해 tmux에서 계속 작동합니다.

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를 전체 화면으로 바인딩합니다. pi 후속 조치 대기열에 Option+Enter를 사용하려면 다음 키 재정의를 추가하세요.

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로 도착할 수 있습니다. pi 후속 대기열에 Option+Enter를 사용하려면 ~/.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 위치:

• 맥OS: ~/Library/Application Support/Code/User/keybindings.json
• 리눅스: ~/.config/Code/User/keybindings.json
• 윈도우: %APPDATA%\\Code\\User\\keybindings.json

keybindings.json에 추가:

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

pi가 사용하는 수정된 Enter 키를 전달하려면 settings.json(Ctrl+Shift+ 또는 설정 → JSON 파일 열기)에 추가하세요.

{
  "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가 후속 대기열에 대해 Alt+Enter을 수신하는 것을 방지합니다.
• Alt+Enter를 sendInput로 다시 매핑하면 실제 키 코드가 대신 pi로 전달됩니다.

actions 배열이 이미 있는 경우 해당 배열에 개체를 추가하세요. 이전 전체 화면 동작이 지속되면 Windows Terminal을 완전히 닫았다가 다시 엽니다.

이러한 터미널은 이스케이프 시퀀스 지원이 제한되어 있습니다. Ctrl+Enter 및 Shift+Enter와 같은 수정된 Enter 키는 일반 Enter와 구별할 수 없으므로 submit: ["ctrl+enter"]와 같은 사용자 정의 키 바인딩이 작동하지 않습니다.

최상의 경험을 위해서는 Kitty 키보드 프로토콜을 지원하는 터미널을 사용하십시오.

• Kitty
• Ghostty
• WezTerm
• iTerm2
• Alacritty (Kitty 프로토콜 지원을 통한 컴파일 필요)

내장 터미널은 이스케이프 시퀀스 지원이 제한되어 있습니다. IntelliJ 터미널에서는 Shift+Enter를 Enter와 구별할 수 없습니다.

하드웨어 커서를 표시하려면 pi를 실행하기 전에 PI_HARDWARE_CURSOR=1를 설정하세요(호환성을 위해 기본적으로 비활성화되어 있음).

최상의 경험을 위해서는 전용 터미널 에뮬레이터를 사용하는 것이 좋습니다.