Claude Code Keybindings: remapeie teclas, modo Vim e atalhos
Todas as formas de mudar o comportamento das teclas no Claude Code: editar o keybindings.json, ativar o modo vim com /vim ou /config e aprender os atalhos de teclado padrão que realmente importam.
Resumão
- Os keybindings moram em ~/.claude/keybindings.json — rode /keybindings para criar e abrir o arquivo. As mudanças valem ao salvar, sem reiniciar.
- As associações ficam agrupadas por contexto (Chat, Autocomplete, Agents, Scroll…) e mapeiam uma tecla como "ctrl+e" a uma ação como chat:externalEditor. Atribua null a uma tecla para desvinculá-la.
- Modo vim: rode /vim, ou /config → Editor mode → Espaço → Enter. O Escape alterna INSERT/NORMAL, e o modo visual (v/V) chegou na v2.1.118.
- Algumas teclas estão fora de alcance: Ctrl+C, Ctrl+D e Ctrl+M não podem ser remapeadas, e o prefixo Ctrl+B do tmux engole os atalhos antes que o Claude Code os veja.
How to Enable Vim Editor in Claude Code CLI
Canal: ProgrammingKnowledge21:32
Claude Code v2.1.118 — Vim Visual Mode & Custom Themes
Canal: Claude Code Updates0:41
How to use Vim in Claude Code
Canal: HAMY LABS5:41
Claude Code release notes — v2.1.118 & v2.1.288
Notas de versão: github.com/anthropics/claude-code
Keybindings — official documentation
Docs: code.claude.com/docs
Os fatos desta página foram conferidos com a documentação oficial de keybindings e com as entradas v2.1.118 e v2.1.288 do changelog; as capturas de tela vêm dos vídeos acima. O comportamento descrito corresponde ao Claude Code v2.1.288 (outubro de 2026).
As capturas de tela são quadros dos vídeos citados, usados com atribuição e ligados ao timestamp original em cada passo.
Remapear teclas e ativar o modo vim, passo a passo
Remapeie teclas no keybindings.json
- 1
Abra o Claude Code e confira seu ambiente
Rode claude no seu terminal para começar uma sessão. Personalizar teclas e o modo vim são recursos do CLI: tudo nesta página acontece no mesmo prompt. Na v2.1.288 ou mais recente você também ganha os atalhos novos da visão de agents: busca com Ctrl+F e saltos entre grupos com Alt+↑/↓.
Uma sessão recém-aberta do Claude Code, pronta para personalização.Ver em 0:17 - 2
Abra o keybindings.json com /keybindings
Digite /keybindings no prompt. Se o ~/.claude/keybindings.json ainda não existir, o Claude Code cria o arquivo e abre no seu editor. Qualquer mudança salva é detectada automaticamente — sem reiniciar.
O menu de comandos filtra enquanto você digita — /keybindings é uma das entradas.Ver em 0:34 - 3
Mapeie uma tecla a uma ação dentro de um contexto
O arquivo contém um array bindings agrupado por contexto — Chat, Autocomplete, Agents, Task, Scroll e mais. Cada bloco mapeia uma tecla a um nome de ação: undefined }. Adicione o campo $schema no topo e seu editor autocompleta todos os nomes de ação.
- 4
Desvincule com null e encadeie chords
Atribua null a uma tecla para desligar um padrão — "ctrl+s": null desativa o stash do texto. Chords são separados por espaço: "ctrl+x ctrl+k" significa pressionar Ctrl+X e, em até três segundos, Ctrl+K. Algumas combinações são reservadas e não podem ser remapeadas: Ctrl+C, Ctrl+D, Ctrl+M, Ctrl+[ e Ctrl+I.
Ative o modo vim
- 5
Abra o painel de ajustes com /config
Prefere um interruptor a editar JSON na mão? O /config abre o painel mostrado no vídeo, com as abas Status, Config e Usage e um campo de busca que filtra a lista enquanto você digita.
O painel /config lista todos os ajustes, incluindo o Editor mode.Ver em 0:40 - 6
Filtre a lista até o Editor mode
Digite edit no campo de busca e a lista se reduz ao ajuste Editor mode. De fábrica ele mostra normal — a edição estilo readline do Claude Code, familiar para quem vem do bash ou dos keybindings do Emacs.
O Editor mode começa em normal; Espaço troca.Ver em 1:08 - 7
Aperte Espaço para mudar para vim
Com a linha do Editor mode destacada, aperte Espaço — o valor passa de normal para vim. A linha de ajuda deixa o combinado claro: Space para mudar, Enter para salvar, / para buscar, Esc para cancelar.
Uma apertada no Espaço basta para escolher vim.Ver em 1:11 - 8
Salve e repare no -- INSERT --
Aperte Enter para salvar. O Claude Code mostra "Set editor mode to vim" e o rodapé ganha o marcador -- INSERT -- do vim. A escolha persiste entre sessões na mesma máquina — fica guardada como editorMode dentro do ~/.claude.json, um arquivo de execução que você não deve linkar nos seus dotfiles, já que ele também guarda caches de OAuth e estado de sessões.
Salvo — o rodapé agora mostra o indicador -- INSERT -- do vim.Ver em 1:28 - 9
Digite no insert mode, comande no normal mode
O insert mode digita como de costume. O Escape leva ao normal mode: h, j, k, l movem o cursor, b e w saltam entre palavras, d apaga, c muda, r substitui. Rodar /vim de novo desliga o modo inteiro. As teclas do próprio vim não são remapeáveis pelo keybindings.json — o vimInsertModeRemaps é o ajuste para sequências em INSERT como jj.
- 10
Selecione texto com o modo visual (v2.1.118+)
Tutoriais antigos dizem que o modo visual não existe — isso envelheceu. A v2.1.118 trouxe o modo visual (v) e o modo de linha visual (V), com seleção, operadores e retorno visual: v mais um motion seleciona caracteres, V mais um motion seleciona linhas inteiras, e então d, y ou c age sobre a seleção.
A v2.1.118 trouxe a seleção com v e V ao modo vim do Claude Code.Ver em 0:16
Atalhos padrão que valem a pena memorizar
- 11
Aprenda os atalhos padrão que mais importam
Shift+Tab circula os modos de permissão, Enter envia, Ctrl+J insere quebra de linha, Ctrl+L limpa a entrada, Ctrl+R busca no histórico, Ctrl+O alterna o transcript, Ctrl+T mostra os todos, Ctrl+B manda uma tarefa para o plano de fundo e Ctrl+X Ctrl+K encerra os agents. Na visão de agents (v2.1.288+), Ctrl+F encontra uma sessão pelo nome e Alt+↑/↓ salta entre grupos — e tudo isso é remapeável no keybindings.json.
keybindings.json vs /config vs /vim: quem muda o quê
Três camadas controlam o que suas teclas fazem no Claude Code. Elas se empilham em vez de competir — escolha a camada que combina com a mudança que você quer.
- 1O keybindings.json remapeia ações pontuais. Leve o chat:externalEditor para o ctrl+e, desvincule o chat:stash, adicione um chord ctrl+x. Granular, portátil e seguro para versionar.
- 2O /config → Editor mode troca o modelo de edição inteiro entre normal (readline) e vim. Um interruptor, salvo na hora, válido para todas as sessões futuras daquela máquina.
- 3O /vim faz exatamente o mesmo que o interruptor do Editor mode — é o caminho mais curto e o comando usado no walkthrough do HAMY LABS. Rode de novo para voltar ao normal.
- 4Seu terminal intercepta algumas teclas antes de o Claude Code as ver: o prefixo Ctrl+B do tmux, o Ctrl+A do GNU screen e o Ctrl+Z, que suspende o processo. Isso se resolve no terminal, não no keybindings.json.
- 5Dentro do modo vim, o vimInsertModeRemaps é a única forma de remapear o comportamento do vim, como jj para escape — o keybindings.json de propósito não toca nas teclas internas do vim.
Regra de bolso: um atalho irritante → keybindings.json; outro estilo de edição por inteiro → modo vim; uma tecla que nunca chega → confira primeiro o terminal.
Keybinding não funciona? Corrija nessa ordem
Quase todas as reclamações sobre keybindings se resumem a cinco causas. Percorra a lista antes de editar o arquivo de novo.
- 1Nada muda depois de editar: confirme que o arquivo é ~/.claude/keybindings.json (não o settings.json) e que o JSON faz parse. Inicie o Claude Code com --debug para enxergar avisos de associação, como ações escritas errado ou contextos desconhecidos.
- 2Uma tecla se recusa a ser remapeada: Ctrl+C, Ctrl+D, Ctrl+M (sempre Enter), Ctrl+[ (sempre Escape) e Ctrl+I (sempre Tab) são reservadas. Caracteres imprimíveis digitados em campos de texto vão para a entrada, não para as associações.
- 3Ctrl+B ou Ctrl+A nunca chega: tmux e GNU screen os consomem como prefixos. Remapeie o atalho no keybindings.json ou troque o prefixo do multiplexador.
- 4Reusar um prefixo de chord falha: se ctrl+x inicia vários chords, você precisa desvincular todos os chords ctrl+x antes de ctrl+x sozinho funcionar como tecla simples.
- 5As teclas do vim ignoram suas associações: de propósito — o modo vim cuida das próprias teclas. Use o vimInsertModeRemaps para sequências em insert, e atualize o Claude Code se a seleção com v ou V não fizer nada (exige v2.1.118+).
Para restaurar qualquer padrão, apague a linha dele do keybindings.json — é a remoção, e não um valor “default” salvo, que devolve a associação original.