How keys work

A koshi shortcut is a sequence of chords, not a single chord. The default leader is Ctrl, so <C-p> l means "hold Ctrl and press p, release, then press l".

Keys belong to the terminal you are sitting at. Each attached terminal reads its own keybinding.kdl, so two terminals on one session can use different shortcuts.

Pending sequences

Once you press the first chord, koshi holds the sequence open. The hint bar at the bottom lists what the next key can be, and the chords you already pressed are marked with the theme's accent colour. The bar updates as you type, without waiting for the next frame.

While a sequence is open, keys go to koshi — not to the program in the pane — until the sequence completes or you cancel it with Esc. A key that matches no continuation is discarded and leaves the sequence open. Prefix-only sequences have no timeout.

chord-timeout-ms applies only when the same sequence is both a complete binding and the prefix of a longer one. At that ambiguity deadline, koshi fires the complete binding.

Modes

Bindings live in modes. Locked input is a mode of its own: with <C-l> every key goes straight to the focused program, which is how you use a program that wants the same chords koshi does.

Inspecting the live keymap

koshi keys list                    # active shortcuts
koshi keys list --mode <MODE>
koshi keys list --scope user       # only what your config added
koshi keys describe "<C-p> l"      # what it does and where it came from

Conflicts

koshi keys conflicts

Reports clashes, sequences made unreachable by a shorter prefix, and warnings. Run it after editing keybinding.kdl — a shortcut hidden behind a prefix never fires, and nothing else tells you.

Validate a file before adopting it:

koshi keys validate path/to/keybinding.kdl

Next