mac-hotkeys

A small background agent for macOS with three hotkeys. No Dock icon, no menu bar item, no settings.

Built for my own use and shared as is. It works on my machine; it may need changes on yours.

• Cmd+Tab: a window switcher. Shows every window with a preview, including ones in fullscreen Spaces, and goes straight to the one you pick. Replaces the built-in Cmd+Tab.
• Cmd+`: cycles the front app's windows, including fullscreen ones, which the built-in version skips.
• The moon key (shared with F6): tap and hold each run a Shortcut of your choice.

Using the switcher

Hold Cmd and press Tab. Each fullscreen window gets a tile, and each desktop gets one tile with an icon per app. While holding Cmd: Tab and Shift+Tab move, 1 to 9 jump to a tile, the arrow keys pick an app within a desktop, Esc cancels, and the mouse works too. Let go of Cmd to switch.

Install

Needs macOS 14 or later and the Xcode Command Line Tools (xcode-select --install). No other dependencies.

git clone https://github.com/halvis82/mac-hotkeys.git
cd mac-hotkeys
./install.sh

It starts at every login from then on. Run ./install.sh again after changing anything, and ./uninstall.sh to remove it.

Then grant it, in System Settings > Privacy & Security:

• Accessibility: required.
• Screen Recording: for the switcher's previews.
• Full Disk Access: optional, lets the moon key see which Focus is on even when it was changed elsewhere, such as from Control Center.

Keeping permissions across rebuilds

macOS ties permissions to the app's signature, and without a signing certificate every rebuild counts as a new app that needs granting again. To avoid that, create a self-signed certificate once:

openssl req -x509 -newkey rsa:2048 -keyout /tmp/k.pem -out /tmp/c.cer -days 3650 -nodes \
  -subj "/CN=Local Codesign" -addext "basicConstraints=critical,CA:false" \
  -addext "keyUsage=critical,digitalSignature" -addext "extendedKeyUsage=critical,codeSigning"
openssl pkcs12 -export -out /tmp/id.p12 -inkey /tmp/k.pem -in /tmp/c.cer \
  -passout pass:tmp -legacy -macalg sha1 -name "Local Codesign"
security import /tmp/id.p12 -k ~/Library/Keychains/login.keychain-db -P tmp -T /usr/bin/codesign -A
security add-trusted-cert -r trustRoot -p codeSign -k ~/Library/Keychains/login.keychain-db /tmp/c.cer
rm /tmp/k.pem /tmp/c.cer /tmp/id.p12

Setting up the moon key

The moon key turns Focus modes on and off through three shortcuts you make in the Shortcuts app, each with a single Set Focus action:

Shortcut	What it should do	Runs when
Moon Key Tap	turn a Focus mode on, e.g. Do Not Disturb	tapped, with no Focus on
Moon Key Hold	turn another Focus mode on	held, unless that mode is already on
Moon Key Off	turn Focus off, not tied to one mode, so it clears whichever is on	tapped with any Focus on, or held with the hold mode on

To use shortcuts you already have, put their names in ~/.config/mac-hotkeys/moon-key.json:

{ "tap": "My DND on", "hold": "My Work on", "off": "My Focus off" }

It works this way because macOS only lets apps change Focus through Shortcuts. Until all three exist, the moon key works as normal.

More

• tail -f ~/Library/Logs/com.halvor.machotkeys.log shows what it is doing, including how long each Cmd+Tab took.
• ./test.sh runs the tests. See NOTES.md for the other test modes and how it all works.
• It relies on private macOS APIs, so a macOS update can break parts of it.

MIT licensed.