Claude Code 터미널 설정하기(Configure your terminal for Claude Code)

Claude Code 터미널 설정하기(Configure your terminal for Claude Code)

Claude Code는 구성 없이도 어떤 터미널에서든 동작해요. 이 페이지는 뭔가 예상대로 동작하지 않을 때 쓰는 문서예요. 모든 게 이미 잘 동작한다면 이 페이지는 필요 없어요. 증상이 아래 목록에 해당하면 해당 섹션으로 가서 해결하면 돼요.

출처: 공식문서

본문

이 페이지는 터미널이 Claude Code에 올바른 신호를 보내도록 하는 내용을 다뤄요. Claude Code 자체가 응답하는 키를 바꾸는 건 keybindings 문서를 보세요.

여러 줄 프롬프트 입력

Enter는 메시지를 제출해요. 줄바꿈만 하고 제출하지 않으려면 Ctrl+J를 누르거나 \를 입력한 다음 Enter를 눌러요. 둘 다 어떤 터미널에서도 설정 없이 동작해요.

대부분 터미널에서 Shift+Enter도 되지만 지원 여부는 에뮬레이터마다 달라요.

터미널 Shift+Enter로 줄바꿈
Ghostty, Kitty, iTerm2, WezTerm, Warp, Apple Terminal, Windows Terminal 설정 없이 동작
kitty 키보드 프로토콜을 지원하는 다른 터미널(foot, Alacritty 0.16+) 설정 없이 동작(Claude Code v2.1.269+)
VS Code, Cursor, Devin Desktop, Alacritty 0.16 이전, Zed /terminal-setup 한 번 실행
gnome-terminal, JetBrains IDE(PyCharm, Android Studio) 불가능; Ctrl+J 또는 \ + Enter 사용

VS Code·Cursor·Devin Desktop·Alacritty(0.16 이전)·Zed의 경우 /terminal-setup이 터미널 설정 파일에 Shift+Enter 키바인딩을 써 넣어요. 이 명령은 tmux/screen 안이 아니라 호스트 터미널에서 직접 실행해야 해요(호스트 터미널 설정에 써야 하니까). VS Code·Cursor·Devin Desktop에선 /terminal-setup이 terminal.integrated.gpuAcceleration을 "off"로 바꿔 글자 깨짐을 막고, terminal.integrated.mouseWheelScrollSensitivity도 설정해요. Zed에선 keymap.json을 백업(keymap.json.1a2b3c4d.bak)한 뒤 Shift+Enter 바인딩을 병합해요.

tmux 안에서 실행 중이면 바깥 터미널이 지원해도 Shift+Enter는 아래 tmux 설정이 필요해요. 새 줄에 다른 키를 바인딩하거나 Enter/Shift+Enter 동작을 바꾸려면 keybindings 파일에서 chat:newline과 chat:submit 액션을 매핑하세요.

macOS Option 키 단축키 활성화

일부 단축키(Option+Enter 새 줄, Option+P 모델 전환)는 Option 키를 써요. macOS에서는 대부분 터미널이 기본으로 Option을 수정자로 보내지 않아서 활성화 전까지 동작하지 않아요. 이 설정은 보통 "Use Option as Meta Key"로 표시돼요.

  • Apple Terminal: Settings → Profiles → Keyboard에서 "Use Option as Meta Key" 체크. 첫 실행 터미널 설정 프롬프트를 수락했다면 이미 됐어요.
  • iTerm2: Settings → Profiles → Keys → General에서 Left/Right Option key를 "Esc+"로 설정. /terminal-setup은 iTerm2에서 "/copy" 명령용 클립보드 접근도 활성화해요.
  • VS Code: 설정에 "terminal.integrated.macOptionIsMeta": true 추가.
  • Ghostty, Kitty 등: 터미널 설정 파일에서 Option-as-Alt/Option-as-Meta 설정을 찾으세요.

터미널 벨 또는 알림

