Skip to content

Keys ​

Every command has a key, and you can change any of them. keymap = "direct" is the default: every command has 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.

Keys are spelled out in full, joined by +: Ctrl+Shift+T, Ctrl+Alt+Left. A key is named by what you press, so ? is shown as Shift+/. A capital letter never stands for Shift: after the leader, T is the t key alone and Shift+H is the capital.

On macOS, keys use your menus' signs, in this order: Control ⌃, Option ⌥, Shift ⇧, Command ⌘, then the key, as in ⇧⌘N and ⌃⌥←. Keys pressed one after another are a space apart: ⌃Space T. The direct keys are ⌘-based; on Linux they're Ctrl+Shift with a letter.

On macOS, closing the window or pressing ⌘Q doesn't quit. insensical stays in the menu bar, still telling you when a pane needs you. Open it again from the menu bar item, the Dock or Spotlight. To quit, choose Quit insensical or press ⌥⌘Q. If a pane is running or waiting, it asks first: Esc goes back, W closes the window and leaves the application running, Enter quits. With menu-bar off there's no item, and ⌘Q quits. ⌘, opens Settings. ⌘H, ⌥⌘H and ⌥⌘Q are the application's and don't reach a pane.

On Linux, closing the window quits. The quit command has no key; find it in the palette, or add a line to [keys], such as "ctrl-alt-q" = "quit".

On macOS, Option isn't Alt unless you say so. Option with a key types the layout's character (Option+B is ∫), so a shell's Alt+B doesn't answer. Set option-as-alt = true and Option is Alt in the pane, and you can't type those characters there. If the system's ⌃Space ("select the previous input source") is on, it takes the key before the leader can.

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

Seeing every key ​

Press Ctrl+Shift+/ or Ctrl+F1, or leader ?, or choose "Show every key" in the palette. A sheet lists the commands in a card for each heading, each with its keys, for the keymap in use with your changes.

  • Commands with no key are folded at the foot of their card, under a line such as "2 without a key". Click it to show them. If your own [keys.direct] or [keys.leader] table took a command's key, it isn't folded: its row says not in your [keys.direct].
  • Typing narrows the sheet by a command's words, heading or keys: split, ctrl alt. It searches every command, with a key or without.
  • A chord you press while the sheet is open is described, not run. The foot shows what you pressed and the command it runs. This is also how to find out how a key is written.
  • Escape, Enter, "Close" or a click outside closes it.

Locking the keys ​

When a program needs every key, such as an editor, another multiplexer or a remote desktop, press Ctrl+Alt+Shift+L in either keymap, or choose "Give every key to the program, or take them back" in the palette.

While locked, every key goes to the program in the pane, including the window's chords, the leader, copy, paste and find. Only the lock key stays the window's, and it unlocks.

  • The pane with the keyboard shows a "Locked" mark in its header, or over its corner when headers are hidden. Click it to unlock.
  • The pointer works as usual. The lock is off the next time the window opens.
  • A lock key you set in [keys] must be a single chord; one starting with the leader can't unlock.

The leader keymap ​

Use it to keep the Ctrl+Shift chords for your programs.

toml
keymap = "leader"
leader = "ctrl-space"   # the default
  • The direct keymap's chords then reach the panes. Copy, paste, paste-selection and find keep their chords in both keymaps.
  • While the leader waits, a panel at the bottom lists every key that can follow.
  • If nothing follows the leader for about a second, it goes to the program. Press the leader twice to send its own key; Escape cancels it.
  • Setting leader alone changes nothing. keymap = "leader" turns the leader keymap on.
  • If the desktop takes Ctrl+Space (input method switchers do), 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.

Changing keys ​

Add a line under [keys] to rebind a command:

toml
[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 what you hold first: ctrl, shift, alt, cmd or super, joined by hyphens, as in ctrl-shift-t or ctrl-alt-left.
  • On Linux ctrl-shift-] and ctrl-} are the same key, and so are ctrl-shift-/ and ctrl-?.
  • Separate keys in a sequence with spaces. leader stands for the key leader is set to.
  • Your keys are added to the defaults and win where they overlap. To remove a default, set its key to none. The command names are in the reference.
  • A bad name or key is reported in the top bar; the rest still apply. The bar also reports conflicts: the same key for two commands (ctrl-shift-y and shift-ctrl-y are the same), a key that's also the start of a sequence, and the leader bound to a command.

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

