Keybinding Claude Code: Rebind, Unbind, dan Chord

Saya ingin satu tombol untuk menyisipkan baris baru lalu memilih tombol yang tampak kosong. Ia menolak terikat, dalam senyap, dan saya mengira file-nya yang salah. Bukan: tombol yang saya pilih adalah prefiks dari tiga chord bawaan, dan sebuah chord di konteks aktif mana pun menahan prefiksnya tetap terpesan. Binding saya sedang bersaing dengan mekanisme yang keberadaannya tidak saya sadari.

Sistem keybinding-nya lebih terstruktur daripada yang biasanya dibuat perkakas terminal — sembilan belas konteks, daftar action bernamespace, dukungan chord sungguhan — dan strukturnya itulah yang membuat sebagian rebind menolak bekerja dengan alasan yang tidak kentara. Tulisan ini membahas file-nya, konteksnya, aturan prefiks chord, tombol yang terpesan beserta alasannya, dan bagaimana vim mode serta keybinding hidup berdampingan tanpa berkelahi.

Satu file, dimuat ulang otomatis

Jalankan perintah keybindings dan Claude Code membuat atau membuka file-nya untuk Anda. Isinya sebuah objek berisi array blok, masing-masing menyebut satu konteks dan peta dari keystroke ke action. URL schema di bagian atas bersifat opsional dan layak dipertahankan — ia memberi Anda autocompletion untuk nama action di editor mana pun yang membacanya, dan itu penting karena jumlahnya jauh lebih dari seratus.

// ~/.claude/keybindings.json — run /keybindings to create it.
// Changes are detected and applied WITHOUT restarting.
{
  "$schema": "https://www.schemastore.org/claude-code-keybindings.json",
  "bindings": [
    {
      "context": "Chat",
      "bindings": {
        "ctrl+e": "chat:externalEditor",
        "ctrl+u": null
      }
    }
  ]
}

# Actions are namespace:action — chat:submit, app:toggleTodos.
# Setting one to null unbinds the default.
#
# Modifiers join with +:  ctrl  shift  alt|opt|option|meta
#                         cmd|command|super|win
# The cmd group is only detected in terminals that report the
# Super modifier (Kitty protocol, xterm modifyOtherKeys). Most
# do not — use ctrl or meta for bindings that must work anywhere.

Konteks adalah alasan binding Anda tidak menyala

Setiap binding milik sebuah konteks, dan binding di konteks yang keliru sekadar tidak pernah berjalan. Ada sembilan belas konteks, dan pembagiannya lebih halus daripada dugaan kebanyakan orang — dialog permission, penampil diff, model picker, dan penjelajah plugin semuanya punya konteks sendiri. Empat yang benar-benar akan Anda sentuh adalah berikut ini.

Konteks yang layak diketahui:

Rebind yang benar-benar layak dilakukan

Sebagian besar default sudah baik. Empat ini yang saya lihat diubah orang lalu dipertahankan:

• Action editor eksternal, kalau Anda menulis prompt panjang. Default-nya sebuah chord dan sebuah tombol kontrol yang sudah diklaim banyak terminal.
• Action scroll lompat ke bawah, yang tidak punya chord default yang berfungsi di keyboard MacBook — kombinasi standarnya sama sekali tidak sampai ke Claude Code di macOS.
• Action background task, yang default-nya tombol yang juga merupakan prefiks tmux. Ada alternatif chord justru untuk alasan ini.
• Action stash prompt, kalau tombol default-nya Anda pakai untuk hal lain di shell, dan banyak orang begitu.

Aturan prefiks chord

Inilah mekanisme yang memblokir rebind saya, dan ia layak dipahami alih-alih disiasati. Chord adalah keystroke yang dipisahkan spasi, dan chord mana pun di konteks aktif menahan keystroke pertamanya. Mengambil kembali keystroke itu sebagai binding tombol tunggal berarti melepas setiap chord yang memakainya — dan keluarga bawaannya membentang di dua konteks, jadi melepas hanya yang terlihat menyisakan prefiksnya tetap terpesan.

