Claude Code를 위한 터미널 구성

Shift+Enter를 개행으로 수정하고, Claude가 완료되면 터미널 벨을 받으며, tmux를 구성하고, 색상 테마를 일치시키고, Claude Code CLI에서 Vim 모드를 활성화합니다.

Claude Code는 구성 없이 모든 터미널에서 작동합니다. 이 페이지는 특정 항목이 예상대로 작동하지 않을 때를 위한 것입니다. 아래에서 증상을 찾아보십시오. 이미 모든 것이 올바르게 느껴진다면 이 페이지가 필요하지 않습니다.

• Shift+Enter가 개행을 삽입하는 대신 제출합니다
• macOS에서 Option 키 단축키가 작동하지 않습니다
• Claude가 완료되면 소리나 알림이 없습니다
• tmux 내에서 Claude Code를 실행합니다
• Windows에서 백스페이스가 전체 단어를 삭제합니다
• 디스플레이가 깜박이거나 스크롤백이 점프합니다
• 프롬프트에서 Vim 키를 원합니다

이 페이지는 터미널이 Claude Code에 올바른 신호를 보내도록 하는 것에 관한 것입니다. Claude Code 자체가 응답하는 키를 변경하려면 대신 키 바인딩을 참조하십시오.

여러 줄 프롬프트 입력

Enter를 누르면 메시지가 전송됩니다. 전송하지 않고 줄바꿈을 추가하려면 Ctrl+J를 누르거나 \를 입력한 후 Enter를 누르십시오. 두 방법 모두 모든 터미널에서 설정 없이 작동합니다.

대부분의 터미널에서는 Shift+Enter를 누를 수도 있지만, 터미널 에뮬레이터에 따라 지원이 다릅니다:

VS Code, Cursor, Devin Desktop, Alacritty 0.16 이전, 및 Zed의 경우, /terminal-setup은 Shift+Enter 키 바인딩을 터미널의 구성 파일에 작성합니다. 첫 번째 실행 시 Installed VSCode terminal Shift+Enter key binding과 같은 확인 메시지가 표시됩니다. 기존 바인딩은 그대로 유지되며, VSCode terminal Shift+Enter key binding already configured와 같은 메시지가 표시되면 변경이 없었던 것입니다. tmux 또는 screen 내부가 아닌 호스트 터미널에서 직접 /terminal-setup을 실행하십시오. 호스트 터미널의 구성에 작성해야 하기 때문입니다.

VS Code, Cursor 및 Devin Desktop에서 /terminal-setup은 또한 두 가지 편집기 설정을 업데이트합니다: 통합 터미널의 텍스트 손상을 방지하기 위해 terminal.integrated.gpuAcceleration을 "off"로 설정하고, 전체 화면 모드에서 더 부드러운 스크롤링을 위해 terminal.integrated.mouseWheelScrollSensitivity를 설정합니다. GPU 가속 변경을 취소하려면 "auto"로 다시 설정하고 편집기 창을 다시 로드하십시오.

Zed에서 /terminal-setup은 keymap.json을 제자리에서 업데이트합니다:

• 키맵에 이미 바인딩이 있고 그 중 어느 것도 Terminal shift-enter가 아닌 경우, Claude Code는 먼저 keymap.json.1a2b3c4d.bak과 같은 같은 디렉토리의 복사본으로 백업한 다음 Shift+Enter 바인딩을 키맵에 병합하여 다른 키 바인딩과 주석을 유지합니다.
• Claude Code가 키맵을 읽거나 구문 분석할 수 없거나, 백업할 수 없거나, 병합된 결과를 확인할 수 없는 경우, 파일을 변경하지 않은 상태로 두고 직접 추가할 키 바인딩 블록을 인쇄합니다.

tmux 내부에서 실행 중인 경우, 외부 터미널이 지원하더라도 Shift+Enter는 아래의 tmux 구성이 필요합니다.

줄바꿈을 다른 키에 바인딩하거나 Enter가 줄바꿈을 삽입하고 Shift+Enter가 전송하도록 동작을 바꾸려면, 키 바인딩 파일에서 chat:newline 및 chat:submit 작업을 매핑하십시오.

macOS에서 Option 키 단축키 활성화

Claude Code의 일부 단축키는 Option 키를 사용합니다. 예를 들어 Option+Enter는 새 줄을 입력하고 Option+P는 모델을 전환합니다. macOS에서는 대부분의 터미널이 기본적으로 Option을 수정자로 전송하지 않으므로 이를 활성화할 때까지 이러한 단축키는 작동하지 않습니다. 터미널 설정은 일반적으로 "Use Option as Meta Key"로 표시됩니다. Meta는 현재 Option 또는 Alt로 표시된 키의 역사적 Unix 이름입니다.

Ghostty, Kitty 및 기타 터미널의 경우 터미널의 구성 파일에서 Option-as-Alt 또는 Option-as-Meta 설정을 찾습니다.

터미널 벨 또는 알림 받기

Claude가 작업을 완료하거나 권한 프롬프트에서 일시 중지되었을 때, 사용자가 터미널에서 자리를 비운 것으로 보이면 알림 이벤트가 발생합니다. 각 알림 유형이 발생하는 정확한 시점은 알림 유형별 발생 시점을 참조하세요. 이를 터미널 벨 또는 데스크톱 알림으로 표시하면 긴 작업이 실행되는 동안 다른 작업으로 전환할 수 있습니다.

기본적으로 Claude Code는 Ghostty, Kitty, iTerm2에서만 데스크톱 알림을 전송합니다. 다른 터미널에서는 preferredNotifChannel을 "terminal_bell"로 설정하여 터미널 벨을 울리거나, 사용자 정의 소리나 명령을 위해 Notification 훅을 구성하세요. 다음 설정 항목은 터미널 벨을 켭니다:

{
  "preferredNotifChannel": "terminal_bell"
}

데스크톱 알림은 SSH를 통해 로컬 머신에 도달하므로 원격 세션도 사용자에게 알릴 수 있습니다. Ghostty와 Kitty는 추가 설정 없이 OS 알림 센터로 전달합니다. iTerm2는 전달을 활성화해야 합니다:

알림이 여전히 나타나지 않으면 터미널 애플리케이션이 OS 설정에서 알림 권한을 가지고 있는지 확인하고, tmux 내에서 실행 중인 경우 passthrough를 활성화하세요.

Notification 훅으로 소리 재생하기

모든 터미널에서 Notification 훅을 구성하여 Claude가 사용자의 주의가 필요할 때 소리를 재생하거나 사용자 정의 명령을 실행할 수 있습니다. 훅은 기본 제공 알림과 함께 실행되며 이를 대체하지 않으므로, Warp 또는 VS Code 통합 터미널과 같이 데스크톱 알림을 받지 않는 터미널은 훅을 사용하거나 preferredNotifChannel을 "terminal_bell"로 설정할 수 있습니다.

아래 예제는 macOS에서 시스템 소리를 재생합니다. 연결된 가이드에는 macOS, Linux, Windows용 데스크톱 알림 명령이 있습니다.

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

tmux 구성

Claude Code가 tmux 내에서 실행될 때, 기본적으로 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에서 Claude Code는 ^H로 도착하는 Backspace를 Ctrl+Backspace로 읽으며, 이는 이전 단어를 삭제합니다. 단, TERM_PROGRAM이 mintty이거나 TERM이 cygwin인 경우는 예외입니다. macOS와 Linux에서 Claude Code는 이를 일반 Backspace로 읽습니다.

Backspace를 누를 때마다 전체 단어가 삭제되면, 터미널이 일반 Backspace에 대해 ^H를 전송하는 것입니다. CLAUDE_CODE_BS_AS_CTRL_BACKSPACE=0을 설정하세요. 그러면 Backspace와 Ctrl+H가 각각 한 문자씩 삭제합니다. macOS 또는 Linux에서 터미널이 Ctrl+Backspace에 대해 ^H를 전송하기 때문에 Ctrl+Backspace가 한 문자만 삭제하는 경우, 대신 변수를 1로 설정하세요.

색상 테마 일치시키기

/theme 명령을 사용하거나 /config의 테마 선택기를 사용하여 터미널과 일치하는 Claude Code 테마를 선택합니다. 자동 옵션을 선택하면 터미널의 밝은 배경 또는 어두운 배경을 감지하므로 테마가 터미널이 변경될 때마다 OS 모양 변경을 따릅니다. Claude Code는 터미널 애플리케이션에서 설정하는 터미널 자체의 색상 구성표를 제어하지 않습니다.

인터페이스 하단에 표시되는 내용을 사용자 정의하려면 현재 모델, 작업 디렉토리, git 분기 또는 기타 컨텍스트를 표시하는 사용자 정의 상태 줄을 구성합니다.

사용자 정의 테마 만들기

기본 제공 사전 설정 외에도 /theme은 정의한 사용자 정의 테마와 설치된 플러그인에서 제공한 테마를 나열합니다. 목록 끝에서 **새 사용자 정의 테마…**를 선택하여 대화형으로 만듭니다. 테마 이름을 지정한 다음 개별 색상 토큰을 선택하여 재정의합니다. 사용자 정의 테마가 강조 표시된 상태에서 Ctrl+E를 눌러 편집합니다.

각 사용자 정의 테마는 ~/.claude/themes/의 JSON 파일입니다. .json 확장자를 제외한 파일 이름이 테마의 슬러그이며, 테마를 선택하면 custom:<slug>이 테마 기본 설정으로 저장됩니다. 파일에는 세 가지 선택적 필드가 있습니다.

색상 값은 #rrggbb, #rgb, rgb(r,g,b), ansi256(n), 또는 ansi:<name>을 허용합니다. 여기서 <name>은 red 또는 cyanBright와 같은 16개의 표준 ANSI 색상 이름 중 하나입니다. 알 수 없는 토큰과 잘못된 색상 값은 무시되므로 오타가 렌더링을 손상시킬 수 없습니다.

다음 예제는 어두운 사전 설정을 유지하지만 프롬프트 악센트, 오류 텍스트 및 성공 텍스트를 다시 칠하는 테마를 정의합니다.

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

Claude Code는 ~/.claude/themes/를 감시하고 파일이 추가되거나 변경될 때 다시 로드하므로 편집기에서 만든 편집 내용이 다시 시작하지 않고 실행 중인 세션에 적용됩니다. Claude Code가 시작될 때 ~/.claude/themes/ 폴더 자체가 없었다면 첫 번째 테마 파일을 만든 후 한 번 다시 시작합니다. 그 후에는 다시 시작하지 않고 변경 사항이 적용됩니다.

아래 참조는 overrides에서 설정할 수 있는 토큰을 다룹니다. /theme의 대화형 편집기는 라이브 미리 보기와 함께 동일한 토큰을 표시하며, 여기서 생략된 온보딩 화면 색상과 같은 몇 가지 단일 목적 악센트도 표시합니다.

{
"name": "Midnight",
"base": "dark",
"overrides": {
"claude": "#a78bfa",
"planMode": "#38bdf8",
"diffAdded": "#14532d",
"diffRemoved": "#7f1d1d",
"userMessageBackground": "#1e1b4b"
}
}

전체 화면 렌더링으로 전환

화면 읽기 모드에서는 이 섹션이 적용되지 않습니다. Claude Code는 연결된 백그라운드 세션을 제외하고는 항상 일반 스크롤 텍스트로 렌더링되며, 다른 세션에서 /tui fullscreen을 실행하면 Claude Code는 전환하는 대신 설명을 출력합니다.

Claude가 작업 중일 때 디스플레이가 깜박이거나 스크롤 위치가 점프하면 전체 화면 렌더링 모드로 전환하세요. 이 모드에서는 터미널의 기본 스크롤백이 아닌 마우스나 PageUp으로 Claude Code 내에서 스크롤합니다. 검색 및 복사 방법은 전체 화면 페이지를 참조하세요.

깜박임이 유일한 문제이고 터미널이 동기화된 출력을 지원하지만 Emacs eat과 같이 자동 감지되지 않는 경우, CLAUDE_CODE_FORCE_SYNC_OUTPUT=1을 설정하여 렌더러를 변경하지 않고 깜박임을 중지할 수 있습니다.

/tui fullscreen을 실행하여 전환하고 기본 설정을 저장하세요. 대화가 그대로 다시 시작되며 전체 화면 시작이 실패하지 않는 한 향후 세션은 전체 화면에서 시작됩니다. Claude Code를 시작하기 전에 CLAUDE_CODE_NO_FLICKER 환경 변수를 설정할 수도 있습니다.

CLAUDE_CODE_NO_FLICKER=1 claude

$env:CLAUDE_CODE_NO_FLICKER = "1"; claude

{
"env": {
"CLAUDE_CODE_NO_FLICKER": "1"
}
}

대용량 콘텐츠 붙여넣기

프롬프트에 800자 이상 또는 3줄 이상의 텍스트를 붙여넣으면 Claude Code는 입력을 [Pasted text #1 +120 lines]과 같은 플레이스홀더로 축약하여 입력 상자를 사용 가능한 상태로 유지하고, 제출할 때 전체 콘텐츠를 여전히 전송합니다. 전체 파일이나 긴 로그와 같은 매우 큰 입력의 경우, 콘텐츠를 파일에 작성하고 붙여넣기 대신 Claude에 파일을 읽도록 요청합니다. 대화 기록을 읽기 쉽게 유지하고 Claude가 나중 차례에서 경로로 파일을 참조할 수 있습니다. VS Code 통합 터미널은 매우 큰 붙여넣기에서 Claude Code에 도달하기 전에 문자를 삭제할 수 있으므로, 거기서는 파일을 사용합니다.

붙여넣기에 보이지 않는 유니코드 문자가 포함되어 있으면 Claude Code는 Enter를 누를 때 이를 제거하고 정리된 프롬프트를 입력 상자에 다시 넣어서 다른 Enter로 전송할 수 있도록 합니다.

Claude가 붙여넣은 텍스트를 처리하는 방식

제출하면 Claude는 각 [Pasted text #N] 플레이스홀더 뒤의 콘텐츠를 입력한 것이 아니라 다른 곳에서 붙여넣은 텍스트로 표시된 것을 봅니다. Claude는 붙여넣기가 작성하지 않은 지시사항을 포함할 수 있으며, 입력한 메시지가 요청하는 경우에만 그 안의 지시사항을 따르도록 지시받습니다. 기능 플래그를 가져오지 않는 세션에서는 붙여넣기가 표시되지 않습니다.

축약된 붙여넣기 삭제 및 복원

Ctrl+W 또는 Ctrl+K와 같은 단어 또는 줄 단축키로 삭제하거나, df]와 같은 f/t 모션을 통한 vim 삭제로 삭제하고, 삭제된 범위가 [Pasted text #N] 플레이스홀더 내부에 도달하면 Claude Code는 플레이스홀더 전체를 제거합니다. Ctrl+Y를 단어 또는 줄 단축키 후에 사용하거나, vim 삭제 후 p NORMAL 모드를 사용하여 삭제를 다시 붙여넣을 수 있습니다.

붙여넣은 텍스트가 있는 프롬프트 회수

Claude Code는 축약된 각 [Pasted text #N] 플레이스홀더 뒤의 콘텐츠를 ~/.claude/paste-cache/ 아래에 유지하므로, 명령 기록에서 프롬프트를 회수하고 다시 제출하면 전체 붙여넣은 콘텐츠가 다시 전송되며, 나중 세션에서도 포함됩니다. cleanupPeriodDays보다 오래된 캐시 파일은 보존 스윕 규칙에 따라 삭제되므로, 회수된 프롬프트는 더 이상 존재하지 않는 붙여넣은 텍스트를 참조할 수 있습니다. 이러한 프롬프트를 제출하면 Claude Code는 절대 리터럴 [Pasted text #N] 문자열을 전송하지 않으며, 누락된 붙여넣기의 이름을 지정하는 알림을 표시합니다:

• 남은 텍스트가 있는 일반 프롬프트에서 Claude Code는 플레이스홀더를 제거하고 남은 텍스트를 전송합니다.
• 셸 모드 명령 또는 / 명령에서, 제거가 실행되는 내용을 변경할 수 있으며, 제거가 비어 있는 모든 프롬프트에서 Claude Code는 제출을 취소하고 원본 텍스트를 입력에 유지하며, 플레이스홀더는 여전히 포함됩니다. 플레이스홀더를 삭제하거나 명령을 편집한 후 다시 제출합니다.

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

Claude Code는 프롬프트 입력을 위한 Vim 스타일 편집 모드를 포함합니다. /config → Editor mode를 통해 활성화하거나, ~/.claude/settings.json에서 editorMode를 "vim"으로 설정하여 활성화할 수 있습니다. Editor mode를 normal로 다시 설정하여 비활성화합니다.

Vim 모드는 hjkl 네비게이션, v/V 선택, 텍스트 객체와 함께 d/c/y 같은 NORMAL 모드 및 VISUAL 모드 모션과 연산자의 부분 집합을 지원합니다. 전체 키 테이블은 Vim 편집기 모드 참조를 참조하십시오.

Vim 모션은 키바인딩 파일을 통해 재매핑할 수 없습니다. jj를 Escape로 매핑하는 것과 같은 두 개의 키 INSERT 모드 시퀀스를 매핑하려면, 사용자 설정에서 vimInsertModeRemaps를 설정하십시오.

INSERT 모드에서 Enter를 누르면 표준 Vim과 달리 프롬프트가 여전히 제출됩니다. 대신 NORMAL 모드에서 o 또는 O를 사용하거나 Ctrl+J를 사용하여 새 줄을 삽입하십시오.

관련 리소스

• 대화형 모드: 전체 키보드 단축키 참조 및 Vim 키 테이블
• 키 바인딩: Enter 및 Shift+Enter를 포함한 모든 Claude Code 단축키 다시 매핑
• 전체 화면 렌더링: 전체 화면 모드에서 스크롤, 검색 및 복사에 대한 세부 정보
• 훅 가이드: Linux 및 Windows용 더 많은 알림 훅 예제
• 문제 해결: 터미널 구성 외부의 문제에 대한 수정 사항