Skip to content

Changing keys

Every ws shortcut can be changed in ~/.config/ws/keys.toml:

  • The leader (the prefix, Ctrl-Space by default) can be any key or chord.
  • Keys after the leader can be rebound or removed.
  • Sequences put more commands behind one key: leader o p, leader o d.
  • Direct keys run a command with no leader (the Alt layer by default).

The file lists only what you change; everything else keeps its default. A running ws reloads it within 10 seconds of a save. You can edit it by hand, or in the shortcut editor: ws keys, or leader ? then e.

The shortcut editor

Section titled “The shortcut editor”

ws keys in a terminal opens it. Inside ws, leader ? then e opens it in a new tab. It’s also the Keyboard shortcuts tab of Settings (leader S), where changes save as you make them.

Every command is listed by group, with its keys after the leader and its direct keys. Above the list, when the screen is tall enough (30 rows, or whenever you’re using it), a keyboard map shows one layer: what each key runs, colored by group, with free keys as · and sequences as …. The selected command’s keys are underlined on it.

Key Does
j/k, arrows, g/G, PageUp/PageDown Move
Enter New keys after the leader for this command, replacing its old ones. Type them (several make a sequence: o p), then Enter. Backspace takes one back, Esc cancels
a Add a key after the leader, keeping the ones it has
d Add a direct key: press it (it needs Ctrl, Alt or a function key)
x Remove all of this command’s keys
L Change the leader: press the new one
K Use the keyboard map (below)
u Undo the last change
/ Filter by description or command name
w Save to keys.toml
q, Esc Quit. With unsaved changes it asks: w saves and quits, q quits without saving

On the keyboard map:

Key Does
h/j/k/l, arrows Move between keys; the title says what the key under the cursor does
Enter On a sequence (…): open it. On any other key: pick a command for it from the list (j/k or /, then Enter; Esc goes back). Picking adds the key; the command keeps its others
Backspace Out of a sequence
x Clear this key. Clearing a sequence’s last key removes the sequence
Tab Next layer: after the leader, with Shift, Alt (direct keys), Alt with Shift
K, Esc Back to the list
  • Conflicts ask first. A key that runs another command, a key that would turn another command’s key into a sequence, and a direct key programs use (C-w, C-r, …) each say what they’d take; y goes ahead.
  • Mistakes are refused. Every change is loaded the way ws will load it; one that wouldn’t load (a bare letter as a direct key, the leader bound after itself) isn’t made, and the bottom line says why. Notes, like “a key that types” for a plain-key leader, show there too.
  • Only your changes are written. Saving keeps keys.toml’s comments and order. A default you take away is written as "none"; a key you added and then removed disappears from the file.
  • Inside ws, your leader goes to ws first. To use it in the editor (as a new key, or as the new leader), press it twice.
  • Saving applies it. A running ws picks the file up within 10 seconds.

A keys.toml

Section titled “A keys.toml”
[leader]
key = "`"              # the leader; default "C-Space"
twice_sends = true     # the leader twice types it into the pane (default)
which_key = false      # a popup of the keys when you pause after the leader (default off)
which_key_delay = 400  # ms before that popup (default)


[leader.keys]          # keys after the leader
v = "split-below"
w = "none"             # remove a default


[direct]               # keys that work without the leader
"M-/" = "search"
"F8" = "find"

ws keys --print-defaults prints a complete file with every default, to start from:

Terminal window
ws keys --print-defaults > ~/.config/ws/keys.toml

Key names

