Personalizzare le scorciatoie da tastiera

Personalizzare le scorciatoie da tastiera in Claude Code con un file di configurazione keybindings.

Claude Code supporta scorciatoie da tastiera personalizzabili. Eseguire /keybindings per creare o aprire il file di configurazione in ~/.claude/keybindings.json.

File di configurazione

Il file di configurazione delle scorciatoie da tastiera è un oggetto con un array bindings. Ogni blocco specifica un contesto e una mappa di sequenze di tasti per le azioni.

Questo esempio associa Ctrl+E per aprire un editor esterno nel contesto della chat e annulla l'associazione di Ctrl+U:

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

Contesti

Ogni blocco di binding specifica un contesto dove si applicano i binding:

Prima della v2.1.205, un contesto Doctor e un'azione doctor:fix esistevano per la schermata diagnostica /doctor.

Azioni disponibili

Le azioni seguono un formato namespace:action, come chat:submit per inviare un messaggio o app:toggleTodos per mostrare l'elenco delle attività. Ogni contesto ha azioni specifiche disponibili.

Azioni dell'app

Azioni disponibili nel contesto Global:

Azioni della cronologia

Azioni per navigare nella cronologia dei comandi:

Azioni della chat

Azioni disponibili nel contesto Chat:

*Su Windows senza modalità VT (Node <24.2.0/<22.17.0, Bun <1.2.23), il valore predefinito è Meta+M.

Azioni di autocompletamento

Azioni disponibili nel contesto Autocomplete:

Azioni di conferma

Azioni disponibili nel contesto Confirmation:

*Su Windows senza modalità VT (Node <24.2.0/<22.17.0, Bun <1.2.23), il valore predefinito è Meta+M.

Prima della v2.1.257, un'azione confirm:toggleExplanation, associata a Ctrl+E per impostazione predefinita, mostrava una spiegazione generata dal modello del comando sui prompt di permesso Bash e PowerShell.

Azioni di permesso

Azioni disponibili nel contesto Confirmation per i dialoghi di permesso:

Azioni di trascrizione

Azioni disponibili nel contesto Transcript:

transcript:toggleShowAll si applica solo nel renderer classico; nel rendering a schermo intero, il visualizzatore di trascrizione non offre un'opzione di visualizzazione completa.

Azioni di ricerca nella cronologia

Azioni disponibili nel contesto HistorySearch:

I valori predefiniti di historySearch:next, historySearch:accept, historySearch:cancel e historySearch:execute si applicano alla ricerca nella cronologia inline nel renderer classico, che ricerca sempre i prompt da tutti i progetti. historySearch:cycleScope ha effetto solo nel rendering a schermo intero, dove Ctrl+R apre una finestra di dialogo di ricerca e Ctrl+S cicla il suo ambito. I tasti della finestra di dialogo sono fissi e non possono essere riassociati: Invio o Tab posiziona la corrispondenza evidenziata nell'input del prompt e Esc annulla.

Azioni delle attività

Azioni disponibili nel contesto Task:

Azioni del tema

Azioni disponibili nel contesto ThemePicker:

Azioni della guida

Azioni disponibili nel contesto Help:

Azioni delle schede

Azioni disponibili nel contesto Tabs:

Azioni degli allegati

Azioni disponibili nel contesto Attachments:

Azioni del piè di pagina

Azioni disponibili nel contesto Footer:

Azioni del selezionatore di messaggi

Azioni disponibili nel contesto MessageSelector:

Azioni diff

Azioni disponibili nel contesto DiffDialog:

La visualizzazione dei dettagli diff associa anche i tasti in stile pager alle azioni di scorrimento standard. Questi binding fanno parte del contesto DiffDialog e si applicano solo nella visualizzazione dei dettagli; i valori predefiniti del contesto Scroll elencati in Azioni di scorrimento rimangono invariati.

Azioni del pannello diff

Azioni per il pannello diff che /diff apre nel rendering a schermo intero. app:cycleDiffBase è nel contesto DiffPanel, che è attivo mentre il pannello è aperto; gli altri sono Global. Il pannello richiede Claude Code v2.1.260 o successiva.

Azioni del selezionatore di modelli

Azioni disponibili nel contesto ModelPicker:

Azioni del cursore di sforzo

Azioni disponibili nel contesto EffortSlider, il cursore che si apre quando esegui /effort senza argomenti. I tasti Sinistra, Destra, Invio ed Escape del cursore non possono essere riassociati.

Azioni di selezione

Azioni disponibili nel contesto Select:

