Cmd. /keybindings
키 바인딩 설정 파일(~/.claude/keybindings.json)을 열거나 생성하는 명령
핵심 요약
/keybindings는~/.claude/keybindings.json을 열거나(없으면) 생성해 단축키를 커스터마이즈하는 명령입니다.- 설정은 컨텍스트별
bindings배열이며, 액션은namespace:action형식(예:chat:submit)입니다. 기본 바인딩은null로 해제합니다. - 파일 변경은 재시작 없이 자동 적용되며, 커스터마이즈 가능한 단축키는
v2.1.18이상이 필요합니다. - 코드(chord)는 공백으로 구분한 키 시퀀스(
ctrl+k ctrl+s)이고,cmd계열은 Super를 보고하는 터미널에서만 인식됩니다. Ctrl+C·Ctrl+D·Ctrl+M·Caps Lock은 재바인딩할 수 없고,/doctor로 바인딩 충돌·오류 경고를 확인합니다.
명령어 원본 선언
/keybindings공식 설명 요약
공식 문서의 정의는 "Open or create your keybindings configuration file"(키 바인딩 설정 파일을 열거나 생성한다)입니다.
/keybindings를 실행하면 ~/.claude/keybindings.json 파일이 없으면 생성하고, 있으면 엽니다. 이 파일에서 컨텍스트별 키 바인딩을 직접 고쳐 단축키를 커스터마이즈합니다.
- 설정 파일은
bindings배열을 담은 객체이며, 각 블록은 컨텍스트(context) 와 키스트로크 → 액션 맵을 지정합니다. - 액션은
namespace:action형식입니다(예:chat:submit은 메시지 전송,app:toggleTodos는 작업 목록 토글). - 파일 변경 사항은 Claude Code를 재시작하지 않아도 자동으로 감지·적용됩니다.
별칭(alias)은 없으며, 번들 스킬이나 워크플로우가 아닌 일반 내장 명령입니다.
최소 지원 버전
v2.1.18이상 (공식 키 바인딩 문서 명시: "Customizable keyboard shortcuts require Claude Code v2.1.18 or later")- 현재 버전은
claude --version으로 확인할 수 있습니다.
사용법
/keybindings설정 파일의 기본 형식은 다음과 같습니다. 아래 예시는 Chat 컨텍스트에서 Ctrl+E를 외부 에디터 열기에 바인딩하고, Ctrl+U 기본 바인딩은 null로 해제합니다.
{
"$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
}
}
]
}주요 필드
| 필드 | 설명 |
|---|---|
$schema | (선택) 에디터 자동완성용 JSON 스키마 URL |
$docs | (선택) 문서 URL |
bindings | 컨텍스트별 바인딩 블록 배열 |
키스트로크 문법
- 모디파이어:
+로 결합 —ctrl/control,shift,alt/opt/option/meta,cmd/command/super/win.meta는 macOS의 Option, Windows·Linux의 Alt에 매핑됩니다.cmd계열은 Super 모디파이어를 보고하는 터미널(Kitty 프로토콜, xtermmodifyOtherKeys)에서만 인식됩니다. 대부분의 터미널에서는ctrl또는meta를 사용하세요.
- 대문자: 단독 대문자
K는shift+k와 동일. 단, 모디파이어가 붙은ctrl+K는ctrl+k와 같으며 Shift를 함의하지 않습니다. - 코드(chord): 공백으로 구분한 키 시퀀스 —
ctrl+k ctrl+s는Ctrl+K를 누르고 떼었다가Ctrl+S를 누름. - 특수 키:
escape/esc,enter/return,tab,space,up/down/left/right,backspace/delete.
좋은 사용 예
Chat컨텍스트에서chat:externalEditor를 원하는 키로 재바인딩해 외부 에디터를 빠르게 열기.- 기본 단축키를
null로 설정해 비활성화하기(예: 충돌하는ctrl+u해제). - Vim 모드 사용자를 위한 스크롤 vi 스타일 바인딩 구성(
scroll:halfPageUp/scroll:halfPageDown등은 기본 미바인딩 상태로 제공).
비슷한 명령어 추천
| 명령어 | 차이점 | 언제 선택 |
|---|---|---|
/keybindings | 키 바인딩 설정 파일 열기/생성 | 단축키를 직접 커스터마이즈할 때 |
/config | Editor mode(Vim 등) 등 설정 토글 | 입력 모드 전환·일반 설정 변경 목적 |
/terminal-setup | Shift+Enter 등 터미널 단축키 구성 | VS Code·Cursor·Zed 등 터미널별 입력 문제 점검 |
/doctor | 키 바인딩 경고를 포함한 진단 | 바인딩 충돌·오류 검증 시 |
활용 사례
- 팀 공통 단축키 가이드 배포(설정 파일을 공유해 동일한 키맵 적용).
- 외부 에디터·작업 토글처럼 자주 쓰는 액션을 손에 맞는 키로 옮겨 생산성 높이기.
- 터미널 멀티플렉서(tmux
Ctrl+B, GNU screenCtrl+A)와 충돌하는 키를 우회하도록 재바인딩.
주의사항
- 재바인딩 불가(예약 단축키):
Ctrl+C(인터럽트/취소),Ctrl+D(종료),Ctrl+M(터미널에서 Enter와 동일),Caps Lock은 변경할 수 없습니다. - 터미널 충돌:
Ctrl+B(tmux 프리픽스),Ctrl+A(GNU screen 프리픽스),Ctrl+Z(프로세스 일시정지)는 멀티플렉서와 충돌할 수 있습니다. - Vim 모드 상호작용:
/config→ Editor mode로 Vim 모드를 켜면, Vim 모드(텍스트 입력 레벨)와 키 바인딩(컴포넌트 레벨)이 독립적으로 동작합니다. Vim의 Escape는 INSERT→NORMAL 전환이며chat:cancel을 트리거하지 않습니다. - 검증: Claude Code는 JSON 파싱 오류, 잘못된 컨텍스트 이름, 예약 단축키 충돌, 멀티플렉서 충돌, 동일 컨텍스트 내 중복 바인딩을 경고합니다.
/doctor로 키 바인딩 경고를 확인할 수 있습니다. - 공유 환경에서는
bindings항목을null로 두거나 파일을 제거해 기본값으로 복구하는 경로를 문서화해 두세요.
출처
- Commands(공식 명령어 레퍼런스): https://code.claude.com/docs/en/commands
- Customize keyboard shortcuts(키 바인딩 전용 문서): https://code.claude.com/docs/en/keybindings