요약
- 키바인딩은 ~/.claude/keybindings.json 에 있습니다. /keybindings 로 만들고 열 수 있고, 저장하는 순간 적용됩니다. 재시작은 필요 없습니다.
- 바인딩은 컨텍스트별로 묶입니다(Chat, Autocomplete, Agents, Scroll 등). "ctrl+e" 같은 키를 chat:externalEditor 같은 액션에 연결하고, null 을 지정하면 해제됩니다.
- vim 모드: /vim 을 실행하거나 /config → Editor mode → Space → Enter. Escape 가 INSERT/NORMAL 을 전환하고, v2.1.118 부터 비주얼 모드(v/V)도 지원합니다.
- 건드릴 수 없는 키도 있습니다. Ctrl+C, Ctrl+D, Ctrl+M 은 재할당이 불가능하고, tmux 의 Ctrl+B 프리픽스는 Claude Code 에 닿기 전에 단축키를 가로챕니다.
How to Enable Vim Editor in Claude Code CLI
채널: ProgrammingKnowledge21:32
Claude Code v2.1.118 — Vim Visual Mode & Custom Themes
채널: Claude Code Updates0:41
How to use Vim in Claude Code
채널: HAMY LABS5:41
Claude Code release notes — v2.1.118 & v2.1.288
릴리스 노트: github.com/anthropics/claude-code
Keybindings — official documentation
공식 문서: code.claude.com/docs
이 페이지의 사실 관계는 공식 keybindings 문서와 v2.1.118·v2.1.288 체인지로그와 대조해 확인했습니다. 스크린샷은 위 영상들에서 가져온 프레임입니다. 설명된 동작은 Claude Code v2.1.288(2026년 10월) 기준입니다.
스크린샷은 소개된 영상들의 프레임으로, 출처를 밝히고 매 단계에 원본 타임스탬프로 돌아가는 링크를 붙였습니다.
키 변경부터 vim 모드까지, 단계별 가이드
keybindings.json 에서 키 바꾸기
- 1
Claude Code 실행하고 환경 확인
터미널에서 claude 를 실행해 세션을 시작합니다. 키바인딩 커스터마이징과 vim 모드는 CLI 기능이라 이 페이지의 모든 작업은 같은 프롬프트에서 끝납니다. v2.1.288 이상이면 agents 뷰의 최신 단축키도 쓸 수 있습니다. Ctrl+F 검색과 Alt+↑/↓ 그룹 이동입니다.
커스터마이징을 기다리는 새 Claude Code 세션.영상 0:17 지점 보기 - 2
/keybindings 로 keybindings.json 열기
프롬프트에 /keybindings 를 입력하세요. ~/.claude/keybindings.json 이 없으면 Claude Code 가 파일을 만들어 편집기로 열어 줍니다. 저장한 변경은 자동으로 감지되므로 재시작이 필요 없습니다.
슬래시 메뉴는 입력에 따라 좁혀집니다. /keybindings 도 그 항목 중 하나입니다.영상 0:34 지점 보기 - 3
컨텍스트 안에서 키를 액션에 매핑
파일에는 컨텍스트별로 묶인 bindings 배열이 들어 있습니다. Chat, Autocomplete, Agents, Task, Scroll 등이 그 대상입니다. 각 블록은 키를 액션 이름에 연결합니다. undefined }. 파일 상단에 $schema 필드를 넣으면 에디터가 모든 액션 이름을 자동 완성해 줍니다.
- 4
null 로 해제하고 chord 로 연결
키에 null 을 지정하면 기본 동작이 꺼집니다. "ctrl+s": null 은 입력 stash 를 비활성화합니다. chord 는 공백으로 구분합니다. "ctrl+x ctrl+k" 는 Ctrl+X 를 누르고 3초 안에 Ctrl+K 를 누르라는 뜻입니다. 일부 조합은 예약되어 재할당할 수 없습니다. Ctrl+C, Ctrl+D, Ctrl+M, Ctrl+[, Ctrl+I 입니다.
vim 모드 켜기
- 5
/config 로 설정 패널 열기
JSON 손편집보다 토글이 편한가요? /config 는 영상에 나온 설정 패널을 엽니다. Status·Config·Usage 탭과, 입력에 따라 목록을 좁히는 검색 상자가 있습니다.
/config 패널에는 Editor mode 를 포함한 모든 설정이 나열됩니다.영상 0:40 지점 보기 - 6
검색으로 Editor mode 찾기
검색 상자에 edit 를 입력하면 목록이 Editor mode 설정 한 줄로 좁혀집니다. 기본값은 normal. bash 나 Emacs 키바인딩에 익숙한 사람이라면 낯익은 readline 스타일 편집입니다.
Editor mode 의 기본값은 normal이고, Space 로 바꿉니다.영상 1:08 지점 보기 - 7
Space 로 vim 으로 전환
Editor mode 행이 선택된 상태에서 Space 를 누르면 값이 normal 에서 vim 으로 바뀝니다. 힌트 줄이 규칙을 정리해 줍니다. Space 로 변경, Enter 로 저장, / 로 검색, Esc 로 취소.
vim 선택은 Space 한 번이면 충분합니다.영상 1:11 지점 보기 - 8
저장하고 -- INSERT -- 확인하기
Enter 로 저장하면 Claude Code 가 "Set editor mode to vim" 을 출력하고, 상태 푸터에 vim 의 -- INSERT -- 표시가 생깁니다. 이 선택은 같은 머신에서 세션을 넘어 유지됩니다. ~/.claude.json 의 editorMode 로 저장되는데, 이 파일은 OAuth 캐시와 세션 상태도 담는 런타임 파일이라 dotfiles 로 symlink 하지 마세요.
저장 완료. 푸터에 vim 의 -- INSERT -- 표시가 나타납니다.영상 1:28 지점 보기 - 9
insert 로 입력하고 normal 으로 지휘하기
insert 모드는 그냥 평범한 타이핑입니다. Escape 를 누르면 normal 모드로 전환되고, h·j·k·l 로 커서를 움직이고, b·w 로 단어 사이를 이동하고, d 는 삭제, c 는 변경, r 은 교체입니다. /vim 을 다시 실행하면 모드 전체가 꺼집니다. vim 고유의 키는 keybindings.json 으로 재할당되지 않습니다. INSERT 중의 jj 같은 시퀀스는 vimInsertModeRemaps 로 설정하세요.
- 10
비주얼 모드로 텍스트 선택하기(v2.1.118+)
비주얼 모드가 없다고 안내하는 예전 튜토리얼이 있지만, 이제는 옛말입니다. v2.1.118 에서 비주얼 모드(v)와 visual-line 모드(V)가 추가됐습니다. 선택, 연산자, 시각적 피드백이 함께죠. v plus motion 으로 문자를, V plus motion 으로 줄 전체를 선택한 뒤 d·y·c 로 처리합니다.
v2.1.118 에서 Claude Code 의 vim 모드에 v·V 선택이 생겼습니다.영상 0:16 지점 보기
외워둘 만한 기본 단축키
- 11
가장 중요한 기본 단축키 익히기
Shift+Tab 은 권한 모드 순환, Enter 는 전송, Ctrl+J 는 줄바꿈, Ctrl+L 은 입력 지우기, Ctrl+R 은 기록 검색, Ctrl+O 는 transcript 토글, Ctrl+T 는 todo 표시, Ctrl+B 는 작업 백그라운드 전환, Ctrl+X Ctrl+K 는 agents 종료입니다. v2.1.288 이상의 agents 뷰에서는 Ctrl+F 로 세션을 이름으로 찾고 Alt+↑/↓ 로 그룹을 건너뛸 수 있고, 이 모든 키는 keybindings.json 에서 바꿀 수 있습니다.
keybindings.json vs /config vs /vim: 무엇이 무엇을 바꾸나
Claude Code 의 키 동작은 세 개의 층위가 결정합니다. 서로 경쟁하기보다 쌓이는 관계라, 바꾸려는 것에 맞는 층위를 고르면 됩니다.
- 1keybindings.json 은 개별 액션을 재할당합니다. chat:externalEditor 를 ctrl+e 로 옮기고, chat:stash 를 해제하고, ctrl+x chord 를 추가하세요. 잘게 쪼개져 있고, 이식 가능하고, 버전 관리에 넣어도 안전합니다.
- 2/config → Editor mode 는 편집 모델 전체를 normal(readline)과 vim 사이에서 바꿉니다. 토글 하나, 즉시 저장, 그 머신의 이후 모든 세션에 적용됩니다.
- 3/vim 은 Editor mode 토글과 정확히 같은 일을 합니다. 가장 빠른 길이자 HAMY LABS 워크스루에서 쓰는 명령이기도 합니다. 다시 실행하면 normal 로 돌아옵니다.
- 4터미널이 Claude Code 보다 먼저 일부 키를 가로챕니다. tmux 의 Ctrl+B 프리픽스, GNU screen 의 Ctrl+A, 프로세스를 멈추는 Ctrl+Z 가 그 대상입니다. 이 문제는 keybindings.json 이 아니라 터미널 쪽에서 해결하세요.
- 5vim 모드 안에서는 vimInsertModeRemaps 만이 jj → escape 같은 vim 동작을 재할당하는 유일한 방법입니다. keybindings.json 은 의도적으로 vim 내부 키에 손대지 않습니다.
경험칙: 성가신 단축키 하나 → keybindings.json. 편집 스타일 자체를 바꾸고 싶다 → vim 모드. 키가 아예 도착하지 않는다 → 터미널부터 확인.
키바인딩이 안 될 때? 순서대로 고치기
키바인딩 문제의 대부분은 다섯 가지 원인으로 환원됩니다. 파일을 다시 고치기 전에 목록을 위에서부터 훑어보세요.
- 1편집 후 아무 변화가 없다: 파일이 ~/.claude/keybindings.json 인지(settings.json 이 아닌지), JSON 이 파싱되는지 확인하세요. --debug 플래그로 Claude Code 를 시작하면 액션 오타, 존재하지 않는 컨텍스트 같은 바인딩 경고가 드러납니다.
- 2어떤 키는 재할당을 거부한다: Ctrl+C, Ctrl+D, Ctrl+M(항상 Enter), Ctrl+[(항상 Escape), Ctrl+I(항상 Tab)는 예약 키입니다. 텍스트 필드에서 입력한 인쇄 가능 문자는 바인딩이 아니라 입력으로 흘러갑니다.
- 3Ctrl+B 나 Ctrl+A 가 닿지 않는다: tmux 와 GNU screen 이 이 키들을 프리픽스로 소비합니다. keybindings.json 에서 단축키를 바꾸거나 멀티플렉서의 프리픽스를 변경하세요.
- 4chord 프리픽스 재사용이 실패한다: ctrl+x 로 시작하는 chord 가 여러 개인 동안에는 전부 해제해야 ctrl+x 혼자 일반 키로 동작합니다.
- 5vim 키가 바인딩을 무시한다: 설계입니다. vim 모드는 자기 키를 스스로 관리합니다. insert 시퀀스는 vimInsertModeRemaps 를 쓰고, v·V 선택이 아무 일도 하지 않으면 Claude Code 를 v2.1.118 이상으로 업데이트하세요.
기본값을 복원하려면 keybindings.json 에서 해당 줄을 삭제하세요. 「default」 값을 다시 적어 넣는 게 아니라, 삭제 자체가 원래 바인딩을 돌려줍니다.