Claude Code applica i tuoi binding select:pageUp, select:pageDown, select:first e select:last nel menu /skills. Nella maggior parte degli altri elenchi, come il selezionatore /model, Claude Code pagina con PagSu e PagGiù indipendentemente dai tuoi binding e ignora Home e Fine.

Azioni dei plugin

Azioni disponibili nel contesto Plugin:

Azioni delle impostazioni

Azioni disponibili nel contesto Settings. Le azioni select:accept e confirm:no vengono riutilizzate dai contesti Select e Confirmation con comportamento specifico delle impostazioni: le modifiche si applicano a ogni impostazione non appena la modifichi, quindi Escape chiude il pannello con le modifiche salvate piuttosto che rifiutarle.

Azioni degli agenti

Azioni disponibili nel contesto Agents, che si applica nella visualizzazione dell'agente, aperta con claude agents. Richiede v2.1.257 o successiva.

Mentre la visualizzazione dell'agente è aperta, Claude Code utilizza il binding Agents per qualsiasi tasto che il contesto Agents associa, e ignora un binding Chat o Global sulla stessa chiave. Ad esempio, premendo Ctrl+S nella visualizzazione dell'agente si cambia il raggruppamento della sessione piuttosto che attivare il valore predefinito chat:stash.

La scorciatoia dell'editor esterno dell'input di dispatch non è un'azione Agents. La visualizzazione dell'agente segue il binding chat:externalEditor del contesto Chat, Ctrl+G per impostazione predefinita.

I binding si attivano su singole pressioni di tasto nella visualizzazione dell'agente, quindi l'accordo Ctrl+X Ctrl+E associato a chat:externalEditor non apre l'editor lì.

Azioni vocali

Azioni disponibili nel contesto Chat quando la dettatura vocale è abilitata:

Azioni di scorrimento

Azioni disponibili nel contesto Scroll quando il rendering a schermo intero è abilitato:

Sintassi delle sequenze di tasti

Modificatori

Utilizzare i tasti modificatori con il separatore +:

• ctrl o control - Tasto Control
• shift - Tasto Shift
• alt, opt, option, o meta - Tasto Alt su Windows e Linux, tasto Option su macOS
• cmd, command, super, o win - Tasto Command su macOS, tasto Windows su Windows, tasto Super su Linux

Il gruppo cmd viene rilevato solo nei terminali che segnalano il modificatore Super, come quelli che supportano il protocollo della tastiera Kitty o la modalità modifyOtherKeys di xterm. La maggior parte dei terminali non lo invia, quindi utilizzare ctrl o meta per i binding che si desidera funzionino ovunque.

Ad esempio:

ctrl+k          Ctrl + K
shift+tab       Shift + Tab
meta+p          Option + P su macOS, Alt + P altrove
ctrl+shift+c    Più modificatori

Lettere maiuscole

Claude Code analizza i nomi dei tasti in modo insensibile alle maiuscole, quindi K è lo stesso binding di k e ctrl+K è lo stesso di ctrl+k. Per associare Shift e una lettera, scrivere shift+k.

Layout di tastiera non US

Scrivere i nomi dei tasti dei scorciatoie Ctrl come caratteri latini anche quando il layout di tastiera attivo digita altri caratteri.

Il modo in cui Claude Code associa il tasto premuto a un binding dipende dal tipo di layout:

• Sotto un layout non latino come il cirillico, Claude Code associa i scorciatoie Ctrl in base alla posizione del tasto nel layout US quando il terminale utilizza il protocollo della tastiera Kitty e segnala quella posizione. In tale terminale, con un layout russo attivo, premendo Ctrl e il tasto fisico W si attiva ctrl+w. In un terminale che non segnala la posizione, Claude Code associa quello che il terminale invia per la pressione del tasto: un codice di controllo ASCII attiva il scorciatoio latino, e una pressione del tasto che arriva come carattere cirillico non corrisponde a nessun binding
• Sotto layout che riorganizzano le lettere latine, come AZERTY, Claude Code associa la lettera che il tasto digita, quindi premendo Ctrl e il tasto etichettato A si attiva ctrl+a

Prima della v2.1.247, premere un scorciatoio Ctrl sotto un layout non latino non attivava il suo binding nei terminali che utilizzano il protocollo della tastiera Kitty, come Ghostty, Kitty, WezTerm e iTerm2.

Accordi

Gli accordi sono sequenze di tasti separate da spazi:

ctrl+k ctrl+s   Premi Ctrl+K, rilascia, quindi Ctrl+S

