Everything MultiShortcuts Pro can do, explained.

01 · Quick Start

MultiShortcuts Pro for Mac is a free script for Hammerspoon, plus an optional rule file for Karabiner-Elements that adds the hold-for-⌘ keys. Setup takes about five minutes.

Step 1 · Install Hammerspoon

Download Hammerspoon from hammerspoon.org, open the .dmg and drag Hammerspoon into Applications. It's free and open source.

Step 2 · Grant Accessibility permission

Open Hammerspoon. macOS asks for Accessibility permission, which any keyboard tool needs to read keystrokes and type for you. Go to System Settings → Privacy & Security → Accessibility and turn Hammerspoon on.

Step 3 · Add MultiShortcuts Pro

⬇ MultiShortcutsPro.lua

In the Hammerspoon menu bar icon choose Open Config. Put MultiShortcutsPro.lua in that ~/.hammerspoon/ folder, then add this line to init.lua in the same folder (create the file if it isn't there):

require("MultiShortcutsPro")

Hammerspoon menu → Reload Config. An MSP item appears in your menu bar, and a welcome message explains the basics.

Step 4 · Turn on the hold keys (recommended)

Hold ; for ⌘ and hold Caps Lock for ⌥ use Karabiner-Elements, a free keyboard tool that handles tap-or-hold keys reliably.

1. Install Karabiner-Elements and open it once. Allow Input Monitoring and the driver extension when macOS asks.
2. Either click Add to Karabiner-Elements on the home page, or choose MSP → Set up hold keys… in the menu bar.
3. In Karabiner-Elements, open Complex Modifications → Add predefined rule and click Enable next to each MultiShortcuts Pro rule you want.

Step 5 · Try it

Open Notes. Type -= and today's date appears. Select a word, hold ; and press C: it's copied. Tap Caps Lock, then a: Claude opens.

02 · ⌘ and ⌥ on the Home Row

The modifier keys sit at the corners of the keyboard, so every copy, paste and save means a stretch. These keys put them under your fingers. Each one still types its normal character when you tap it.

Turn each one on or off

Every key is a separate rule in Karabiner-Elements → Complex Modifications: enable the ones you want, remove the ones you don't. For the mouse rule, also tick your mouse under Devices so Karabiner can see it. There's an alternative mouse rule that makes the wheel act like Caps Lock instead (click = `, hold = ⌥). Enable only one of the two mouse rules.

Fast typing stays typing

A key counts as held after 200 ms. If you press the next key before letting go of ; or ` (a fast roll while typing), it counts as typing, not holding, so you never get ⌘ or ⌥ by accident. To change the 200 ms, edit the three 200 values in a rule's parameters in Karabiner-Elements (100 to 1000 ms works well).

03 · ; Commands

Tap ;, then a letter. The ; is held back for a moment, so it never replaces your selection. If no command letter follows, ; is typed as usual. Lowercase is what you use most; the Capital is the rarer or riskier twin.

Typing normally is safe: a ; right after a letter (as in this;and) is treated as punctuation. Turn the commands off in the menu: MSP → ; Commands.

04 · Starter Mode & Full Features

New installs start in Starter mode with the built-in shortcuts only: the hold keys, the ; commands, the ` launchers and the = dates.

When you want your own shortcuts, choose MSP → Unlock Full Features…. That turns on the ⌥ hotkeys (⌥T, ⌥A, ⌥E and the rest), the editor, and adds a few sample text shortcuts. It's free; nothing to buy.

05 · The Trigger System

A trigger is the short string you type to fire a shortcut. There are two kinds.

Instant triggers

Triggers that end in a capital letter, or contain a digit or a symbol, fire the moment you type the last character.

Word triggers

All-lowercase triggers wait for you to finish the word with a space, return, tab, or . , : ? !, so they never fire inside a real word. The character you typed is kept after the expansion.

Force a word trigger to be instant

Add $$ to the end of the trigger in your shortcut file: addr$$ 1 Main St fires as soon as you type addr.

06 · Naming Convention

Good triggers are memorable, fast to type, and don't collide with real words. This convention scales to hundreds of shortcuts.

Adding new vs. editing existing

Every save writes a timestamped backup to ~/.hammerspoon/MultiShortcutsPro/backups/.

07 · Date Shortcuts

The = family is built in. Examples assume today is October 28, 2026.

Months are clamped: one month after January 31 is February 28 (or 29), not March 3. The built-ins are ordinary lines in your shortcut file, like 1-= {when:+7d}, so you can change them. If you delete one, it comes back on the next start; to replace one, give its trigger your own text.

Your own date formats

08 · App, Web & Document Launchers

Launchers live in ~/.hammerspoon/MultiShortcutsPro/launchers.txt, one per line: trigger target. With the hold keys on, tap Caps Lock to type the `.

Apps

`s Safari
`n Notes
`m Messages

Websites and links

`g https://voice.google.com
`a https://claude.ai
`mom facetime:5551234567

Documents and folders

`r ~/Documents/recipes.md
`b ~/Documents/budget.numbers
`d ~/Downloads

Mac link types

What a launcher may open

Launchers are checked when shortcuts load and every time one fires:

• Opens: apps, folders, Finder aliases, web links, documents (PDF, text, Word, Excel, Pages, Numbers, Keynote…), images, audio, video, and zip or disk-image files.
• Blocked: scripts and installers, such as .command, .sh, .scpt, .applescript, .workflow, .pkg, and programs without an extension. Also blocked: javascript:, file: and other link types not listed above.
• Asks first: Terminal, Script Editor, Automator, Shortcuts, System Settings and similar powerful tools, and any app outside your Applications folders.
• Missing target: if a file was moved or deleted, you get a clear message telling you which launcher to fix.

Built-in launchers

09 · AI Prompt Library

Keep your most-used AI prompts two keystrokes away. Works with Claude, ChatGPT, Gemini, or any AI chat in your browser or desktop app.

Typing the same instruction to an AI more than twice? Make it a shortcut: ⌥T, paste the prompt, pick a trigger.

10 · Texting from Your Mac

Shortcuts work in every texting app on your Mac: Messages (iMessage and SMS through your iPhone), Google Voice, WhatsApp, Telegram and Signal.

These samples are added when you unlock Full Features, along with qp, jg, jj, jt and jT.

11 · Placeholders & Sequences

Placeholders

Sequence macros

Press keys, wait, and switch apps inside an expansion. Modifiers: ^ = ⌘, ! = ⌥, # = ⌃, + = ⇧.

Example: sendX {key:^a}{key:^c}{focus:Messages}{wait:300}{key:^v} copies everything and pastes it into Messages. The space you type after a word trigger isn't added to a sequence.

12 · File Format & SpeedKee

MultiShortcuts Pro for Mac, MultiShortcuts Pro for Windows and SpeedKee for Android share one format:

; lines starting with "; " are comments
mP My pleasure!
addr$$ 1 Main St[NEWLINE]Chicago, IL 60601
`a https://claude.ai

• One shortcut per line: trigger expansion.
• Line breaks inside an expansion are stored as [NEWLINE].
• $$ at the end of a trigger makes it fire instantly.

Files

Edit the files in any text editor; changes load within a second. To move shortcuts between your phone and computer, use the phone ⇄ PC converter. Text shortcuts and websites transfer; app launchers, file paths, Mac-only placeholders and multi-line text don't.

13 · Privacy & Safety

• Stays on your Mac. No network calls, no telemetry, no account.
• Clipboard privacy. Long expansions are pasted instead of typed. Those clipboard writes are marked private and temporary, so clipboard managers and Universal Clipboard skip them, and your previous clipboard is put back.
• History without text. Expansion history keeps only shortcut names and character counts.
• Safe launchers. See section 08 for what opens, what's blocked and what asks first.
• Undo can't eat your writing. ⌥Z only works right after an expansion, before you type or click anywhere else.

14 · Troubleshooting & Hotkeys

Holding ; types semicolons instead of acting as ⌘

The hold keys come from Karabiner-Elements. Check that it's running, that Input Monitoring is allowed for it, and that the MultiShortcuts Pro rules are enabled under Complex Modifications.

Caps Lock then a letter does nothing

Make sure the Caps Lock rule is enabled and that `a is in your launchers (⌥L). Try both slowly and fast: either way should open Claude.

I can't grant Accessibility permission (work Mac)

Adding an app to Accessibility needs an administrator. Ask IT, or use the built-in alternatives on the Locked-down Mac page, including a converter that moves your text shortcuts into Text Replacements.

Gatekeeper warning when opening Hammerspoon

Right-click Hammerspoon in Applications → Open → Open. After that it opens normally.

Accessibility permission keeps getting revoked

After a Hammerspoon update, remove it from System Settings → Privacy & Security → Accessibility and add it again.

Shortcuts don't fire in one app

Some games, virtual machines and remote-desktop apps capture the keyboard below where Hammerspoon can see it. That's by design.

Hotkeys

In Starter mode only ⌥Q, ⌥Z, ⌥P, ⌥R and ⌥H are active.