Multi-letter shortcuts for macOS.
Chord lets you bind actions to key sequences while keeping your existing shortcuts untouched.
Chords are sequences of non-modifier keys that correspond to actions. Most of the time, these actions are defined as existing keyboard shortcuts in an application.
For example, here are some example chords for the macOS Finder app:
# chords/com/apple/finder/macos.toml
gd = { name = "Goto Downloads", shortcut = "opt+cmd+l" }
du = { name = "Directory Up", shortcut = "cmd+up" }
tt = { name = "Toggle Tabs", shortcut = "cmd+shift+t" }
ts = { name = "Toggle Sidebar", shortcut = "ctrl+cmd+s" }
tp = { name = "Toggle Preview", shortcut = "cmd+shift+p" }
nds = { name = "New Directory with Selection", shortcut = "ctrl+cmd+n" }Because chords are only composed of letters and/or numbers, they are often easier to remember than their modifier + key counterparts.
In order to run a chord, you need to have the Chord app installed and running in the background. Chord won't do anything until you press the activation sequence to activate Chord Mode, which defaults to Caps Lock + Space.
Why Caps Lock + Space?
An ideal requirement for typing chords is to have all your fingers free to type arbitrary chord sequences while a certain key is held down. One of the only keys that fit this requirement is the Space key.
However, Space needs to be pressed as part of a key combination, since pressing it alone will output the actual space character. The key which makes the most sense as part of this combination is Caps Lock, since it's one of the easiest keys to reach yet still remains relatively unused on most layouts.
Because we only use it as part of a key combination, pressing Caps Lock on its own will still toggle on Caps as usual, and this special behavior only applies when Space is pressed down while Caps Lock is pressed.
After pressing the Space key, the chords panel will appear on the left, which displays the valid chords for the focused application.
In addition to app-specific chords, you're also able to define global chords (which can be triggered from any app) by starting the key sequence with a symbol instead of a letter:
# chords/macos.toml
"/q" = { name = "Force Quit", command = "Force Quit", shortcut = "cmd+opt+esc" }After typing out all the chord letters, you can simply release Space to trigger it and exit Chord Mode.
If you want to trigger a chord without exiting Chord Mode, you can press Caps Lock which will trigger and clear your input. You'll remain in Chord Mode as long as Space is still held down.
Why `Caps Lock`?
Caps Lock is a key that's significantly more comfortable to press after many chord sequences, especially ones containing symbols. To try it yourself, compare pressing [o followed by Caps Lock, and then compare it to pressing Enter afterwards.
You can run a chord multiple times by pressing Caps Lock again. Pressing the following sequence of keys in Chord Mode goes up three folders in Finder:
du⇪⇪⇪
- Tap(D)
- Tap(U)
- Tap(Caps)
- Tap(Caps)
- Tap(Caps)
If you're triggering a sequence of chords that share the same prefix, you can hold Shift while pressing the last key of the chord:
/F
- Tap(Slash)
- Press(Shift)
- Tap(F)
- Release(Shift)
This will execute the chord with that sequence (lowercased, since all chords must be lowercase) without adding appending the key to your existing sequence.
As an example, say you wanted to quickly toggle the tabs view, the sidebar view, and the preview in Finder. Instead of typing out the entirety of three separate chords:
tt⇪ts⇪tp⇪
- Tap(T)
- Tap(T)
- Tap(Caps)
- Tap(T)
- Tap(S)
- Tap(Caps)
- Tap(T)
- Tap(P)
- Tap(Caps)
You can just type T once and keep Shift held down for the other three keys:
tTSP
- Tap(T)
- Press(Shift)
- Tap(T)
- Tap(S)
- Tap(P)
- Release(Shift)
In addition, because chords don't use modifier keys, you're able to use any existing shortcuts while Chord Mode is active. The following sequence of keys will move all the contents of your Downloads folder into a new folder:
/FgD⌘ands⇪
- Tap(Slash)
- Press(Shift)
- Tap(F)
- Release(Shift)
- Tap(G)
- Press(Shift)
- Tap(D)
- Release(Shift)
- Press(Command)
- Tap(A)
- Release(Command)
- Tap(N)
- Tap(D)
- Tap(S)
- Tap(CapsLock)
Pressing Backspace will delete the last key in your current sequence. Pressing Shift+Backspace will clear the entire sequence.
Actions can also take the form of shell commands, which is useful when certain functionality isn't available via a keyboard shortcut:
"/f" = { name = "Finder", command = "Finder", shell = "open -a Finder" }Chords ignores all inputs whenever a modifier key (other than Shift) is held down.
To exit Chord Mode, all you need to do is simply release your Space key. It's that simple!
In addition to running shortcuts and shell commands, chords can also run arbitrary JavaScript scripts, which provides more power for certain use-cases, especially for apps that don't necessarily have shortcuts bound to every action.
# chords/com/microsoft/VSCode/macos.toml
[js]
default = "dist/vscode.runtime.js"
menu = "dist/menu.runtime.js"
[chords]
# `explorer.newFile` doesn't have a default shortcut in VSCode
fh = { name = "File: Here", 'js:default' = [ "explorer.newFile" ] }
# `js:menu` calls the named `menu` target instead of `default`
mc = { name = "Menu: Columns", 'js:menu' = [
"View",
"Columns"
] }
# String JS invocations are evaluated as JavaScript and must return an array
df = { name = "Dynamic File", 'js:default' = '["explorer.newFile", Date.now().toString()]' }
# ...The top-level js table maps invocation targets to JavaScript filenames. Chords must reference those targets with js:<name>, most commonly js:default.
js:<name> accepts either a TOML array of literal values or a raw JavaScript string. When you use the string form, Chords evaluates it in the embedded JS runtime and expects the result to be an array, which is then spread into the target function call.
Chord embeds the LLRT runtime, a QuickJS-based JavaScript environment which provides partial compatibility with the Node.js APIs. For more information, see scripting.md.
Many macOS apps can only be activated through a global hotkey. We thus use a synthetic hotkey pool:
cmd+ctrl+alt+shift+{a-z}cmd+ctrl+alt+shift+{0..9}cmd+ctrl+alt+shift+f{1..12}cmd+ctrl+alt+f{1..12}
While Chord Mode defaults to app-shortcuts, you can press Tab right after (Caps+Space+Tab) to toggle "Web Mode", which activates chords that apply to the currently focused webpage.
In Web Mode, whenever keys are typed in the browser, they will default to chord sequences instead of input.
To type regular input in Web Mode (e.g. opening a new tab), you should hold Shift while typing it out and press Caps to run it (obviously, the Shift shortcut isn't available in Web Mode).
To exit Web Mode and re-enter Chord Mode, press Esc.
One of Chord's most powerful features is the ability to "buffer" chords: if you press another chord before the current one is finished executing, Chord will queue it instead of triggering it immediately.
Because keyboard shortcuts must be composed of one or more modifier keys followed by a single character, they come with inherent limitations:
Because there are only a limited amount of modifier+key combinations available, many shortcuts don't intuitively map to their action:
# chords/com/microsoft/VSCode/macos.toml
gf = {
name = "Go to File",
# cmd+p doesn't make you think of "File" (my best guess is that cmd+f is already taken by Find, and so it's adapted from the shortcut for the similar feature Command Palette which is cmd+shift+p (p for palette)
# Either way, "gf" for "goto file" is a lot easier to remember
shortcut = "cmd+p"
}
gd = {
name = "Go to Definition",
# Some shortcuts don't even use letters at all...
shortcut = "F12"
}The same app on different platforms (Windows/Linux/MacOS) often use different shortcuts or modifiers for the same action, which can be a pain to deal with if you need to switch between platforms.
Chord can act as an abstraction over these shortcut differences by letting you map the same chord to different shortcuts on each platform.
Different apps will often have different keybindings for similar actions. While you are able to set custom keymaps in certain apps, they make it harder to follow along with documentation (which often assume the default keymap) and require you to create and maintain your own keybindings files if you ever want to make changes.
With chords, you can define the same chord across multiple apps which map to the corresponding shortcut for that app. This way, you can just remember one chord for an action and it'll work across all your apps without you having to memorize the specific shortcuts for each app:
# chords/com/microsoft/VSCode/macos.toml
gd = { name = "Go to definition", shortcut = "f12" }
rs = { name = "Rename Symbol", shortcut = "f2" }
rf = { name = "Recent Files", shortcut = "cmd+e" }
cp = { name = "Command Palette", shortcut = "cmd+shift+p" }
fc = { name = "Format Code", shortcut = "shift+alt+f" }# chords/com/jetbrains/intellij/macos.toml
gd = { name = "Go to definition", shortcut = "cmd+b" }
rs = { name = "Rename Symbol", shortcut = "shift+f6" }
rf = { name = "Recent Files", shortcut = "ctrl+tab" }
cp = { name = "Command Palette", shortcut = "cmd+shift+a" }
fc = { name = "Format Code", shortcut = "cmd+option+l" }ss = { name = "Sort by Size", shortcut = "cmd+opt+cmd+6" }