ChordCopy Anchor Link

Multi-letter shortcuts for macOS.

Chord lets you bind actions to key sequences while keeping your existing shortcuts untouched.

InstallationCopy Anchor Link

1. Download Chord-aarch64.dmg from the latest release. It is signed and notarized.
2. Open the DMG, drag Chord into Applications, and launch it.

SetupCopy Anchor Link

PermissionsCopy Anchor Link

Chord requires macOS Accessibility Permissions so it can detect when you press ⇪ (Caps Lock) + ␣ (Space) to activate Chord Mode.

Chord ModeCopy Anchor Link

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.

Triggering a ChordCopy Anchor Link

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.

Auto-triggerCopy Anchor Link

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.

ConfigurationCopy Anchor Link

Chord FilesCopy Anchor Link

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.

Chord File Example - FinderCopy Anchor Link

A chord file for macOS Finder would live at:
chords/com/apple/Finder/macos.toml

Chord PackagesCopy Anchor Link

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!

Chord Package Example - FinderCopy Anchor Link

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:

1. /f⇪ to open Finder,
2. gh⇪ to open your home directory!

Pre-Made Chord PackagesCopy Anchor Link

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!

Installing Chord PackagesCopy Anchor Link

TODO

Chord ScriptsCopy Anchor Link

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.

Chord Scripts Example - IntelliJ IDEACopy Anchor Link

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!