읽는 시간: 6분 | 난이도: 초급자

Claude Code는 완전히 커스터마이징 가능한 키보드 단축키를 지원합니다. /keybindings 명령을 실행하면 설정 파일(~/.claude/keybindings.json)이 생성되거나 열립니다. 이 파일을 통해 워크플로우에 맞는 단축키를 자유롭게 정의할 수 있습니다.

설정 파일 구조

키바인딩 설정 파일은 bindings 배열을 포함하는 JSON 객체입니다. 각 블록은 적용할 컨텍스트와 키 입력-액션 매핑을 지정합니다.

참고: 키바인딩 파일의 변경사항은 Claude Code를 재시작하지 않아도 자동으로 감지되어 적용됩니다.

다음 예시는 채팅 컨텍스트에서 Ctrl+E를 외부 에디터 열기에 바인딩하고, Ctrl+U를 언바인딩합니다:

{
  "$schema": "https://www.schemastore.org/claude-code-keybindings.json",
  "$docs": "https://code.claude.com/docs/en/keybindings",
  "bindings": [
    {
      "context": "Chat",
      "bindings": {
        "ctrl+e": "chat:externalEditor",
        "ctrl+u": null
      }
    }
  ]
}

컨텍스트 (Contexts)

각 바인딩 블록은 단축키가 적용되는 컨텍스트를 지정합니다:

사용 가능한 액션

액션은 namespace:action 형식을 따릅니다. 예를 들어 chat:submit은 메시지를 전송하고, app:toggleTodos는 작업 목록을 표시합니다.

앱 액션 (Global 컨텍스트)

히스토리 액션

채팅 액션 (Chat 컨텍스트)

자동완성 액션 (Autocomplete 컨텍스트)

확인 액션 (Confirmation 컨텍스트)

기타 주요 액션

태스크 액션 (Task 컨텍스트):

설정 액션 (Settings 컨텍스트):

키 입력 문법

수정자 키 (Modifiers)

수정자 키는 + 구분자와 함께 사용합니다:

• ctrl 또는 control — Control 키
• alt, opt, 또는 option — Alt/Option 키
• shift — Shift 키
• meta, cmd, 또는 command — Meta/Command 키

예시:

ctrl+k          수정자 키와 단일 키
shift+tab       Shift + Tab
meta+p          Command/Meta + P
ctrl+shift+c    다중 수정자

대문자

단독 대문자는 Shift를 의미합니다. 예를 들어 K는 shift+k와 동일합니다. 이는 대소문자에 다른 의미를 부여하는 vim 스타일 바인딩에 유용합니다.

수정자와 함께 사용된 대문자(예: ctrl+K)는 Shift를 의미하지 않습니다. ctrl+K와 ctrl+k는 동일합니다.

코드 (Chords)

코드는 공백으로 구분된 키 입력 시퀀스입니다:

ctrl+k ctrl+s   Ctrl+K 입력 후 Ctrl+S 입력

특수 키

• escape 또는 esc — Escape 키
• enter 또는 return — Enter 키
• tab — Tab 키
• space — 스페이스 바
• up, down, left, right — 방향키
• backspace, delete — 삭제 키

기본 단축키 해제

액션을 null로 설정하면 기본 단축키를 해제할 수 있습니다:

{
  "bindings": [
    {
      "context": "Chat",
      "bindings": {
        "ctrl+s": null
      }
    }
  ]
}

예약된 단축키

다음 단축키는 재바인딩할 수 없습니다:

터미널 충돌

일부 단축키는 터미널 멀티플렉서와 충돌할 수 있습니다:

Vim 모드와의 상호작용

vim 모드가 활성화된 경우(/vim), 키바인딩과 vim 모드는 독립적으로 동작합니다:

• Vim 모드는 텍스트 입력 수준에서 처리됩니다 (커서 이동, 모드, 모션)
• 키바인딩은 컴포넌트 수준에서 액션을 처리합니다 (할일 토글, 전송 등)
• vim 모드에서 Escape 키는 INSERT에서 NORMAL 모드로 전환하며, chat:cancel을 트리거하지 않습니다
• 대부분의 Ctrl+키 단축키는 vim 모드를 통과하여 키바인딩 시스템에 전달됩니다

유효성 검사

Claude Code는 키바인딩을 검증하고 다음 항목에 대한 경고를 표시합니다:

• 파싱 오류 (잘못된 JSON 또는 구조)
• 잘못된 컨텍스트 이름
• 예약된 단축키 충돌
• 터미널 멀티플렉서 충돌
• 동일한 컨텍스트 내 중복 바인딩

키바인딩 경고를 확인하려면 /doctor를 실행하세요.

실용적인 예시

Vim 스타일 탐색

{
  "bindings": [
    {
      "context": "Select",
      "bindings": {
        "j": "select:next",
        "k": "select:previous"
      }
    }
  ]
}

외부 에디터 단축키 변경

{
  "bindings": [
    {
      "context": "Chat",
      "bindings": {
        "ctrl+e": "chat:externalEditor",
        "ctrl+g": null
      }
    }
  ]
}

다음 단계

• 상태 표시줄 설정 — 하단 상태바 커스터마이징
• 모델 설정 — 사용 모델 변경
• 설정 파일 가이드 — 전체 설정 옵션 참조