Skip to content
KeyChordPublic

About

Multi-letter shortcuts for macOS.

Resources

Stars

27 stars

Watchers

1 watching

Forks

Repository files navigation

Chord

Multi-letter shortcuts for macOS.

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

Installation

  1. Download Chord-aarch64.dmg (Apple silicon) or Chord-x86_64.dmg (Intel) from the latest release. Both are signed and notarized.
  2. 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.

Setup

Permissions

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.

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).

Triggering a Chord

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

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 ␣!

Configuration

Chord Files

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

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.

Chord Packages

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

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 Packages

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 Packages

Open Browse in Chord's settings and choose Install for an official package. Official packages are loaded through ~/.chord/packages/@keychord/.

Installing Third-Party Chord Packages

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.

Chord Scripts

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 IDEA

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!

About

Multi-letter shortcuts for macOS.

Resources

Stars

27 stars

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages