Keybindings do Claude Code

Os teus dedos esperam que Ctrl+K abra uma paleta de comandos. Claude Code tem outras ideias. Cada reflexo errado custa um segundo de pensamento e quebra o ritmo.

O custo acumula. Uma sessão longa de Claude Code funciona com memória muscular, e os padrões errados lutam contra essa memória muscular em cada tecla. Anos de hábitos com VS Code, Vim ou Emacs não se desaprendem por comando. Retreinar as mãos para corresponder ao layout de atalhos de outra pessoa é esforço desperdiçado.

A solução está integrada. Um ficheiro JSON, organizado por contexto, trata de todos os atalhos que te importam. Tens sequências de acordes, stacks de modificadores, e a opção de eliminar um padrão de vez. As edições entram em vigor no momento em que guardas. Aqui está como configurar tudo para que a ferramenta pareça tua.

Primeiros Passos com Keybindings Personalizados

Escreve /keybindings dentro do Claude Code. Esse slash command cria ou abre ~/.claude/keybindings.json por ti. O ficheiro vive na pasta habitual ~/.claude/ ao lado do resto das tuas configurações.

A forma do ficheiro é simples:

{
  "$schema": "https://platform.claude.com/docs/schemas/claude-code/keybindings.json",
  "$docs": "https://code.claude.com/docs/en/keybindings",
  "bindings": [
    {
      "context": "Chat",
      "bindings": {
        "ctrl+e": "chat:externalEditor",
        "ctrl+u": null
      }
    }
  ]
}

Três chaves de topo nível fazem todo o trabalho:

• $schema - Opcional. Apontar para o URL do JSON Schema dá ao teu editor autocompletar e validação gratuitos. Vale a pena manter.
• $docs - Opcional. Um link para documentação para consultas rápidas.
• bindings - O array onde vivem os teus atalhos. Uma entrada por contexto.

Esse campo de schema é uma vantagem silenciosa. Qualquer editor com suporte a JSON Schema sugere então ações válidas e nomes de contexto enquanto escreves.

Os ficheiros guardados são detetados em tempo real. Edita, carrega em guardar, e os novos bindings funcionam imediatamente. Sem reinício.

Como Funcionam os Contextos

Cada binding vive dentro de um contexto, e o contexto decide quando o atalho está ativo. Um binding Chat só dispara quando o input principal do chat tem foco. Reutiliza as mesmas teclas em contextos diferentes e cada uma pode fazer algo diferente.

Existem 17 contextos no Claude Code:

Global é o caso especial. Um atalho aqui dispara independentemente do que estás a ver. Usa-o com cuidado. Um Ctrl+K global vai disparar dentro do chat, dentro do autocompletar e dentro de uma revisão de diff.

Todas as Ações, Listadas

Os nomes de ações seguem o padrão namespace:ação. Abaixo estão todas as ações em todos os contextos, com a tecla padrão.

Ações Globais

Estas disparam em qualquer lugar:

Utilizadores frequentes da lista de tarefas carregam app:toggleTodos o dia todo. Se Ctrl+T entra em conflito com o teu terminal, move-o para um lugar mais amigável.

Ações do Chat

Onde aterra a maioria das teclas:

No Windows sem VT mode, chat:cycleMode recua para Meta+M. Aplica-se a builds de Node mais antigas do que 24.2.0/22.17.0, e Bun mais antigo do que 1.2.23. O atalho controla os modos de permissão, que definem o que Claude tem permissão para fazer.

Ações de Histórico

Para navegar de volta por prompts anteriores:

Ações de Autocompletar

Ativas enquanto o menu de sugestões está aberto:

Ações de Confirmação

Bindings para diálogos de permissão e aprovação:

Ações do Transcript

Ações de Pesquisa de Histórico

Ações de Tarefas

Ações de Tema, Ajuda e Configurações

Ações de Navegação