Premere ogni sequenza di tasti entro 3 secondi da quella precedente. Se si attende più a lungo, Claude Code annulla l'accordo e mostra un breve avviso che lo comunica.

Tasti speciali

• escape o esc - Tasto Escape
• enter o return - Tasto Invio
• tab - Tasto Tab
• space - Barra spaziatrice
• up, down, left, right - Tasti freccia
• pageup, pagedown - Tasti Pagina Su e Pagina Giù
• home, end - Tasti Home e Fine
• backspace, delete - Tasti Canc
• wheelup, wheeldown - Eventi di scorrimento della rotella del mouse

Annulla l'associazione delle scorciatoie predefinite

Impostare un'azione su null per annullare l'associazione di una scorciatoia predefinita:

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

Questo funziona anche per i binding degli accordi. Annullare l'associazione di ogni accordo che condivide un prefisso libera quel prefisso per l'uso come binding a tasto singolo. Un accordo in qualsiasi contesto attivo mantiene il suo prefisso riservato, quindi è necessario annullare l'associazione di ogni accordo nel contesto che lo definisce.

Claude Code associa questi accordi predefiniti sul prefisso ctrl+x: ctrl+x ctrl+k, ctrl+x ctrl+e, ctrl+x enter, ctrl+x ctrl+a, e ctrl+x tab in Chat, ctrl+x ctrl+b in Task, e ctrl+x b in DiffPanel. L'accordo ctrl+x enter richiede v2.1.247 o successivo, e ctrl+x b, ctrl+x ctrl+a, e ctrl+x tab richiedono v2.1.260 o successivo. Per reclamare ctrl+x stesso come binding a tasto singolo, annullare l'associazione di tutti loro:

{
  "bindings": [
    {
      "context": "Task",
      "bindings": {
        "ctrl+x ctrl+b": null
      }
    },
    {
      "context": "DiffPanel",
      "bindings": {
        "ctrl+x b": null
      }
    },
    {
      "context": "Chat",
      "bindings": {
        "ctrl+x ctrl+k": null,
        "ctrl+x ctrl+e": null,
        "ctrl+x enter": null,
        "ctrl+x ctrl+a": null,
        "ctrl+x tab": null,
        "ctrl+x": "chat:newline"
      }
    }
  ]
}

Se annulli l'associazione di alcuni ma non di tutti gli accordi su un prefisso, premere il prefisso entra comunque in modalità di attesa degli accordi per i binding rimanenti.

Scorciatoie riservate

Queste scorciatoie non possono essere riassociate:

Conflitti del terminale

Alcune scorciatoie potrebbero entrare in conflitto con i multiplexer di terminale:

Interazione con la modalità Vim

Quando la modalità vim è abilitata tramite /config → Editor mode, le scorciatoie da tastiera e la modalità vim operano indipendentemente:

• Modalità Vim gestisce l'input a livello di input di testo (movimento del cursore, modalità, movimenti)
• Scorciatoie da tastiera gestiscono le azioni a livello di componente (attiva/disattiva attività, invia, ecc.)
• Il tasto Escape in modalità vim passa da INSERT a NORMAL; non attiva chat:cancel
• La maggior parte delle scorciatoie Ctrl+tasto passano attraverso la modalità vim al sistema di scorciatoie da tastiera
• I tasti Vim non sono rimappabili tramite il file delle scorciatoie da tastiera. Per mappare una sequenza in modalità INSERT a due tasti come jj su Escape, utilizzare l'impostazione vimInsertModeRemaps
• In modalità vim NORMAL, ? mostra il menu della guida (comportamento vim)
• In modalità vim NORMAL, / apre la ricerca nella cronologia, lo stesso di Ctrl+R in modalità standard

Convalida

Claude Code convalida i tuoi keybindings e mostra avvisi per:

• Errori di analisi (JSON non valido o struttura non valida)
• Nomi di contesto non validi
• Valori di azione non validi, come un'azione che non è una stringa o null
• Nomi di azione sconosciuti, come un errore di battitura di un'azione registrata. Claude Code salta il binding e mantiene in vigore qualsiasi binding predefinito per quel tasto. Prima della v2.1.246, un binding con un nome di azione sconosciuto disabilitava silenziosamente quel tasto
• Conflitti di scorciatoie riservate
• Binding duplicati nello stesso contesto

Claude Code segnala avvisi quando il file viene caricato e scrive ognuno nel log di debug. Avvia Claude Code con --debug per visualizzare i dettagli.