# Koshi 0.6.0 — keybinding.kdl (/docs/v0.6/configuration/keybinding-kdl) User bindings are applied over the built-in ones. A user binding wins for the same key; every key you do not mention keeps its built-in action. The file sits directly in the [config directory](/docs/v0.6/configuration#where-the-files-go). Each terminal reads it for itself when it attaches, so two terminals on one session can use different shortcuts. Any error drops the whole file. Run `koshi keys conflicts` after editing — it exits 2 when koshi would drop the file — and `koshi keys list` to see what is actually active. ## Top-level settings [#top-level-settings] `version` is required. Every other setting is optional and may appear at most once, beside the `mode` blocks. | Key | Value | Default | Since | | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ------- | ------- | | `chord-timeout-ms` | integer — ambiguity delay when one sequence is both a complete binding and the prefix of a longer binding | `500` | ≥ 0.1.0 | | `which-key-delay-ms` | integer — ms from a shortcut's first key until the hint bar shows the keys that continue it; `0` shows them with the first key | `300` | ≥ 0.1.0 | | `max-chord-depth` | integer 0–255 — most keys one shortcut may chain. A shortcut longer than this can never fire, and `koshi keys conflicts` reports it | `4` | ≥ 0.1.0 | | `leader` | string — what `` stands for: a modifier run like `"C-"`, or a single chord like `""` | `"C-"` | ≥ 0.1.0 | | `unlock-alternative` | string — the chord that leaves locked mode, **in place of** `` | none | ≥ 0.1.0 | ## Key grammar [#key-grammar] Keys use angle brackets. Spaces join keys into a sequence. | Written | Means | | --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | `` | Ctrl+t. Modifiers are `C` Ctrl, `A` Alt, `S` Shift, `D` Super | | `` | Several modifiers on one key | | `` `` `` `` `` | Named keys. The others are ``, ``, ``, ``, ``, ``, ``, ``, ``, ``, and `` to `` | | `T` | An uppercase letter is that letter with Shift: `` | | `p` | The leader, then `p` | Always bracket named keys. A bare word like `Tab` is read as one chord **per character** — `T`, then `a`, then `b`. With leader `"C-"`, `p` is ``. With leader `""` it becomes `` then `p`. Explicit keys such as `` never move when the leader changes. ## Key sequences [#key-sequences] A key that starts a longer shortcut opens a sequence. While it is open, no key reaches the program. A sequence that is not also a complete binding waits for its next key with no time limit; a key that continues nothing is discarded and the sequence stays open. `` ends it. For example, `` then `z` discards `z`, and a following `n` opens a new pane. ### Repeating keys [#repeating-keys] These actions repeat from their prefix: after a shortcut of two or more keys fires one, the prefix stays open and the last key alone fires it again. * `core:focus-pane-left`, `-down`, `-up`, `-right` * `core:resize-pane-left`, `-down`, `-up`, `-right` * `core:focus-next-floating-pane`, `core:focus-previous-floating-pane` * `core:scroll-pane-up`, `core:scroll-pane-down` ` ` focuses left, left again, then down. A key that fires a non-repeating action ends the prefix; `` ends it too. `koshi keys describe` prints `continuous: true` for these shortcuts. ## mode blocks [#mode-blocks] A `mode` block holds the bindings for one mode. `"normal"` and `"locked"` are the base modes: locked passes keys straight to the program except the unlock chord. The other modes are open only while their screen is: | Mode | Open while | | ----------------------- | ----------------------------------- | | `"pane-placement"` | The tiled pane move preview is open | | `"pane-move-choice"` | The move chooser is open | | `"floating-pane-move"` | Floating pane move mode is open | | `"floating-pane-tray"` | The floating pane tray is open | | `"notification-center"` | The notification center is open | A block for any other mode name binds nothing, and `koshi keys conflicts` warns that the mode is unregistered. | Node | Meaning | | ---------------------------- | ----------------------------------------------------------------- | | `bind "" "core:action"` | Two strings: the key sequence and the **full**, namespaced action | | `remove ""` | Void a key in this mode so lower layers no longer bind it | A bare action name like `new-tab` is rejected with a hint — write `core:new-tab`. A `bind` takes no arguments: a fixed choice lives in the action name (`core:new-pane-left`), an open value lives in the CLI. Run `koshi actions list` for every name you can bind to, and `koshi actions run ` to run one from a shell. `core:quit` leaves the session; it does not end one. See [Actions](/docs/v0.6/keybindings/actions). ## The complete default keymap [#the-complete-default-keymap] ```kdl title="keybinding.kdl" // keybinding.kdl — the complete default keymap. version 2 chord-timeout-ms 500 which-key-delay-ms 300 max-chord-depth 4 leader "C-" // the leader = the Ctrl modifier run (default) // unlock-alternative "" // replaces ; also bind it to core:unlock in "locked" mode "normal" { // reserved lock/unlock chord — explicit, never moves with the leader bind "" "core:lock" // leader-relative — rebind `leader` and all of these move together bind "q" "core:quit" bind "g" "core:mouse-select" bind "p n" "core:new-pane" // n with the default leader bind "p h" "core:new-pane-left" bind "p j" "core:new-pane-down" bind "p k" "core:new-pane-up" bind "p l" "core:new-pane-right" bind "p s" "core:new-pane-stacked" bind "p f" "core:new-pane-floating" bind "p u" "core:toggle-pane-floating" bind "p " "core:focus-next-floating-pane" // repeats bind "p " "core:focus-previous-floating-pane" // repeats bind "p w" "core:toggle-floating-pane-tray" bind "p i" "core:toggle-pane-pinned" bind "p m" "core:begin-pane-placement" bind "p x" "core:close-pane-tree" bind "p " "core:focus-pane-left" // repeats bind "p " "core:focus-pane-down" bind "p " "core:focus-pane-up" bind "p " "core:focus-pane-right" bind "s " "core:resize-pane-left" // repeats bind "s " "core:resize-pane-down" bind "s " "core:resize-pane-up" bind "s " "core:resize-pane-right" bind "t n" "core:new-tab" // n with the default leader bind "t x" "core:close-tab" // explicit chords — they never move with the leader bind "" "core:toggle-pane-fullscreen" bind "" "core:toggle-notification-center" bind "" "core:next-tab" bind "" "core:previous-tab" } mode "locked" { // locked mode passes every other key straight to the program. bind "" "core:unlock" bind "q" "core:quit" bind "g" "core:mouse-select" } mode "pane-placement" { bind "" "core:select-pane-target-left" bind "" "core:select-pane-target-down" bind "" "core:select-pane-target-up" bind "" "core:select-pane-target-right" bind "" "core:select-pane-insertion-left" bind "" "core:select-pane-insertion-down" bind "" "core:select-pane-insertion-up" bind "" "core:select-pane-insertion-right" bind "" "core:cycle-pane-placement-span" bind "" "core:select-next-placement-tab" bind "" "core:select-previous-placement-tab" bind "s" "core:toggle-pane-placement-stack" bind "" "core:confirm-pane-placement" bind "" "core:cancel-pane-placement" } mode "pane-move-choice" { bind "t" "core:begin-tiled-pane-placement" bind "f" "core:begin-floating-pane-move" bind "" "core:confirm-pane-move-choice" bind "" "core:cancel-pane-move-choice" } mode "floating-pane-move" { bind "" "core:move-floating-pane-left" bind "" "core:move-floating-pane-down" bind "" "core:move-floating-pane-up" bind "" "core:move-floating-pane-right" bind "" "core:select-next-floating-pane" bind "" "core:select-previous-floating-pane" bind "" "core:confirm-floating-pane-move" bind "" "core:cancel-floating-pane-move" } mode "floating-pane-tray" { bind "" "core:select-tray-tile-left" bind "" "core:select-tray-tile-down" bind "" "core:select-tray-tile-up" bind "" "core:select-tray-tile-right" bind "" "core:activate-selected-tray-tile" bind "a" "core:toggle-minimize-all-floating-panes" bind "" "core:close-floating-pane-tray" bind "p w" "core:toggle-floating-pane-tray" } mode "notification-center" { bind "" "core:select-newer-notification" bind "" "core:select-older-notification" bind "x" "core:dismiss-selected-notification" bind "c" "core:clear-notifications" bind "" "core:close-notification-center" bind "" "core:toggle-notification-center" } ``` ## Moving a pane [#moving-a-pane] `p m` starts a move preview in the current client. When the client shows a floating pane it did not pin, it opens the `"pane-move-choice"` chooser first. The preview's mode name is `"pane-placement"`; its keymap takes priority over the normal or locked map until the move is accepted or cancelled. The base mode is retained, so cancelling a move started from locked mode returns to locked mode. The default locked map binds no key that opens it; a locked client can drag a pane's grab handle, or you can bind a key in the `locked` block. Arrow keys choose a pane to swap with. Shift+Arrow chooses an edge to insert beside the selected pane or stack. Space cycles the available split spans. Tab and Shift+Tab preview another visible tab, where the same keys can choose a pane or insertion edge. `s` switches the target between a pane and its stack. Enter accepts the move; Escape cancels it. Each local mode must keep a live binding for its closing action, or the file is rejected: `core:cancel-pane-placement` in `pane-placement`, `core:cancel-pane-move-choice` in `pane-move-choice`, `core:cancel-floating-pane-move` in `floating-pane-move`, `core:close-floating-pane-tray` in `floating-pane-tray`, and `core:close-notification-center` in `notification-center`. Only the client that started the move sees the preview. After it is accepted, all clients see the new layout. By default the mode stays active after an accepted move; `stay-in-pane-placement-mode-after-placement #false` makes it end instead. Mouse drags can also preview and accept a move. To insert with a mouse, hold Shift when starting the drag. ## Checking your work [#checking-your-work] ```bash koshi keys validate ~/.config/koshi/keybinding.kdl # before adopting it koshi keys conflicts # clashes and dead shortcuts koshi keys describe " l" # what one sequence does koshi keys list --scope user # only what you added ```