HyprMac guides

Install HyprMac on macOS

HyprMac is free and MIT licensed. You need macOS 13 Ventura or later, and you need to let it control your windows through Accessibility. You do not need to turn off System Integrity Protection, and you do not need a kernel extension or a scripting add-on.

1. Install the app

If you use Homebrew, this is the whole install:

brew trust --cask zacharytgray/hyprmac/hyprmac && brew install --cask zacharytgray/hyprmac/hyprmac

Otherwise, download the DMG from the releases page, open it, and drag HyprMac into Applications. The builds are signed with a Developer ID and notarized by Apple, so the first launch is an ordinary double click. The releases page is also where the changelog for each version lives.

2. Allow Accessibility

Open HyprMac from Applications. It will ask for Accessibility, which is how it reads window frames and moves windows around. Grant it in System Settings, under Privacy & Security, then Accessibility. Nothing tiles until that switch is on.

3. Pick your Hypr key

Hypr is the one modifier every shortcut starts with. Caps Lock is the default. Leave Caps Lock assigned to “Caps Lock” in Keyboard, then Modifier Keys: if you set it to “No Action”, macOS stops sending the event and HyprMac never sees your shortcuts. If you would rather keep Caps Lock as Caps Lock, you can choose another key in Settings, under Keys: backslash, F13 through F20, or Option or Command on either side. Shift and Control are not offered, because many shortcuts add them to Hypr, and neither are Tab and backtick, because default shortcuts already use them.

4. Learn five shortcuts

The first run walks you through a short tutorial, and these five carry most of the work. Hypr and an arrow key moves focus to the window that way. Hypr and a number, 1 through 9 or 0 for ten, switches workspace. Hypr and T floats the focused window and tiles it again. Hypr and K opens the searchable list of every binding you have. Hypr and P pauses tiling and turns it back on, which is the shortcut to remember when something looks wrong and you want your windows left alone for a minute.

The rest of the defaults are in the keyboard shortcut reference, and you can try the whole workflow in the browser demo before you commit to it.

Settings, and where your config lives

The Settings window has three tabs: General, Keys, and Layout, with a live preview of gaps, padding, and corner radius. Every binding is editable with a key recorder, and you can add your own bindings that launch an app or run a command. General is where you name workspaces and pin apps to a workspace or to the scratchpad, and Layout is where you choose which workspaces live on which monitor and set padding per monitor. Under the hood it is JSON at ~/Library/Application Support/HyprMac/config.json, which you can hand edit, and there is an optional iCloud sync if you run more than one Mac. There is also a per-app list of windows that should never be tiled.

Two integrations are off until you turn them on. “Allow other apps to control HyprMac”, in General, lets tools like Raycast, BetterTouchTool and Karabiner run any HyprMac action by opening a hyprmac://action/ link. A status bar export for bars like sketchybar writes the workspace state to a file and runs a command on every change; it is turned on by hand in monitor-config.json. The HyprMac docs cover control from other apps and status bars.

Updates and help

HyprMac updates itself: use “Check for updates…” from the menu bar item, or run brew upgrade --cask hyprmac if you installed it that way. Upgrades keep the shortcuts you customized; when a default chord moves, only the untouched old default is migrated.

If something misbehaves, the useful bug report says which macOS version you are on, which HyprMac version, how your displays are arranged, and the steps that triggered it. Open an issue on GitHub, and the source is right there too.