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.

[!NOTE]

Le modifiche al file keybindings vengono rilevate automaticamente e applicate senza riavviare Claude Code.

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

{
  "$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+s": 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 il 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 del completamento automatico

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, assegnata a Ctrl+E per impostazione predefinita, mostrava una spiegazione del comando generata dal modello nelle richieste di permesso di Bash e PowerShell.

Le finestre di dialogo usano confirm:yes e confirm:no per accettare e annullare anche quando non pongono una domanda sì-o-no. Se assegni una lettera semplice come y o n in questo contesto, la lettera agisce anche sulle finestre di dialogo che non la mostrano mai come tasto. Una finestra di dialogo che mostra y e n come tasti legge quelle lettere autonomamente e non ha bisogno di alcuna assegnazione.

Nella maggior parte delle finestre di dialogo, premere Ctrl+C o Ctrl+D due volte chiude la finestra invece di uscire da Claude Code. Il suggerimento dopo la prima pressione indica se la seconda pressione chiude la finestra o esce. Entrambi i tasti sono riservati e non possono essere riassegnati.

Questo esempio assegna y a confirm:yes e n a confirm:no:

{
  "bindings": [
    {
      "context": "Confirmation",
      "bindings": {
        "y": "confirm:yes",
        "n": "confirm:no"
      }
    }
  ]
}

Con queste assegnazioni, y e n continuano a digitare lettere mentre un campo di testo ha il focus.

Prima della v2.1.280, y era assegnato anche a confirm:yes e n a confirm:no per impostazione predefinita. Se hai creato il tuo keybindings.json con /keybindings prima della v2.1.280, il file elenca entrambe le assegnazioni, che restano attive finché non elimini quelle due righe.

Azioni dei permessi

Azioni disponibili nel contesto Confirmation per le finestre di dialogo dei permessi:

Azioni della trascrizione

Azioni disponibili nel contesto Transcript:

transcript:toggleShowAll si applica solo nel renderer classico; nel rendering a schermo intero, il visualizzatore della trascrizione non offre un'opzione per mostrare tutto.

Azioni della 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 in linea del renderer classico, che cerca sempre tra i prompt di tutti i progetti. historySearch:cycleScope ha effetto solo nel rendering a schermo intero, dove Ctrl+R apre invece una finestra di dialogo di ricerca e Ctrl+S ne cambia l'ambito. Gli altri tasti della finestra di dialogo sono fissi e non possono essere riassegnati: Enter o Tab inserisce 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:

In una finestra di dialogo a schede, tabs:next e tabs:previous cambiano scheda mentre la riga delle schede ha il focus. In alcune finestre di dialogo, come /help e /sandbox, i tasti per cambiare scheda funzionano anche dall'interno del contenuto della scheda.

Up e Down spostano il focus tra la riga delle schede e il contenuto della scheda, e un elenco nel contenuto risponde ai tasti solo mentre ha il focus.

Azioni degli allegati

Azioni disponibili nel contesto Attachments:

Azioni del footer

Azioni disponibili nel contesto Footer:

Mentre è selezionato un elemento del footer, come una riga nel pannello degli agenti sotto il prompt, Enter lo apre anche se riassegni Enter nel contesto Chat a chat:queueSubmit o chat:newline.

Le assegnazioni Chat su tasti che il contesto Footer non assegna, come Shift+Tab per chat:cycleMode, continuano a funzionare mentre un elemento è selezionato.

Azioni del selettore dei messaggi

Nell'elenco dei messaggi del menu di riavvolgimento, ti sposti tra i messaggi e ne scegli uno con le azioni Select e i loro tasti predefiniti. Anche le tue assegnazioni Select per quelle azioni si applicano lì. Il contesto MessageSelector non ha azioni né assegnazioni predefinite proprie. Usalo per cambiare un tasto solo per questo elenco, assegnando un'azione Select come select:accept in un blocco MessageSelector.

Questo esempio assegna o alla scelta del messaggio evidenziato nel menu di riavvolgimento, senza modificare nessun altro elenco:

{
  "bindings": [
    {
      "context": "MessageSelector",
      "bindings": {
        "o": "select:accept"
      }
    }
  ]
}

Prima della v2.1.283, questo elenco ignorava le assegnazioni Select e aveva azioni proprie: messageSelector:up, messageSelector:down, messageSelector:top, messageSelector:bottom e messageSelector:select. Se il tuo keybindings.json assegna uno di questi nomi, l'assegnazione continua a funzionare in questo elenco come l'azione Select che fa la stessa cosa. Home e End saltano a una delle due estremità dell'elenco; prima della v2.1.283, tasti come Shift+K e Shift+J lo facevano per impostazione predefinita.

Azioni del diff

Queste azioni raggiungono solo il precedente visualizzatore di diff di Claude Code, che /diff apre al di fuori del rendering a schermo intero dopo aver disabilitato il mod cc-plugin-diff in /plugin. Finché quel mod è abilitato, /diff apre invece la finestra di dialogo del diff. Un keybindings.json che nomina queste azioni viene caricato senza errori in entrambi i casi.

Azioni disponibili nel contesto DiffDialog:

L'elenco dei file risponde anche alle azioni Select, tramite i loro tasti predefiniti e le tue assegnazioni Select. select:previous e select:next passano al file precedente e successivo, e Enter apre il diff del file selezionato tramite select:accept. Per cambiare uno di questi tasti solo per l'elenco dei file, assegna l'azione Select in un blocco DiffDialog.

Prima della v2.1.283, l'elenco dei file ignorava le assegnazioni Select, e Enter apriva il diff del file selezionato tramite un'azione separata diff:viewDetails. Se il tuo keybindings.json assegna diff:viewDetails, l'assegnazione continua a funzionare nell'elenco dei file come select:accept.

La vista dettagliata del diff assegna anche tasti in stile pager alle azioni di scorrimento standard. Queste assegnazioni fanno parte del contesto DiffDialog e si applicano solo nella vista dettagliata; i valori predefiniti del contesto Scroll elencati in Azioni di scorrimento restano invariati.

Azioni del pannello del diff

Azioni per il pannello del diff che /diff apre nel rendering a schermo intero. app:cycleDiffBase è nel contesto DiffPanel, attivo mentre il pannello è aperto; le altre sono Global.

Il mod cc-plugin-diff integrato disegna questo pannello e gestisce app:cycleDiffBase, app:diffFileListUp e app:diffFileListDown. app:toggleReplTab, app:toggleDiffNoiseFilter e app:toggleDiffPreSession raggiungono solo il precedente pannello di Claude Code, che /diff apre dopo aver disabilitato cc-plugin-diff in /plugin.

Azioni del selettore del modello

Azioni disponibili nel contesto ModelPicker:

Azioni del cursore dello sforzo

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

Azioni Select

Azioni disponibili nel contesto Select:

Nei pannelli a elenco come /skills, /mcp e /tasks, Claude Code applica le tue assegnazioni select:pageUp, select:pageDown, select:first e select:last. Nella maggior parte degli altri elenchi, come il selettore /model, si applicano le tue assegnazioni select:first e select:last. PageUp e PageDown scorrono le opzioni di quegli elenchi indipendentemente dalle tue assegnazioni.

Prima della v2.1.280, quegli altri elenchi ignoravano Home, End e le tue assegnazioni select:first e select:last.

Prima della v2.1.283, l'elenco degli strumenti di /mcp scorreva per pagine con tasti PageUp e PageDown fissi, indipendentemente dalle tue assegnazioni.

Azioni dei plugin

Azioni disponibili nel contesto Plugin:

Azioni sopra il prompt

Azioni per la fascia sopra il prompt, la striscia condivisa in cui i mod disegnano pulsanti, campi di input e menu di selezione. abovePrompt:toggle e abovePrompt:focus si applicano nel contesto Chat. Le altre azioni si applicano nel contesto dell'elemento che ha il focus della tastiera nella fascia o in un riquadro.

Nel contesto AbovePrompt, anche Right e Left eseguono abovePrompt:next e abovePrompt:previous per impostazione predefinita, e anche Space esegue abovePrompt:press.

Il contesto AbovePrompt assegna anche Up, Down, PageUp, PageDown, Home ed End alle azioni di scorrimento del riquadro da pane:scrollUp a pane:bottom, quindi per cambiare uno di questi tasti per la fascia, assegna l'azione di scorrimento in un blocco AbovePrompt.

Azioni del riquadro

Azioni per un riquadro disegnato da un mod. Le azioni di scorrimento, ridimensionamento e chiusura si applicano nel contesto Pane. pane:close si applica anche nel contesto PaneField, quindi funziona mentre uno dei campi del riquadro ha il focus. pane:next e pane:previous si applicano nel contesto Global quando è aperto più di un riquadro.

Il contesto Pane assegna anche Tab, Shift+Tab, Enter ed Escape alle stesse azioni sopra il prompt della fascia, e i campi di input e i menu di selezione di un riquadro usano i contesti AbovePromptInput e AbovePromptSelect. Focus della tastiera e tasti di scelta elenca cosa fa ciascun tasto in un riquadro.

Azioni delle impostazioni

Azioni disponibili nel contesto Settings. Le azioni select:accept e confirm:no sono riutilizzate dai contesti Select e Confirmation con un comportamento specifico per le impostazioni: le modifiche si applicano a ciascuna impostazione non appena la cambi, quindi Escape chiude il pannello con le modifiche salvate anziché rifiutarle.

Azioni degli agenti

Azioni disponibili nel contesto Agents, che si applica nella vista agenti, aperta con claude agents. Richiede v2.1.257 o successiva.

Mentre la vista agenti è aperta, Claude Code usa l'assegnazione Agents per qualsiasi tasto assegnato dal contesto Agents, e ignora un'assegnazione Chat o Global sullo stesso tasto. Ad esempio, premendo Ctrl+S nella vista agenti si cambia il raggruppamento delle sessioni anziché attivare il chat:stash predefinito.

La scorciatoia dell'editor esterno dell'input di dispatch non è un'azione Agents. La vista agenti segue l'assegnazione chat:externalEditor del contesto Chat, Ctrl+G per impostazione predefinita.

Nella vista agenti le assegnazioni si attivano con singole pressioni di tasto, quindi la combinazione Ctrl+X Ctrl+E assegnata a chat:externalEditor non apre l'editor in quella vista.

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

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, per contesto:

• Chat: ctrl+x ctrl+k, ctrl+x ctrl+e, ctrl+x enter, ctrl+x ctrl+a, ctrl+x ctrl+s e ctrl+x tab
• Task: ctrl+x ctrl+b
• DiffPanel: ctrl+x b
• Pane: ctrl+x left, ctrl+x right, ctrl+x up, ctrl+x down e ctrl+x x
• PaneField: ctrl+x x

L'accordo ctrl+x enter richiede v2.1.247 o successivo, ctrl+x b, ctrl+x ctrl+a e ctrl+x tab richiedono v2.1.260 o successivo, e ctrl+x ctrl+s richiede v2.1.275 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": "Pane",
      "bindings": {
        "ctrl+x left": null,
        "ctrl+x right": null,
        "ctrl+x up": null,
        "ctrl+x down": null,
        "ctrl+x x": null
      }
    },
    {
      "context": "PaneField",
      "bindings": {
        "ctrl+x x": 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 ctrl+s": 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:

Campi di testo

Se associate un carattere, una cifra o uno spazio semplice, potete comunque digitare quel carattere in un campo di testo all'interno di una finestra di dialogo o di un pannello. Uno di questi campi è la risposta Other a una domanda che Claude pone. Mentre il campo ha il focus, un tasto stampabile che premete senza Ctrl, Alt o Cmd va al campo, e Claude Code non lo confronta con le vostre associazioni.

Questi tasti eseguono comunque le loro associazioni mentre il campo ha il focus:

• Tasti che non digitano un carattere, come Enter, Escape, Tab e i tasti freccia
• Qualsiasi tasto premuto con Ctrl, Alt o Cmd
• Il secondo tasto di un accordo già in corso

Al prompt principale, Claude Code confronta ogni tasto rispetto ai contesti attivi, come Chat, e digita il tasto solo quando nessuna associazione lo cattura.

Interazione con la modalità Vim

Quando abiliti la modalità vim con l'impostazione Editor mode in /config, 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à e movimenti
• Scorciatoie da tastiera gestiscono le azioni a livello di componente, come attivare o disattivare le attività o inviare un messaggio
• Il tasto Esc in modalità vim passa dalla modalità INSERT alla modalità 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

Nella riga Other di una domanda posta da Claude, in modalità vim Escape non annulla subito la domanda. Tranne che in modalità screen reader, la riga parte in modalità INSERT ogni volta che le dai il focus. Quando premi Escape nella riga Other, la riga passa alla modalità NORMAL oppure scarta un comando vim digitato a metà, e la domanda resta aperta. Premi di nuovo Escape in modalità NORMAL per annullare la domanda.

Annullare una domanda con un solo tasto

Per annullare una domanda con un solo tasto in modalità vim, associa un altro tasto a select:cancel nel contesto Select. Puoi annullare in questo modo dalla riga Other di una domanda in cui selezioni una sola opzione. In modalità screen reader o in una domanda in cui puoi selezionare più opzioni, il tasto associato non annulla, quindi annulla invece con Escape.

Scegli un tasto da premere con Ctrl o Alt. Una lettera o una cifra da sola va invece alla riga Other e non raggiunge le tue scorciatoie da tastiera. Ad esempio, per associare Ctrl+Q, aggiungi questo a ~/.claude/keybindings.json:

{
  "bindings": [
    {
      "context": "Select",
      "bindings": {
        "ctrl+q": "select:cancel"
      }
    }
  ]
}

Dopo aver salvato il file, premi Ctrl+Q nella riga Other di una domanda in cui selezioni una sola opzione. La domanda si chiude sia che la riga sia in modalità INSERT sia in modalità NORMAL.

Convalida

Claude Code convalida i tuoi scorciatoie da tastiera e scrive un avviso nel log di debug per:

• Errori di analisi (JSON non valido o struttura non valida)
• Modificatori scritti male, come ctl+k. Claude Code elimina la parte che non riconosce e applica il binding al tasto rimanente, k in questo esempio.
• Uno spazio accanto a + in una stringa di tasti, come ctrl+ k. Claude Code legge la stringa come un accordo di ctrl+ seguito da k. Nessuna pressione di tasto corrisponde a ctrl+ da solo, quindi il binding non si attiva mai. Rimuovi lo spazio.
• 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.
• Conflitti di scorciatoie riservate
• Binding duplicati nello stesso contesto

Avvia Claude Code con --debug per visualizzare i dettagli.