Section titled “Key names”
Write For
C- Ctrl
M- or A- Alt, which is Option on a Mac
S- Shift, for named keys such as S-Tab; a letter’s case already carries Shift, so write H, not S-h
a character itself: v, H, `, /, !
Space, Enter, Tab, Esc, Backspace those keys
Up, Down, Left, Right, Home, End, PageUp, PageDown those keys
F1 … F24 function keys

Modifiers combine: C-M-x.

Commands

Section titled “Commands”

Every command has a name, such as split-right, focus-left, go-to-tab-3, search, memory or review-pr. ws keys --list lists them all, each with its description and current keys:

$ ws keys --list
leader: C-Space


split-below            split below                    leader s
split-right            split right                    leader v
focus-left             focus pane left                leader h, M-h
…

Choosing a leader

Section titled “Choosing a leader”
Leader A command is Notes
C-Space (default) Ctrl+Space, then a key A chord, then a key
` backtick, then a key Two plain keystrokes. To type a backtick, press it twice
C-a Ctrl+a, then a key tmux’s classic prefix; takes Ctrl-a (start of line) from shells
M-Space Option+Space, then a key Needs Option to send Alt (below)
F12, or Caps Lock remapped to one one key, then a key Needs a key you don’t otherwise use

A plain-key leader (such as `) never reaches the program in the pane. Press it twice to type it (twice_sends).

Option on macOS

Section titled “Option on macOS”

Keys with M- (the default Alt-h/j/k/l, Alt-1…9 and so on, or an Option-based leader) only reach ws if your terminal sends Option as Alt. In Ghostty, add this to its config:

macos-option-as-alt = true

Otherwise Option types special characters. ws doctor checks this when your keys use M-.

Sequences

Section titled “Sequences”

A key after the leader can lead to more keys, like a Vim mapping: give it a table instead of a command.

[leader.keys.o]        # leader o, then:
p = "open-pr"          #   leader o p
d = "open-dev-server"  #   leader o d


[leader.keys.o.r]      # sequences nest: leader o r r
r = "review-pr"
  • The key stops doing what it did. leader o opened the dev server by default; with the table above it waits for the next key instead. ws keys --check notes it: leader o was open-dev-server, now starts a sequence. Put the old command in the sequence if you still want it, as d does here.
  • ws waits for the next key. There’s no timeout: the status line shows PREFIX o until you press one. Esc cancels.
  • The status line says what can follow. After leader o it shows PREFIX o and d open dev server · p open PR · esc cancel (a key that leads further shows as r …). If the which-key popup is on, it follows along too: at the leader it lists sequences under “Sequences”, and after o only what can follow.
  • Sequences show wherever keys do. leader ?, ws keys --list, the finder and menu hints show o p for a command only a sequence reaches.
  • Keys in a sequence use the same names as everywhere else. The leader can’t be one of them, and a sequence needs at least one key.
  • Only after the leader. [direct] keys can’t start a sequence.

The which-key popup

Section titled “The which-key popup”

A popup of every key after the leader, shown when you pause after pressing it. It’s off by default: once you know your keys it mostly gets in the way, and leader ? shows them all whenever you want. To have it:

[leader]
which_key = true
which_key_delay = 400  # ms you pause before it shows

With it off, the status line still hints (a key for a command · ? all keys, or what can follow in a sequence).

Direct keys

Section titled “Direct keys”

Direct keys never reach the program in the pane, so choose ones your shell, editor and agents don’t need.

  • A bare letter isn’t allowed as a direct key; it needs a modifier.
  • ws keys --check warns about keys programs commonly use (C-c, C-d, C-w, C-r, C-h/j/k/l, M-b, M-f, …).

Checking and reloading

Section titled “Checking and reloading”
Terminal window
ws keys --check

It reports errors and notes:

  • Errors: an unknown command, a key name it can’t read, binding the leader itself (after the leader or in a sequence), an empty sequence, or a typo in a section name.
  • Notes: a key that was bound to something else before (including one that now starts a sequence), a direct key programs use, and how a plain-key leader is typed.

A running ws checks the file every 10 seconds. After a good save the top bar says keys reloaded; the leader is …. A bad file shows its error, and ws keeps the keys it had until you fix it. ws doctor checks the file too.

What follows your keys

Section titled “What follows your keys”

Everything that shows keys reads the same keymap, so a change appears in all of them:

  • the which-key popup and the keys overlay (leader ?), sequences included
  • the key hints in context menus
  • the finder’s command list
  • the status line and top bar hints

The key tables in Keys and mouse describe the defaults.

See also

Section titled “See also”