키보드 단축키 커스터마이즈
키보드 단축키 커스터마이즈 (Customize keyboard shortcuts)
Claude Code는 키보드 단축키를 설정 파일로 커스터마이즈할 수 있습니다. /keybindings를 실행하면 ~/.claude/keybindings.json 설정 파일을 만들거나 엽니다. 키 입력(keystroke)을 액션(action)에 매핑하고, 파일 변경은 재시작 없이 자동 감지·적용됩니다.
출처: 공식문서
본문
설정 파일
bindings 배열을 가진 객체입니다. 각 블록은 컨텍스트와 키→액션 맵을 지정합니다. 필드: $schema(에디터 자동완성용 JSON Schema URL), $docs(문서 URL), bindings(컨텍스트별 바인딩 배열).
매핑 예 — Chat 컨텍스트에서 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(작업·팀·diff·아티팩트 푸터), MessageSelector(rewind·요약 메시지 선택), DiffDialog(diff 뷰어), DiffPanel(/diff 패널), ModelPicker(모델 선택기), EffortSlider(/effort 슬라이더), Select(일반 select/list), Plugin(플러그인 대화상자), Agents(claude agents 에이전트 뷰), Scroll(전체화면 스크롤·텍스트 선택). v2.1.205 이전에는 /doctor용 Doctor 컨텍스트·doctor:fix 액션이 있었습니다.
액션 (Actions)
액션은 namespace:action 형식입니다(예 chat:submit, app:toggleTodos).
App (Global): app:interrupt Ctrl+C(취소), app:exit Ctrl+D(종료, 800ms 내 두 번 눌러 확인), app:redraw(언바운드, 터미널 재그리기), app:toggleTodos Ctrl+T(할 일 목록 토글 — /tasks와 다름), app:toggleTranscript Ctrl+O(verbose 트랜스크립트 토글).
History: history:search Ctrl+R(히스토리 검색), history:previous Up, history:next Down.
Chat: chat:cancel Escape(입력 취소), chat:clearInput Ctrl+L(전체화면 재그리기, 전체화면 렌더링에선 화면도 클리어), chat:clearScreen Cmd+K(chat:clearInput과 동일), chat:killAgents Ctrl+X Ctrl+K(백그라운드 서브에이전트 전부 정지·아티팩트 자동답변 끔), chat:cycleMode Shift+Tab(권한 모드 순환; Windows VT 미지원 시 Meta+M), chat:modelPicker Meta+P(모델 선택기), chat:fastMode Meta+O(패스트 모드 토글), chat:thinkingToggle Meta+T(확장 사고 토글), chat:submit Enter(전송), chat:queueSubmit Ctrl+X Enter(대기열 전송 — v2.1.247+), chat:newline Ctrl+J(새 줄), chat:undo Ctrl+_ / Ctrl+Shift+- (실행 취소), chat:externalEditor Ctrl+G·Ctrl+X Ctrl+E(외부 에디터), chat:stash Ctrl+S(현재 프롬프트 임시 보관), chat:imagePaste Ctrl+V(WSL·Windows는 Alt+V)(클립보드 이미지 붙여넣기).
Autocomplete: autocomplete:accept Tab, autocomplete:dismiss Escape, autocomplete:previous Up, autocomplete:next Down.
Confirmation: confirm:yes Y·Enter, confirm:no N·Escape, confirm:previous Up, confirm:next Down, confirm:nextField Tab, confirm:previousField(언바운드), confirm:toggle Space, confirm:cycleMode Shift+Tab(v2.1.257 이전엔 confirm:toggleExplanation이 Ctrl+E에 바인딩돼 Bash·PowerShell 프롬프트 명령 설명을 표시).
Permission: permission:toggleDebug(언바운드 — 이전 기본값 Ctrl+D는 app:exit과 충돌해 v2.1.146에서 제거).
Transcript: transcript:toggleShowAll Ctrl+E(클래식 렌더러 전용), transcript:exit q·Ctrl+C·Escape.
HistorySearch: historySearch:next Ctrl+R, accept Escape·Tab, cancel Ctrl+C, execute Enter, cycleScope Ctrl+S(세션·프로젝트·전체 — 전체화면 렌더링 전용).
Task: task:background Ctrl+B·Ctrl+X Ctrl+B(tmux 프리픽스 충돌 회피용 코드).
ThemePicker: theme:toggleSyntaxHighlighting Ctrl+T.
Help: help:dismiss Escape. Tabs: tabs:next Tab·Right, tabs:previous Shift+Tab·Left.
Attachments: attachments:next Right, previous Left, remove Backspace·Delete, exit Down·Escape.
Footer: footer:next Right, previous Left, up Up, down Down, openSelected Enter, clearSelection Escape, dismiss Backspace·Delete(선택된 아티팩트 링크 해제 — v2.1.217+).
MessageSelector: messageSelector:up Up·K·Ctrl+P, down Down·J·Ctrl+N, top Ctrl+Up·Shift+Up·Meta+Up·Shift+K, bottom Ctrl+Down·Shift+Down·Meta+Down·Shift+J, select Enter.
DiffDialog: diff:dismiss Escape, previousSource Left, nextSource Right, previousFile Up·K, nextFile Down·J, viewDetails Enter, back(언바운드 — v2.1.203에서 Left 기본 제거). 상세 뷰에는 pager 스타일 키도 바인딩: scroll:pageUp PageUp, scroll:pageDown PageDown, scroll:fullPageUp Shift+Space·B, scroll:fullPageDown Space, scroll:top G·Home, scroll:bottom Shift+G·End.
DiffPanel (/diff가 여는 패널, v2.1.260+): app:toggleReplTab(언바운드, /diff와 동일), app:cycleDiffBase Ctrl+X B(비교 기준 순환), app:diffFileListUp Ctrl+Up·Meta+Up, app:diffFileListDown Ctrl+Down·Meta+Down, app:toggleDiffNoiseFilter(언바운드), app:toggleDiffPreSession(언바운드).
ModelPicker: modelPicker:decreaseEffort Left, increaseEffort Right, thisSessionOnly s.
EffortSlider (/effort 슬라이더): effortSlider:thisSessionOnly s(v2.1.257+). Left·Right·Enter·Escape는 재바인딩 불가.
Select: select:next Down·J·Ctrl+N, previous Up·K·Ctrl+P, pageUp PageUp, pageDown PageDown, first Home, last End, accept Enter, cancel Escape.
Plugin: plugin:toggle Space, plugin:install I, plugin:favorite F.
Settings: settings:search /, settings:retry R, select:accept Enter·Space(변경 즉시 적용), confirm:no Escape(변경 저장된 채 닫힘).
Agents (에이전트 뷰, v2.1.257+): agents:switchView Ctrl+S(세션 그룹화 전환), agents:togglePin Ctrl+T. 에이전트 뷰가 열려 있으면 같은 키의 Agents 바인딩이 Chat/Global보다 우선합니다.
Voice (/voice 음성 받아쓰기): voice:pushToTalk Space.
Scroll (전체화면 렌더링): scroll:lineUp wheelup, scroll:lineDown wheeldown, scroll:pageUp PageUp, scroll:pageDown PageDown, scroll:top Ctrl+Home, scroll:bottom Ctrl+End, scroll:halfPageUp/halfPageDown(언바운드, vi 재바인딩용), scroll:fullPageUp/fullPageDown(언바운드), selection:copy Ctrl+Shift+C/Cmd+C, selection:clear(언바운드, v2.1.234+), selection:extendLeft Shift+Left, extendRight Shift+Right, extendUp Shift+Up, extendDown Shift+Down, extendLineStart Shift+Home, extendLineEnd Shift+End.
키 입력 문법 (Keystroke syntax)
수정자: + 구분자로 결합 — ctrl/control, shift, alt/opt/option/meta(Win·Linux Alt, macOS Option), cmd/command/super/win. cmd 그룹은 Kitty 키보드 프로토콜이나 xterm modifyOtherKeys처럼 Super 수정자를 보고하는 터미널에서만 감지되므로, 어디서나 동작하려면 ctrl이나 meta를 쓰세요.
대문자: 키 이름은 대소문자를 구분하지 않아 K와 k가 같습니다. Shift+글자는 shift+k로 쓰세요.
비US 레이아웃: Ctrl 단축키는 활성 레이아웃과 무관하게 라틴 문자로 씁니다. 키릴 등 비라틴 레이아웃에서 키의 US 위치로 매치하며(Kitty 프로토콜 터미널), AZERTY 등 라틴 재배치 레이아웃에서는 키가 입력하는 글자로 매치합니다. v2.1.247 이전엔 Ghostty·Kitty·WezTerm·iTerm2에서 비라틴 레이아웃 Ctrl 단축키가 동작하지 않았습니다.
코드(chord): 공백으로 구분한 키 시퀀스(예 ctrl+k ctrl+s). 각 키는 앞 키로부터 3초 안에 눌러야 하고, 지나면 코드가 취소됩니다.
특수 키: escape/esc, enter/return, tab, space, up/down/left/right, pageup/pagedown, home/end, backspace/delete, wheelup/wheeldown.
기본 단축키 해제 (Unbind)
액션을 null로 설정해 해제합니다. 코드 바인딩도 해제할 수 있고, 프리픽스를 공유하는 코드를 전부 해제해야 그 프리픽스를 단일 키로 되찾습니다. ctrl+x 프리픽스 기본 코드: Chat에서 ctrl+x ctrl+k, ctrl+x ctrl+e, ctrl+x enter(v2.1.247+), ctrl+x ctrl+a(v2.1.260+), ctrl+x tab(v2.1.260+), Task에서 ctrl+x ctrl+b, DiffPanel에서 ctrl+x b(v2.1.260+).
예약 단축키 (Reserved)
재바인딩 불가: Ctrl+C(인터럽트), Ctrl+D(종료), Ctrl+M(항상 Enter로 받음), Ctrl+[(항상 Escape로 받음 — Kitty 프로토콜 터미널은 v2.1.242+), Ctrl+I(항상 Tab), Ctrl+H(ASCII backspace 바이트 — Windows 동작은 CLAUDE_CODE_BS_AS_CTRL_BACKSPACE 참고), Caps Lock(터미널 앱에 전달 안 됨).
터미널 충돌: Ctrl+B(tmux 프리픽스 — 두 번 눌러 전송), Ctrl+A(GNU screen 프리픽스), Ctrl+Z(SIGTSTP 일시중단).
Vim 모드 상호작용
vim 모드(/config → Editor mode)와 키바인딩은 독립적으로 동작합니다 — vim 모드는 텍스트 입력 수준(커서·모드·모션), 키바인딩은 컴포넌트 수준(토글·제출 등). Escape는 vim에서 INSERT→NORMAL 전환만 하고 chat:cancel을 트리거하지 않습니다. 대부분 Ctrl+키는 vim 모드를 통과합니다. vim 키는 키바인딩 파일로 재매핑할 수 없고, INSERT 모드 두 키 시퀀스(jj 등)는 vimInsertModeRemaps 설정으로 매핑하세요. vim NORMAL에서 ?는 도움말, /는 히스토리 검색(Ctrl+R과 동일)입니다.
검증 (Validation)
프로토콜은 키바인딩을 검증해 파싱 오류, 잘못된 컨텍스트 이름, 잘못된 액션 값, 알 수 없는 액션 이름(v2.1.246 이전엔 해당 키를 조용히 비활성화, 이후엔 기본 바인딩 유지), 예약 단축키 충돌, 같은 컨텍스트 중복 바인딩에 대해 경고합니다. --debug 플래그로 시작하면 상세를 볼 수 있습니다.