Hotkey

A free, open-source text expander for macOS.
Lightweight alternative to TextExpander.

Install • Usage • Migrate from TextExpander • Build

---

Hotkey is a native macOS menu bar app that expands text abbreviations as you type — anywhere on your system. Define shortcuts like ;email → you@example.com or ;sig → your full email signature, and Hotkey replaces them instantly.

No account required. No subscription. Just a single JSON file with your snippets.

Install

1. Download Hotkey.dmg from the latest Release
2. Open the .dmg and drag Hotkey into Applications
3. Launch Hotkey from Applications

On first launch, macOS will ask you to grant Accessibility permission:

1. Open System Settings > Privacy & Security > Accessibility
2. Click + and add Hotkey.app
3. Restart the app

Optional: Launch at Login

osascript -e 'tell application "System Events" to make login item at end with properties {path:"/Applications/Hotkey.app", hidden:false}'

Usage

Hotkey lives in your menu bar with a keyboard icon. It monitors your keystrokes and expands abbreviations from your snippets.json file.

Snippets File

Hotkey looks for snippets.json in this order:

1. ~/.config/hotkey/snippets.json (recommended)
2. Next to the .app bundle
3. Current working directory

The format is a flat JSON object — abbreviation keys mapped to expansion values:

{
  ";email": "you@example.com",
  ";addr": "123 Main St\nSpringfield, IL 62701",
  ";sig": "Best regards,\nJane Doe\nCEO, Acme Corp",
  ":shrug:": "\\_(ツ)_/",
  ";date": "2024-01-15"
}

Edit the file with any text editor. Hotkey watches for changes and reloads automatically — no restart needed.

Menu Bar Options

Action	Shortcut
Pause / Resume	P
Reload Snippets	R
Edit Snippets (opens in default editor)	E
Quit	Q

Tips

• Use a prefix like ; or : for your abbreviations to avoid accidental expansions
• Longest match wins — if you have both ;addr and ;addressb2, the longer one takes priority when both match
• Multi-line text works — use \n in your JSON values
• Clipboard is preserved — Hotkey saves and restores your clipboard during expansions

Migrating from TextExpander

If you have an existing TextExpander installation, the included extract_snippets.py script can pull your snippets directly from TextExpander's local database:

python3 extract_snippets.py

This reads from TextExpander's WebKit IndexedDB storage and outputs a snippets.json file you can use directly with Hotkey.

Building from Source

Requires macOS 13+ and Xcode Command Line Tools (xcode-select --install).

git clone https://github.com/kevinyun/hotkey.git
cd hotkey
./build.sh
open Hotkey.app

The build script compiles a single Swift file into a native .app bundle — no Xcode project needed.

To create a distributable .dmg:

./create_dmg.sh

How It Works

Hotkey uses a low-level CGEvent tap to monitor keystrokes system-wide. When it detects a typed abbreviation, it:

1. Deletes the abbreviation with simulated backspace keys
2. Saves your current clipboard
3. Pastes the expanded text via Cmd+V
4. Restores your clipboard

The entire app is a single 300-line Swift file with no dependencies beyond Cocoa and Carbon.

License

MIT