Tabs, anexos, rodapé, diffs, seletor de modelo, selects e o seletor de mensagens vivem aqui:

Sintaxe de Teclas

A sintaxe para definir combinações de teclas é fácil de ler.

Modificadores

Junta teclas modificadoras à tecla alvo com +:

• ctrl ou control para a tecla Control
• alt, opt, ou option para Alt/Option
• shift para Shift
• meta, cmd, ou command para Meta/Command

Alguns exemplos:

ctrl+k          Single modifier + key
shift+tab       Shift + Tab
meta+p          Command/Meta + P
ctrl+shift+c    Multiple modifiers

Letras Maiúsculas e Shift

Uma letra maiúscula isolada já significa Shift. Por isso K num binding é o mesmo que shift+k. Útil para layouts ao estilo Vim onde j e J (ou k e K) mapeiam para ações diferentes.

Um ponto a ter em atenção. Quando um modificador está presente, a capitalização deixa de importar. ctrl+K e ctrl+k são o mesmo binding. Com modificadores presentes, a maiúscula é apenas cosmética.

Sequências de Acordes

Os acordes dão-te atalhos multi-tecla. Coloca um espaço entre as teclas:

ctrl+k ctrl+s Press Ctrl+K, release, then press Ctrl+S

Isso abre muito mais espaço do que bindings de tecla única. Ficaste sem combos de teclas livres? Os acordes adicionam centenas de novas opções sem pisar em nada.

Teclas Especiais

As teclas não-caracter têm os seus próprios nomes:

• escape ou esc
• enter ou return
• tab
• space
• up, down, left, right
• backspace, delete

Desativar Atalhos Padrão

Define a ação como null e o padrão desaparece:

{
  "bindings": [
    {
      "context": "Chat",
      "bindings": {
        "ctrl+s": null
      }
    }
  ]
}

Útil quando um padrão entra em conflito com o teu terminal, o teu sistema operativo, ou outra ferramenta a correr ao lado do Claude Code. Também podes anular um padrão e depois dar a essa mesma tecla uma nova ação.

Atalhos Reservados

Duas teclas são programadas de forma rígida. Não podem ser reconfiguradas:

Claude Code vai rejeitar qualquer tentativa de remapear estas, e faz bem. Todos os utilizadores de terminal esperam que Ctrl+C interrompa e Ctrl+D saia. São convenções Unix.

Conflitos com Multiplexers de Terminal

A correr Claude Code dentro de tmux, GNU screen, ou um multiplexer similar? As teclas de prefixo vão causar problemas:

task:background vem com Ctrl+B, que é exatamente o prefixo do tmux. Se vives no tmux, reconfigura-o no primeiro dia:

{
  "bindings": [
    {
      "context": "Task",
      "bindings": {
        "ctrl+b": null,
        "ctrl+shift+b": "task:background"
      }
    }
  ]
}

Esse conflito apanha muitos developers que correm Claude Code dentro de sessões com multiplexer.

Interação com Modo Vim

Liga o modo vim com /vim e funciona numa camada separada dos keybindings:

• Modo Vim trata da edição de texto. Movimento do cursor, modos INSERT e NORMAL, motions, text objects.
• Keybindings tratam de ações ao nível da app. Ligar/desligar a lista de tarefas, enviar uma mensagem, abrir o seletor de modelo.

A tecla Escape é a divisão mais clara. Dentro do modo vim, Escape sai do INSERT e vai para NORMAL. Não chama chat:cancel. A maioria dos atalhos Ctrl+tecla passa diretamente pelo modo vim para a camada de keybindings, por isso Ctrl+T ainda liga/desliga a lista de tarefas mesmo a partir do modo NORMAL.

No modo NORMAL, ? abre a ajuda ao estilo vim, não o ecrã de ajuda do Claude Code.