toml
[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"
  • A table lies over that keymap's defaults; keys and commands it doesn't mention keep them.
  • To take a default key away, write it with none: "ctrl-shift-t" = "none". Removing a line from the table brings the default back.
  • Each table is read only in its own keymap; [keys] is read in both, on top.
  • Copy, paste, paste-selection, find and the lock key aren't in either table; change them in [keys].
  • isc config prints both tables in full, with unbound commands as lines to uncomment.

You can make commands of your own. A command is a name and a list of steps under [commands]. Bind it to a key like any other; the palette lists it. If one is written wrongly, the top bar says so and only that command is left out.

toml
[commands]
tidy = ["minimize-others", "zoom"]
tests = [{ run = "cargo watch -x test", in = "right" }]

[commands.review]
title = "Review: lazygit over the tab"
steps = [
  { run = "lazygit", in = "float", cwd = "~/src/app" },
  "float-fill",
]

[keys]
"ctrl-alt-t" = "tests"
"leader shift-t" = "tests"

A step is one of three things:

  • A command's name, in quotes: any command in the reference, such as "split-right".
  • { run = "…" } runs a program in a new pane. in says where: "tab" (the default), "right" or "down" (beside the pane in front), or "float". cwd is the starting directory, and ~ is your home on the pane's machine. keep = true leaves the pane open when the program ends. run = "" runs your shell. The words are split at spaces; when an argument has a space, write a list: run = ["sh", "-c", "make && ./serve"].
  • { type = "…" } types text into the pane in front. End it with \n to press Enter: { type = "git status\n" }.

What to know:

  • Steps run in order. After a step that opens a pane, the pane in front is the new one: [{ run = "", in = "right" }, { type = "npm test\n" }] types into the new shell.
  • If a step fails, the rest don't run, and a notice says which stopped. A step that asks first, such as close-tab with something running, stops the rest too.
  • A name is letters, digits and hyphens, and can't be an existing command.
  • The palette and the leader's panel ("Your commands") list yours; the sheet of keys doesn't.
  • isc do NAME runs one from a shell: see Running things.
  • A step can't be another command of your own, and there are no conditions or loops.

A mode makes plain keys into commands. For things you do many times in a row, like moving a pane's edge, a mode is a set of keys that run commands with no leader and no chord, for as long as it's on. One comes ready: resize mode. Turn it on, press the arrows or H J K L to move the edges of the pane in front, and press Escape when done.

  • Turning it on. In the leader keymap, and in a terminal, it's leader, then Shift+R. In the direct keymap it has no key: choose "Resize mode" in the palette, or give resize-mode a key under [keys].
  • While it's on, its keys aren't sent to the program.
  • Escape or Enter turns it off. Any other key turns it off too, then does what it always does, so the first letter you type is typed.
  • A small sign with the mode's name stays at the bottom while it's on.

Write modes of your own, or change the resize mode, under [modes]:

toml
[modes.resize]
title = "Resize mode"
"left" = "resize-left"
"down" = "resize-down"
"up" = "resize-up"
"right" = "resize-right"
"h" = "resize-left"
"j" = "resize-down"
"k" = "resize-up"
"l" = "resize-right"

[modes.tabs]
title = "Walk the tabs"
timeout = 3
"n" = "next-tab"
"p" = "previous-tab"
"x" = "close-tab"

[keys]
"leader shift-t" = "tabs-mode"
  • A mode's command is its name with -mode after it: resize-mode, tabs-mode. Bind it like any other.
  • Each key runs one command, insensical's or your own from [commands]. A key is written as under [keys] and is one key, not a sequence.
  • timeout is seconds with no key before the mode turns itself off. Without it the mode stays on.
  • [modes.resize] in your settings replaces the ready one whole: write every key you want.
  • A mode's name is letters, digits and hyphens, and NAME-mode can't be an existing command, so there can't be a mode called copy.
  • A key in a mode can't turn on another mode. The page in a browser has no modes.

Keys that are fixed ​

WhereKeys
The sidebar field, the palette, the search fieldThe keys of a field below, Enter, Escape
A held pasteEnter pastes, Escape drops it
A kept pane whose program has endedEnter closes it
The restart questionEnter restarts, Escape doesn't
The question before a tab or a project closesEnter closes, Escape doesn't
The question before panes are clearedEnter clears, Escape doesn't
The new project's name and directoryThe keys of a field below; Tab and Shift+Tab go round the card; Up and Down mark a folder, Right goes into it, Left goes up; Enter, Escape
The question about agentsEnter adds the hooks, Escape doesn't, N stops the offer
Adding a machineThe keys of a field below, Up, Down; Enter meets the marked machine, then gives the answer of the coloured button; Escape leaves
Where one of several machines is chosen: a new project, the settings sheetAlt+M goes to the next machine

Every place you type a line is a proper field: a name, a search, the palette, an address, a token. Pressing puts the caret there, dragging selects, and in the window a double press takes a word and a triple press the line. In lists such as the palette, Up, Down, Tab and Enter stay the list's, and Left, Right, Home and End are the field's.

In the window (Cmd for Ctrl on a Mac)In a terminal
Move a characterLeft, RightLeft, Right, Ctrl+B, Ctrl+F
Move a wordCtrl+Left, Ctrl+Right (Option on a Mac), Alt+B, Alt+FCtrl+Left, Ctrl+Right, Alt+Left, Alt+Right, Alt+B, Alt+F
Start, endHome, End (Cmd+Left, Cmd+Right on a Mac)Home, End, Ctrl+A, Ctrl+E
SelectShift with any move; Ctrl+A selects allShift with any move; Cmd+A or Ctrl+Shift+A selects all, where your terminal sends them
DeleteBackspace, DeleteBackspace, Delete
Delete a wordCtrl+Backspace, Ctrl+W, Ctrl+Delete, Alt+D (Option on a Mac)Ctrl+Backspace, Alt+Backspace, Ctrl+W, Ctrl+Delete, Alt+D
Delete to the start, to the endCtrl+U, Ctrl+K (Cmd+Backspace, Cmd+Delete on a Mac)Ctrl+U, Ctrl+K
Undo, redoCtrl+Z, Ctrl+Shift+Z or Ctrl+YCtrl+Z or Ctrl+/, Ctrl+Shift+Z or Ctrl+Y
Copy, cut, pasteCtrl+C, Ctrl+X, Ctrl+V, Shift+Insert pastesPaste with your terminal's paste; there's no copy or cut

A paste is always one line. A secret field, such as a token, shows dots and copies and cuts nothing. Where a key above already means something, such as Ctrl+Left and Ctrl+Backspace on a setting with a value to change or reset, it keeps that meaning, and the field has Alt+B, Alt+F and Ctrl+W instead.

Every question over the window is a card with buttons at its foot, each naming the key that gives the same answer. Enter gives the coloured button on the right: the accent colour when it doesn't end anything, red when it does.