키보드 단축키

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

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

설정 파일 구조

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

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

필드	설명
`$schema`	에디터 자동완성을 위한 JSON Schema URL (선택사항)
`$docs`	문서 URL (선택사항)
`bindings`	컨텍스트별 바인딩 블록 배열

다음 예시는 채팅 컨텍스트에서 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)

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

컨텍스트	설명
`Global`	앱 전체에 적용
`Chat`	메인 채팅 입력 영역
`Autocomplete`	자동완성 메뉴가 열린 상태
`Settings`	설정 메뉴
`Confirmation`	권한 및 확인 다이얼로그
`Tabs`	탭 네비게이션 컴포넌트
`Help`	도움말 메뉴가 표시된 상태
`Transcript`	트랜스크립트 뷰어
`HistorySearch`	히스토리 검색 모드 (Ctrl+R)
`Task`	백그라운드 작업 실행 중
`ThemePicker`	테마 선택 다이얼로그
`Attachments`	이미지/첨부파일 바 네비게이션
`Footer`	푸터 인디케이터 네비게이션
`MessageSelector`	되감기 및 요약 다이얼로그
`DiffDialog`	차이(Diff) 뷰어 네비게이션
`ModelPicker`	모델 선택기 노력 수준
`Select`	일반 선택/목록 컴포넌트
`Plugin`	플러그인 다이얼로그

사용 가능한 액션

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

앱 액션 (Global 컨텍스트)

액션	기본값	설명
`app:interrupt`	Ctrl+C	현재 작업 취소
`app:exit`	Ctrl+D	Claude Code 종료
`app:toggleTodos`	Ctrl+T	작업 목록 표시/숨기기
`app:toggleTranscript`	Ctrl+O	상세 트랜스크립트 토글

히스토리 액션

액션	기본값	설명
`history:search`	Ctrl+R	히스토리 검색 열기
`history:previous`	Up	이전 히스토리 항목
`history:next`	Down	다음 히스토리 항목

채팅 액션 (Chat 컨텍스트)

액션	기본값	설명
`chat:cancel`	Escape	현재 입력 취소
`chat:cycleMode`	Shift+Tab	권한 모드 순환
`chat:modelPicker`	Cmd+P / Meta+P	모델 선택기 열기
`chat:thinkingToggle`	Cmd+T / Meta+T	확장 사고 토글
`chat:submit`	Enter	메시지 전송
`chat:undo`	Ctrl+_	마지막 액션 되돌리기
`chat:externalEditor`	Ctrl+G	외부 에디터에서 열기
`chat:stash`	Ctrl+S	현재 프롬프트 임시 저장
`chat:imagePaste`	Ctrl+V	이미지 붙여넣기

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

액션	기본값	설명
`autocomplete:accept`	Tab	제안 수락
`autocomplete:dismiss`	Escape	메뉴 닫기
`autocomplete:previous`	Up	이전 제안
`autocomplete:next`	Down	다음 제안

확인 액션 (Confirmation 컨텍스트)

액션	기본값	설명
`confirm:yes`	Y, Enter	액션 확인
`confirm:no`	N, Escape	액션 거절
`confirm:cycleMode`	Shift+Tab	권한 모드 순환
`confirm:toggleExplanation`	Ctrl+E	권한 설명 토글

기타 주요 액션

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

액션	기본값	설명
`task:background`	Ctrl+B	현재 작업을 백그라운드로 전환

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

액션	기본값	설명
`settings:search`	/	검색 모드 진입
`settings:retry`	R	사용량 데이터 다시 로드

키 입력 문법

수정자 키 (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
      }
    }
  ]
}

예약된 단축키

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

단축키	이유
Ctrl+C	하드코딩된 인터럽트/취소
Ctrl+D	하드코딩된 종료

터미널 충돌

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

단축키	충돌
Ctrl+B	tmux 프리픽스 (두 번 눌러서 전송)
Ctrl+A	GNU screen 프리픽스
Ctrl+Z	Unix 프로세스 일시 정지 (SIGTSTP)

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
      }
    }
  ]
}

다음 단계

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