Claude가 작업을 끝내거나 권한 프롬프트에서 멈추고, 사용자가 터미널에서 떨어져 있으면 알림 이벤트를 발생시켜요. 기본적으로 Claude Code는 Ghostty·Kitty·iTerm2에서만 데스크톱 알림을 보내요. 다른 터미널에서는 preferredNotifChannel을 "terminal_bell"로 설정해 터미널 벨을 울리게 하거나, Notification 훅으로 커스텀 소리·명령을 구성할 수 있어요.

{
  "preferredNotifChannel": "terminal_bell"
}

데스크톱 알림은 SSH를 통해 로컬 머신에 도달하므로 원격 세션에서도 알려줘요. iTerm2는 알림 포워딩을 켜야 해요(Settings → Profiles → Terminal → "Notification Center Alerts", "Send escape sequence-generated alerts").

어떤 터미널에서든 Notification 훅으로 소리를 재생하거나 커스텀 명령을 실행할 수 있어요. 훅은 내장 알림을 대체하지 않고 함께 돌아요.

{
  "hooks": {
    "Notification": [
      {
        "hooks": [{ "type": "command", "command": "afplay /System/Library/Sounds/Glass.aiff" }]
      }
    ]
  }
}

tmux 설정

tmux 안에서 Claude Code를 실행하면 기본적으로 두 가지가 깨져요: Shift+Enter가 줄바꿈 대신 제출을 하고, 데스크톱 알림과 진행 바가 바깥 터미널에 도달하지 못해요. ~/.tmux.conf에 다음을 추가하고 tmux source-file ~/.tmux.conf로 적용하세요.

set -g allow-passthrough on
set -s extended-keys on
set -as terminal-features 'xterm*:extkeys'

allow-passthrough는 알림과 진행 업데이트가 tmux에 삼켜지지 않고 바깥 터미널에 도달하게 해요. extended-keys는 tmux가 Shift+Enter와 Enter를 구분하게 해서 새 줄 단축키가 동작하게 해요.

Windows에서 Backspace가 단어 전체를 지우는 경우

Windows에서 ^H로 도착한 Backspace를 Ctrl+Backspace로 읽어 앞 단어 전체를 지워요(단, TERM_PROGRAM이 mintty이거나 TERM이 cygwin이면 제외). macOS/Linux에서는 일반 Backspace로 읽어요. Backspace를 누를 때마다 단어가 지워지면 터미널이 일반 Backspace를 ^H로 보내는 거예요. CLAUDE_CODE_BS_AS_CTRL_BACKSPACE=0으로 설정하세요. 반대로 macOS/Linux에서 Ctrl+Backspace가 한 글자만 지우면 1로 설정하세요.

색상 테마 맞추기

/theme 명령 또는 /config의 테마 선택기로 터미널과 맞는 Claude Code 테마를 고를 수 있어요. auto 옵션은 터미널의 밝은/어두운 배경을 감지해서 OS 모양 변화를 따라가요. Claude Code는 터미널 앱이 정한 터미널 자체 색 구성표는 제어하지 않아요.

커스텀 테마 만들기: /theme에서 **New custom theme…**을 선택해 대화형으로 만들 수 있어요(이름 지정 후 개별 색상 토큰 오버라이드). 커스텀 테마는 ~/.claude/themes/의 JSON 파일이고, 파일명(확장자 제외)이 테마의 slug예요. 필드는 세 개예요.

필드 타입 설명
name string /theme에 표시될 라벨. 기본은 파일명 slug
base string 시작 프리셋: dark, light, dark-daltonized, light-daltonized, dark-ansi, light-ansi. 기본 dark
overrides object 색상 토큰 이름→색상 값 매핑. 나열 안 된 토큰은 base 프리셋으로 폴백

색상 값은 #rrggbb, #rgb, rgb(r,g,b), ansi256(n), ansi:<name>(표준 ANSI 16색 이름)을 받아요. 예시:

