Keys

There are two keymaps. keymap = "direct" is the default, and gives every command its own chord. keymap = "leader" puts every command on a key you press after a leader key. The reference has the full table for both.

The window always spells a key out in full, joined by +: Ctrl+Shift+T, Shift+H, Ctrl+Alt+Left. That's true in tooltips, the palette, the list that follows the leader, the sheet of keys and the buttons of a question. A key is named by what you press, so ? is shown as Shift+/. A capital letter is the key and never stands for Shift, which is always written. After the leader, T is the t key alone and Shift+H is the capital.

On Linux, the direct keys are Ctrl+Shift with a letter. They avoid Super, which window managers own. On macOS, they're ⌘-based.

On macOS, closing the window doesn't quit the application; ⌘Q does, and so does Quit in its menu. If you open the application again while it has no window, it gets one. Either way, the daemon and every program under it keep running, and the next window shows them. On Linux, closing the window quits. The quit command has no key there, and is in the palette.

On macOS, Option isn't Alt. Option with a key types the character the keyboard layout gives it (Option+B is ∫), and no setting changes that. You can't type a shell's Alt+B and Alt+F, or a program's other Alt keys. If the system's own ⌃Space ("select the previous input source") is on, the system takes it before the leader can.

A chord in the direct keymap doesn't reach the program in the pane. Ctrl+`, Ctrl+Shift+Space and Ctrl+Shift+I are among them. To hand a chord back, set it to none in [keys], use the leader keymap, or lock the keys for as long as the program needs them.

Seeing every key

Press Ctrl+Shift+/ or Ctrl+F1, or leader ?, or choose "Show every key" in the palette.

A sheet opens over the window, with every command under its heading: projects and tabs, panes, arranging panes, floating and minimized, finding and going, text, the application. Beside each command are its keys, each key on a cap. They're the keys of the keymap in use, with your own changes. Keys you press one after another have a mark between them.

• A command with no key is listed too, greyed, and says so.
• Typing narrows the sheet to what matches, by a command's words, its heading or its keys: split, float, ctrl alt.
• If you press a chord while the sheet is open, the sheet describes it instead of running it. The foot of the sheet shows what you pressed, as the keyboard sent it, and the command it runs, or says that it has none and goes to the program. This is also how to find out how a key is written.
• Escape, Enter, "Close" or a click outside closes it. It doesn't resize anything.
• The foot of the sheet says which table of config.toml to change those keys in.

Locking the keys

Press Ctrl+Alt+Shift+L, in either keymap, or choose "Give every key to the program, or take them back" in the palette.

While the keys are locked, every key goes to the program in the pane, including the window's own chords and the leader. Use it for a program whose keys clash with the window's: an editor, another multiplexer, a remote desktop.

• The window keeps only the key that locks, and that key unlocks. Copy, paste and find go to the program too while locked.
• When you lock the keys, the window says so along its top for a moment, with the key that unlocks. After that, the pane with the keyboard shows a "Locked" mark in its header, or over its corner when headers are hidden. Click the mark to unlock.
• The pointer works as usual: you can still click tabs, buttons and dividers.
• The lock belongs to the window, not to a pane. It stays on as you go from pane to pane, and it's off again the next time the window opens.
• If you set your own lock key in [keys], it must be a single chord. A key that starts with the leader doesn't unlock, because the leader goes to the program while locked.

The leader keymap

keymap = "leader"
leader = "ctrl-space"   # the default

• The chords of the direct keymap are then not bound, and reach the programs in the panes.
• Copy, paste, paste-selection and find keep their chords in both keymaps.
• While the leader is waiting, a panel at the bottom of the window lists every key that can follow and what it does, including your own keys. It closes when you press the next key, or after a second. It doesn't resize anything.
• If nothing follows the leader for about a second, the leader is passed to the program. So is a leader followed by a key that isn't bound to anything.
• Press the leader twice to send the leader's own key to the program: Ctrl+Space, Ctrl+Space gives the program one Ctrl+Space.
• Escape after the leader cancels it and sends the program nothing.
• If the leader setting can't be read, that's reported and ctrl-space is used.
• Setting leader alone changes nothing. keymap = "leader" is what turns the leader keymap on.

