aster Key

Master key helps you to learn, create and use powerful keybindings in VSCode.

If you want to improve your text editing super powers in VSCode, Master Key might just be the tool for you.

[!NOTE] To power users: Master Key was envisioned as a set of tools to make it easy to create powerful keybinding specifications that match your editor style of choice (modal, chorded, etc...). There are currently some limitations, noted in Keybinding Features and Customized Bindings when creating custom binding sets.

To get started

The easiest way to get started is to activate the built-in keybindings that come with Master Key.

1. Install this extension
2. On windows only: restart VSCode — there is an active investigation to avoid this workaround.
3. Run the command Master Key: Activate Keybindings
4. Select the built-in binding set "Larkin"

[!WARNING] The Larkin keybindings will ask to install some additional extensions. If you choose to install these, one of them, "Rewrap" is not signed by the Marketplace Store. You may have to install this extension manually, rather than using Master Key's UI. Note however that this should not interfere with the activation and use of your keybindings, other than the commands that make use of this specific extension.

You can revert these changes later using Master Key: Deactivate Keybindings.

Discoverability Features

Visual documentation of keybindings

Learn and review your bindings on a keyboard layout:

Cheet sheet of keybindings

Review your bindings in a cheet sheet organized by theme:

Keybinding hints

See a quick pick palette of possible bindings for the current mode and prefix of keys already pressed:

The example above shows the bindings available after pressing m in the Larkin keybinding set that is included with Master Key.

Editing Features

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.

Move by Object

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)

Multi-Cursor Creation and Filtering

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:

Exchange Objects

Swap selected objects with one another:

Repeat Last Selection / Action

Avoid lengthy key sequences by repeating the last action-related selection with "," and the last action with ".":

Record Commands

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 any 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. You can copy your non-master-key bindings over to Master Key (so that they will be recorded) by customizing your bindings and using Import Default Bindings and Import User Bindings to allow all of the default and user bindings stored in VSCode's normal keybinding files to be recorded by Master Key. (You will have to remove your original user bindings from the VSCode keybinding.json file manually)

Symmetric Insert

Insert or remove appropriate characters before and after each selection:

Keybinding Features

[!WARNING] For the initial release of Master Key, the keybinding features are not yet well documented. You can review the format when copying Larkin to your own customization file (via Master Key: Edit Preset Copy). The main goal of the 0.3.0 release was to make the default keybindings accessible to new users. See the roadmap for the versions expected to include better support for creating new keybinding presets. Before those milestones, the finer points of implementing your own keybindings could require some digging into source code and/or asking questions in the discussions section of this repo. These details are also currently subject to change.

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.

Modal Bindings

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"

Parameteric Bindings

Express an entire series of bindings using the foreach field.

[[bind]]
path = "edit.count"
foreach.num = ['{key: [0-9]}']
name = "count {num}"
key = "{num}"
command = "master-key.updateCount"
args.value = "{num}"

Stateful Bindings

Update state with the master-key.captureKeys, master-key.updateCount, master-key.setFlag or master-key.storeNamed and then use this state in downstream commands using computedArgs instead of args in your keybinding.

[[bind]]
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"
computedArgs.str = "captured"
args.inclusive = false

Record and Repeat Commands

Master 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]]
key = ";"
name = "repeat motion"
repeat = "count"
command = "master-key.replayFromHistory"
args.at = "commandHistory[i].path.startsWith('edit.motion') && commandHistory[i].name != 'repeat motion'"

Documented Bindings

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 binding's names will show up in the visual documentation as appropriate.

Customized Bindings

Okay, so you want to customize your keybindings, or create a whole new preset?

You can start by reviewing the built-in Larkin preset using the command Master Key: Edit Preset Copy. A new *.toml file with the contents of this master-key binding set will be opened. The file has comments throughout which document its use.

[!WARNING] Because the error reporting for master keybinding files is not yet very precise, it is recommended that you edit bindings incrementally (e.g. by slowly creating new bindings or by slowly uncommenting an entire binding set you have imported). In this way you can ensure that the changes you've made can be properly activated by Mater Key. Long-term, better error reporting for these binding files will be available.

To simply customize an existing preset, you can append additional bindings by activating user bindings: create a new toml file and enter the bindings you want to append. Then call Master Key: Activate User Keybindings on the toml file you just created. You can import existing user bindings, from keyindings.json, by calling Master Key: Import User Keybindings.

[!NOTE] Normal VSCode user keybindings always take precedence over master keybindings. (It would be rude to have Master Key automatically insert bindings with higher priority than user specified customizations). Make sure you delete any user keybindings from your keybindings.json file after importing them into your master keybindings .toml file.

Alternatively you can define your own preset and import bindings from those you've already created in VSCode. Create a preset copy by calling Master Key: Edit Preset Copy and then you may want to call Master Key: Import Default Keybindings to add any existing bindings you have to your preset copy. Edit the bindings as desired and update your settings to use them by calling Master Key: Activate Keybindings at any time.

Roadmap

• Release 0.1.0: relatively stable default keybindings
• Release 0.1.x: improved coverage/testing/stability of existing features
• Release 0.2.0: missing visual documentation features: markdown summary of bindings
• Release 0.2.x: improved performance/coverage/stability
• Initial publish to VSCode here: 0.3.0
• 0.3.x: improved code coverage, stability improvements
• Release 0.4.x: documentation of all keybinding commands. May introduce breaking changes to improve API clarity for these bindings.
• Release 0.4.y: more precise binding error report: use VSCode language server features to get detailed line and character error indicators for binding-file problems
• Release 0.4.z: source code documentation — may involve substantial refactor to improve legibility / clarity of code
• Release 1.0.0:
  • code should be legible
  • test coverage should be satisfactory
  • documentation should be largely complete
• Release 1.x: upwards and onwards...
  • support for more keyboard layouts for visual docs
  • search: showCount displays movement count overlaid with each highlight
  • additional keybinding sets: e.g. vim, emacs
  • API improvements for new editor sets
  • keybinding debug QOL features: show the binding that was run for a given key sequence
  • clipboard registers

Related Work

Master Key follows in the footsteps of many other extensions:

• VSCodeVim
• vscode-neovim
• Awesome Emacs Keymap
• Dance
• ModalEdit
• ModalKeys

And of course, there are many existing editors that Master Key draws inspiration from:

• vim
• emacs
• kakoune
• helix

Developer Notes

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 | sh

You can then install all dependencies for this project as follows:

mise activate
mise install
npm ic