{
  "name": "Dracula",
  "base": "dark",
  "overrides": {
    "claude": "#bd93f9",
    "error": "#ff5555",
    "success": "#50fa7b"
  }
}

Claude Code는 ~/.claude/themes/를 감시해서 파일이 추가·변경되면 재시작 없이 적용해요(폴더가 시작 시점에 없었다면 첫 테마 파일 생성 후 한 번 재시작). 주요 토큰: 텍스트·액센트(claude, text, inverseText, inactive, subtle, suggestion, permission, remember), 상태(success, error, warning, merged), 입력·모드(promptBorder, planMode, autoAccept, bashBorder, ide, fastMode), diff(diffAdded, diffRemoved 등), 풀스크린(userMessageBackground, userMessageBackgroundHover, bashMessageBackgroundColor, memoryBackgroundColor, selectionBg). 각 토큰엔 셔immer 짝(claudeShimmer 등)이 있고, 서브에이전트 색상은 <color>_FOR_SUBAGENTS_ONLY 패턴(red/blue/green/yellow/purple/orange/pink/cyan)이에요.

풀스크린 렌더링 전환

디스플레이가 깜빡이거나 스크롤 위치가 튄다면 풀스크린 렌더링 모드로 전환하세요. 이 모드에선 터미널 네이티브 스크롤백 대신 Claude Code 안에서 마우스/PageUp으로 스크롤해요. /tui fullscreen으로 전환·저장할 수 있고, 시작 전에 CLAUDE_CODE_NO_FLICKER=1 환경변수(claude 앞에 붙이거나 설정 파일 env 블록에)로도 가능해요. 동기화 출력을 지원하지만 자동 감지되지 않는 터미널(Emacs eat 등)은 CLAUDE_CODE_FORCE_SYNC_OUTPUT=1로 깜빡임을 멈출 수 있어요.

CLAUDE_CODE_NO_FLICKER=1 claude

$env:CLAUDE_CODE_NO_FLICKER = "1"; claude

큰 콘텐츠 붙여넣기

프롬프트에 800자 초과 또는 3줄 초과를 붙여넣으면 Claude Code는 [Pasted text #1 +120 lines] 같은 플레이스홀더로 접어서 입력 상자를 쓰기 좋게 유지해요(12행 미만 창에선 3줄/10행 이하에서도 접힘). 제출 시엔 전체 내용을 보내요. 접힌 콘텐츠는 ~/.claude/paste-cache/에 보관되며, cleanupPeriodDays보다 오래된 캐시는 삭제돼요 — 회수한 프롬프트가 더 이상 없는 붙여넣기를 참조하면 Claude Code는 리터럴 [Pasted text #N] 문자열을 절대 보내지 않고 누락 노티스를 보여줘요. VS Code 통합 터미널은 매우 큰 붙여넣기에서 문자를 떨어뜨릴 수 있으니, 전체 파일·긴 로그 같은 초대형 입력은 붙여넣기 대신 파일에 써서 Claude에게 읽게 하는 걸 권장해요.

Vim 키바인딩으로 프롬프트 편집

Claude Code는 프롬프트 입력용 Vim 스타일 편집 모드를 포함해요. /config → Editor mode 또는 ~/.claude/settings.json에서 editorMode를 "vim"으로 설정해서 켜요. normal로 되돌리면 꺼져요. NORMAL/VISUAL 모드의 일부 모션·연산자(hjkl, v/V 선택, d/c/y + 텍스트 객체)를 지원해요. Vim 모션은 keybindings 파일로는 리매핑할 수 없고, jj→Escape 같은 INSERT 모드 2키 시퀀스는 vimInsertModeRemaps로 매핑해요. 표준 Vim과 달리 INSERT 모드에서 Enter는 그래도 제출이에요. 줄바꿈은 NORMAL 모드의 o/O 또는 Ctrl+J를 쓰세요.

더 알아보기