Ctrl+Space is often the key that switches input method (fcitx, ibus) and, in some editors, the key for completion. If the desktop takes it, the leader never arrives. Choose another with leader = "…".

Repeat. After you move a pane (Ctrl+H Ctrl+J Ctrl+K Ctrl+L), move its edge (H J K L) or move a tab (< >), the same keys work without the leader for one second: leader, L, L, L.

• Any other key ends the repeat and goes to the program.
• So does waiting: a second later, L types an L.
• Nothing else repeats. Focus doesn't, so typing straight after you move focus is never taken for a command.

Changing keys

[keys]
"ctrl-shift-y" = "split-right"   # another key for a command
"leader y" = "split-right"       # after the leader, in either keymap
"alt-enter" = "zoom"
"ctrl-shift-m" = "none"          # leave this key to the program

• Write a key with what you hold first: ctrl, shift, alt, cmd or super, joined by hyphens, as in ctrl-shift-t or ctrl-alt-left.
• You can write a key that has two characters either way on Linux: ctrl-shift-] and ctrl-} are the same key, and so are ctrl-shift-/ and ctrl-?. Keys are shown the first way.
• Separate keys in a sequence with spaces. The word leader stands for the leader key. In the direct keymap it stands for ctrl-space, whatever leader is set to.
• Your keys are added to the defaults, and yours win where the two are the same. The only way to remove a default is to set its key to none.
• The command names are in the reference.
• A name that doesn't exist, or a key that can't be read, is reported in the top bar. The rest of your keys still apply.

If two of your own keys conflict, the top bar reports it. These are conflicts:

• the same key for two commands, however it's written (ctrl-shift-y and shift-ctrl-y are the same key);
• a key that's also the start of a sequence, which would wait a second to see which one you meant;
• the leader bound to a command itself.

A key set to none isn't counted. Replacing a default with your own key isn't a conflict.

You can write out a whole keymap, to see every key in one place and move any of them:

[keys.direct]                  # what keymap = "direct" binds
"ctrl-shift-t" = "new-tab"
"ctrl-t" = "split-right"

[keys.leader]                  # what keymap = "leader" binds: the key after the leader
t = "new-tab"
"shift-h" = "resize-left"

• If a table is present, it replaces all of that keymap's defaults. A command it doesn't list has no key in that keymap. This is different from [keys], which adds.
• Each table is read only in its own keymap. So when keymap = "leader", chords written under [keys.direct] aren't bound, and reach the programs.
• [keys] is still read in both keymaps, on top of the table.
• Copy, paste, paste-selection, find and the key that locks aren't part of either table. They're the same in both keymaps, and you change them in [keys].
• You can't change the leader pressed twice, or Escape after the leader.
• isc config prints both tables in full, with every command that has no key shown as a line to uncomment. A file made from that output lists the commands of the version that printed it. A command added by a later version has no key until you add a line for it.
• A command or key that can't be read is reported in the top bar, which names the table.

Keys that are fixed

Where	Keys
The sidebar field, the palette, the search field	Typing, Backspace, Enter, Escape
A held paste	Enter pastes, Escape drops it
A kept pane whose program has ended	Enter closes it
The restart question	Enter restarts, Escape doesn't
The question before a tab or a project closes	Enter closes, Escape doesn't
The new project's name and directory	Typing, Backspace, Tab, Shift+Tab, Up, Down, Enter, Escape
The question about agents	Enter adds the hooks, Escape doesn't, N stops the offer

Every question that opens over the window looks the same. The window dims behind it, a card says what's being asked and lists what it's about, and the answers are buttons at the foot of the card. Each button names the key that gives the same answer, so you can answer with the pointer or the keyboard. The answer Enter gives is the coloured button on the right: the accent colour when it doesn't end anything, red when it does.