Utilizadores frequentes do modo de pensamento em modo vim devem colocar chat:thinkingToggle por detrás de um acorde que fique longe dos motions do vim. O guia de modo interativo cobre como o modo vim, slash commands e o resto das funcionalidades interativas se encaixam.

Validação e Diagnósticos

Claude Code verifica o teu ficheiro de keybindings em cada gravação e sinaliza:

• Erros de parsing na sintaxe ou estrutura JSON
• Nomes de contexto inválidos que não correspondem aos 17 contextos suportados
• Conflitos com atalhos reservados se tentares rebind Ctrl+C ou Ctrl+D
• Conflitos com multiplexers de terminal para Ctrl+B, Ctrl+A e Ctrl+Z
• Bindings duplicados no mesmo contexto

Corre /doctor para ver todos os avisos de keybinding num só lugar. É o caminho mais rápido para perceber por que um atalho se comporta mal.

Exemplos de Configuração Práticos

Algumas configurações retiradas de setups reais.

Configuração para Utilizador de VS Code

A vir do VS Code e quer os atalhos habituais de volta:

{
  "$schema": "https://platform.claude.com/docs/schemas/claude-code/keybindings.json",
  "bindings": [
    {
      "context": "Chat",
      "bindings": {
        "ctrl+k ctrl+s": "chat:stash",
        "ctrl+shift+p": "chat:modelPicker",
        "ctrl+g": "chat:externalEditor"
      }
    },
    {
      "context": "Global",
      "bindings": {
        "ctrl+shift+t": "app:toggleTodos"
      }
    }
  ]
}

Setup Amigável com tmux

Evita o conflito com o prefixo do tmux:

{
  "$schema": "https://platform.claude.com/docs/schemas/claude-code/keybindings.json",
  "bindings": [
    {
      "context": "Task",
      "bindings": {
        "ctrl+b": null,
        "ctrl+shift+b": "task:background"
      }
    }
  ]
}

Setup Minimalista sem Distrações

Elimina os atalhos que os teus dedos continuam a acionar por acidente:

{
  "$schema": "https://platform.claude.com/docs/schemas/claude-code/keybindings.json",
  "bindings": [
    {
      "context": "Chat",
      "bindings": {
        "ctrl+s": null,
        "ctrl+u": null
      }
    }
  ]
}

Power User com Acordes

Coloca funcionalidades menos usadas por detrás de acordes para que os combos de tecla única fiquem livres:

{
  "$schema": "https://platform.claude.com/docs/schemas/claude-code/keybindings.json",
  "bindings": [
    {
      "context": "Chat",
      "bindings": {
        "ctrl+k ctrl+t": "chat:thinkingToggle",
        "ctrl+k ctrl+m": "chat:modelPicker",
        "ctrl+k ctrl+e": "chat:externalEditor"
      }
    }
  ]
}

As tuas ações mais usadas mantêm os seus bindings de uma tecla. Todo o resto está a um acorde de distância.

Construir a Tua Própria Configuração

Vai devagar. Remapear a app toda de uma vez é uma armadilha. Aqui está uma abordagem mais sensata:

1. Corre /keybindings para gerar o ficheiro de configuração
2. Escolhe os teus três piores problemas (conflitos de atalhos, bindings em falta, disparos acidentais)
3. Corrige esses três primeiro com entradas específicas
4. Corre /doctor para validar o ficheiro
5. Passa uma sessão completa de Claude Code nele e nota o que ainda causa fricção
6. Itera adicionando ou ajustando bindings à medida que a fricção aparece

Personalizar todos os atalhos possíveis não é o objetivo. O objetivo é fechar a diferença entre o que as tuas mãos esperam e o que Claude Code faz. Cinco a dez bindings costumam ser suficientes para a ferramenta parecer nativa.

Os keybindings tratam do lado físico. CLAUDE.md e slash commands personalizados tratam do lado comportamental. Liga os dois e Claude Code começa a parecer que foi construído à volta do teu fluxo de trabalho.