Multi-letter shortcuts for macOS.
Chord lets you bind actions to key sequences while keeping your existing shortcuts untouched.
- Download
Chord-aarch64.dmg(Apple silicon) orChord-x86_64.dmg(Intel) from the latest release. Both are signed and notarized. - Open the DMG, drag Chord into
Applications, and open it.
Chord then starts a short guided setup: it asks for the permission it needs, helps you make your first chord, and has you practice using it. The rest of this readme is reference for what you learn there. To see the guide again, open Settings → General → Getting Started.
Chord requires macOS Accessibility Permissions (called Device Control and Data Access on macOS 27) so it can detect when you press ⇪ (Caps Lock) + ␣ (Space) to activate Chord Mode.
Once you enter Chord Mode, it stays active as long as ␣ is held down.
_Only ␣ needs to stay pressed; you should release ⇪ after pressing ␣
In Chord Mode, any keys you type will be intercepted by Chord as input. These key events won't be passed to the focused application.
While Chord Mode is active, the Hint Panel shows what you've typed and which keys can come next. Press Tab to hide it, and again to show it. To start with it hidden, turn on Hide Hint Panel by default in Chord's settings (General → Application).
Chords can only be triggered in Chord Mode, so make sure to keep ␣ held down!
To trigger a chord, type out the chord's letters and then press ⇪.
For example, typing 0,⇪ opens Chord's settings window.
Once you're done, you can release ␣ to exit Chord Mode.
For sending one-off chords, you can release ␣ right after typing out the chord to execute it.
For example, instead of pressing ⇪, you can also type 0, and then release ␣ to bring up Chord's settings.
Are you a vim user?
For vim users, it might help to treat Chord Mode as somewhat analagous to vim's Normal Mode, with the main difference that it's a lot easier to exit: just lift up ␣!
All chords are defined in configuration files called chord files.
A chord file contains chords for a single application and platform, which is determined by its path.
A chord file for macOS Finder would live at:
chords/com/apple/Finder/macos.toml
Why do chord files end in .toml?
Chord files are written with a standardized configuration format called TOML.
You likely don't need to spend time learning it, as TOML is quite simple and intuitive.
All chord files live under a top-level chords/ folder, which itself is part of a chord package that contains both chord files and scripts the chords might use.
Your default chord package is located in ~/.chord/packages/default.
By adding chord files to this package, you can create your own chords!
If you create the following file in your chord package:
chords/com/apple/Finder/macos.toml
And paste in the following:
name = "Finder"
[chords]
# Always use single quotes when defining a chord's key sequence
'gh' = {
# The `name` property is a required label for the chord
name = 'Goto: Home',
# The `shortcut` property tells Chord to simulate a shortcut when this chord is triggered
shortcut = 'cmd+shift+h'
} # end of `gh` properties
# A chord that starts with a non-letter is a global chord and can be triggered from any application
'/f' = {
name = 'Finder',
# The `shell` property tells Chord to run a shell command (in the background) when this chord is triggered
shell = 'open -a Finder'
}Note that anything after a
#in chord files is a comment used purely for documentation and is ignored by the configuration file.
You'll then be able to type:
- /f⇪ to open Finder,
- gh⇪ to open your home directory!
Instead of defining your own chords for every app, Chord provides pre-made chord packages you can use!
Chord's compiled chords contain certain conventions:
- Navigation: nesw (north, east, south, west)
- Movement: lrud (left, right, up, down)
- Position & Order: fkaz (front, back, first, last)
For a full list of these conventions, see the KeyChords/chords repo!
Open Browse in Chord's settings and choose Install for an official package. Official packages are loaded through ~/.chord/packages/@keychord/.
WARNING: Since Chord scripts can run arbitrary code (necessary for macOS scripting), you should ONLY install chord packages from people you trust or after auditing code.
To install a third-party package, first manually download and extract it into a ~/.chord/packages/<name> folder.
Then, you need to quit and restart Chord, and manually approve it in the Chords tab.
In Chords → Packages → Third-Party Packages, choose Review & Approve…, review the package path and warning, then choose Approve and Enable. Until you approve it, Chord does not enable any of its chords or load its handlers. Approval persists across restarts; use Revoke Approval under Approved packages to disable it again.
Official packages live under ~/.chord/packages/@keychord/ and do not require this approval. Every package outside that folder is untrusted by default, even if its package.json claims an @keychord name. Chord approves personal packages when you create them through My Chords; existing folders require approval.
In addition to simulating shortcuts and executing shell commands, chords can also run scripts!
This is useful for apps that have configurable shortcuts, in which case, you can't just simulate the default ones.
For example, here's what a chord file for IntelliJ might look like:
# chords/com/jetbrains/intellij/macos.toml
name = "IntelliJ IDEA"
[on.action]
file = "jetbrains.js"
[chords]
'fh' = { name = "File: Here", '@input:action' = ['NewFile'] }Where jetbrains.js refers to this file located at js/jetbrains.js:
// `mkdtempDisposable` makes a temporary directory that's automatically cleaned up
import { mkdtempDisposable } from "node:fs/promises";
/**
* Every script should have a top-level "builder" function as its
* default export. The builder returns the event handler function.
*/
export default function actionBuilder() {
// Any code here runs only once: when the chord file is first loaded
const ideaPath = "/Applications/IntelliJ IDEA.app/Contents/MacOS/idea"
/**
* The event handler function gets called every time the chord is triggered.
* The arguments come from the `array` assigned to the '@<event>:<handler>' property
* specified in the TOML chord file.
*
* For example, if the chord file had:
*
* 'fh' = {
* # ...
* '@input:action' = ['NewFile']
* }
*
* Then Chord would call `action("NewFile")`.
*/
return async function action(actionId) {
// We create a temporary directory to avoid conflicting with future/past calls
await using dir = await mkdtempDisposable(`/tmp/jetbrains-`)
// The following Groovy script runs the action `actionId` in IntelliJ
const scriptPath = `${dir.path}/action.groovy`;
await Bun.write(scriptPath, `
import com.intellij.openapi.actionSystem.ActionManager
IDE.application.invokeAndWait {
def m = ActionManager.instance
def a = m.getAction("${actionId}")
if (a) m.tryToExecute(a, null, null, null, true)
}
`);
// We use `Bun.$` to run the above code with the IntelliJ CLI
await Bun.$`${ideaPath} ideScript ${scriptPath}`.quiet();
};
}Using this script, we can define chords for IntelliJ-based IDEs that work regardless of what the user's existing IDE shortcuts are!