# Chords are keystrokes separated by a space:
#   "ctrl+k ctrl+s"   press Ctrl+K, release, then Ctrl+S
#
# The rule that catches people: a chord in ANY active context
# keeps its prefix RESERVED. To reclaim ctrl+x as a single key
# you must unbind every chord that uses it — and the default
# ctrl+x family spans TWO contexts.
{
  "bindings": [
    {
      "context": "Task",
      "bindings": { "ctrl+x ctrl+b": null }
    },
    {
      "context": "Chat",
      "bindings": {
        "ctrl+x ctrl+k": null,
        "ctrl+x ctrl+e": null,
        "ctrl+x": "chat:newline"
      }
    }
  ]
}

# Unbind SOME but not all chords on a prefix and pressing that
# prefix still enters chord-wait mode for the survivors.

Empat tombol yang tidak bisa Anda miliki

Tiap pemesanan punya alasan konkret, dan salah satunya fakta tentang terminal alih-alih keputusan siapa pun. Tombol interrupt dan exit dipatri di kode. Yang ketiga terpesan karena terminal mengirim byte yang identik untuknya dan untuk Enter, sehingga mengikatnya terpisah secara fisik tidak mungkin. Dan yang keempat sama sekali tidak pernah diteruskan ke aplikasi terminal.

# Cannot be rebound, and the reasons are worth knowing:

  Ctrl+C      hardcoded interrupt / cancel
  Ctrl+D      hardcoded exit
  Ctrl+M      terminals send an identical byte to Enter (both CR)
  Caps Lock   never delivered to terminal applications at all

# Conflicts with things that are not Claude Code:

  Ctrl+B      tmux prefix — press twice to send it through
  Ctrl+A      GNU screen prefix
  Ctrl+Z      Unix process suspend

# This is why the background-task action gained the
# ctrl+x ctrl+b chord alongside its ctrl+b default: the chord
# sidesteps the tmux prefix entirely.

Vim mode dan keybinding tidak berkelahi

Keduanya beroperasi di lapisan berbeda, dan mengetahui lapisan mana memiliki apa menghemat banyak kebingungan:

• Vim mode menangani input di level teks — gerakan kursor, mode, motion. Keybinding menangani action di level komponen.
• Tombol escape di vim mode memindahkan insert ke normal mode dan tidak memicu action cancel.
• Sebagian besar shortcut bertombol kontrol lewat begitu saja melalui vim mode menuju sistem keybinding.
• Tombol vim itu sendiri tidak bisa dipetakan ulang lewat file ini. Urutan dua tombol di insert mode yang dipetakan ke escape adalah setting terpisah.

Ketika sebuah binding tidak berlaku

Claude Code memvalidasi file-nya saat dimuat dan memperingatkan soal error parsing, nama konteks yang tidak valid, nilai action yang tidak valid, bentrokan dengan shortcut terpesan, dan binding ganda dalam satu konteks. Peringatan itu muncul saat file dimuat dan juga ditulis ke debug log, jadi memulai dengan flag debug adalah cara melihat detailnya alih-alih ringkasannya.

Kalau file-nya valid dan binding-nya tetap tidak melakukan apa-apa, penyebab lazimnya adalah konteks lalu pemesanan chord, dengan urutan itu. Periksa bahwa action yang Anda ikat memang ada di konteks tempat Anda meletakkannya — sebuah action chat di blok Global adalah JSON yang valid, nama action yang valid, dan sepenuhnya mati.

Dua hal membuat sistem ini mudah begitu Anda tahu: binding itu tercakup, jadi separuh dari semua kegagalan adalah satu blok di konteks yang keliru, dan chord menahan prefiksnya, jadi separuh sisanya adalah tombol yang tidak sekosong kelihatannya. Selebihnya sekadar pencarian. Pertahankan baris schema di bagian atas file untuk autocompletion, mulai dengan flag debug pertama kali sebuah binding berulah, dan raih setting flavour readline sebelum Anda mengikat ulang pengeditan teks tombol demi tombol.