Master Key is a tool for becoming a power-user of your VSCode keybindings. Features include:
- extensive documentation of your bindings (sidebar suggestions, visual guide and inline text documentation)
- predefined keybinding sets
- modal bindings (ala Vim),
- recording of keyboard input (a.k.a. keyboard macros)
- a powerful TOML-based keybinding specification
This curated snippet from the Master Key's Larkin preset defines a VIM-like feature to update a count argument along with a downward motion that uses the count argument:
# front matter...
[[bind]]
foreach.num = ['{{keys(`[0-9]`)}}']
key = "{{num}}"
command = "master-key.updateCount"
args.value = "{{num}}"
finalKey = false
mode = '{{not_modes(["insert"])}}'
doc.name = "count {{num}}"
doc.description = "Add digit {{num}} to the count argument of a command"
doc.combined.key = "0-9"
doc.combined.name = "count 0-9"
doc.combined.description = "Add digit 1-9 to count argument of a command"
[[bind]]
key = "j"
command = "cursorMove"
mode = "normal"
args.value = '{{key.count}}'
args.select = '{{code.editorHasSelection || val.select}}'
args.to = "down"
args.by = "wrappedLine"
doc.name = "↓"
doc.combined.name = "↓/↑"
doc.combined.key = "j/k"
doc.combined.description = "move down/up"
doc.description = "move down"Master Key validates this TOML file, providing inline linting of the file as you edit.
The easiest way to get started is to activate the built-in keybindings that come with Master Key.
- Install this extension
- On windows only: restart VSCode — there is an active investigation to avoid this workaround.
- Run the command
Master Key: Activate Keybindings - Select the built-in binding set "Larkin"
- Review Larkin's documentation (e.g. using
Master Key: Show Text Documentation)
You can start creating your own bindings based off an available preset using Master key: New Keybinding Copy: this will open a TOML file and insert the preset bindings into the file.
You can revert back to the state before master keybindings was installed using Master Key: Deactivate Keybindings.
To learn more about how to use Master Key read the documentation.
Learn and review your bindings on a keyboard layout:
Review your bindings in the text documentation
See a sidebar listing possible bindings for the current mode and prefix of keys already pressed:
The example above shows some of the bindings available in normal mode.
Here are some of the cool editing features that come with the built-in Larkin keybindings provided by Master Key with the help of selection utilities. These bindings follow in the footsteps of Vim, Kakoune and Helix.
Select by word, line, paragraph and more:
Expand by indent, quotes and brackets:
Once you've selected the object, run commands to do stuff (e.g. delete/change/comment)
Quickly create multiple selections, by splitting selections:
matching by word:
or using saved selections:
Filter out the ones you don't want, either by pattern:
or manual removal:
Swap selected objects with one another:
Avoid lengthy key sequences by repeating the last action-related selection with "," and the last action with ".":
Record longer command sequences and replay them. These are sometimes referred to as keyboard macros:
Note
Command recording comes with a few limitations. Master key can record some edits, and any commands that are issued through master key bindings. Commands that are not part of this binding file (e.g. a standard call to Cmd/Ctrl+V to paste) will not be recorded. Also note that some edits cannot be recordings using VSCode's API (e.g. automated completion of parenthesis).
Insert or remove appropriate characters before and after each selection:
When you create your own keybindings using Master Key's special .toml keybinding format you get several powerful features that make it possible to easily create keybindings that would be difficult or impossible to implement without writing your own extension.
Your bindings can be modal—a special key (like escape) switches you to a different mode where all the keys on your keyboard can be used to issue commands specific to that mode.
[[bind]]
key = "j"
mode = "normal"
command = "cursorMove"
args.to = "down"Express an entire series of bindings using the foreach field.
[[bind]]
foreach.num = ['{{key(`[0-9]`)}}']
doc.name = "count {{num}}"
key = "{{num}}"
command = "master-key.updateCount"
args.value = "{{num}}"Update state with the master-key.captureKeys, master-key.updateCount, master-key.setValue and then use this state in downstream commands using
expressions surrounded in {{}}
[[bind]]
doc.name = "between pair"
key = "m t"
description = """
Select between a pair of the specified character. Example: `m t '` would
select all characters that fell between two single quote characters.
"""
command = "runCommands"
[[bind.args.commands]]
command = "master-key.captureKeys"
args.acceptAfter = 1
[[bind.args.commands]]
command = "selection-utilities.selectBetween"
args.str = "{{key.captured}}"
args.fartherBoundary = falseMaster key records recent key presses, allowing you to create commands that quickly repeat a previous sequence using master-key.replayFromHistory or master-key.pushHistoryToStack and master-key.replayFromStack. You can determine how much history is recorded by setting master-key.maxCommandHistory in your settings.
[[bind]]
default = "{{bind.edit_motion}}"
key = ";"
doc.name = "repeat motion"
doc.description = """
Repeat the last motion command. Motions usually move the cursor or change the selection.
"""
repeat = "{{key.count}}"
command = "master-key.replayFromHistory"
args.index = """{{
last_history_index(|i| {
(history[i]?.tags?.contains("motion") ?? false) &&
(history[i]?.doc?.name != "repeat motion" ?? false) &&
(history[i]?.doc?.name != "shrink selection" ?? false)
})
}}"""Of course, just like all of the built-in bindings in Master Key, you can document your bindings so that they show up legibly within the discoverability features above. The toml file is a literate document used to generate the textual documentation and all bindings' names will show up in the visual documentation as appropriate.
This repository was designed to be worked with in unix-like environments. No effort to support development on Windows has been made. The setup relies on a working version of mise installed. You can satisfy this requirement by copying and running the following in bash.
curl https://mise.run | shYou can then install all dependencies for this project as follows:
mise activate
mise install