Rectangle Is Not Working: The Complete Diagnostic Order

Step 0: define the failure precisely

"Rectangle is not working" describes at least six unrelated faults, and the fix for one is useless for the others. Before changing anything, place your symptom in this table. The rest of this guide is organised around it.

Step 1: confirm the process is actually alive

This sounds too obvious to check and it is the single most common cause. The app has no Dock icon and no window; if it quit, or never launched after a restart, the failure is indistinguishable from a total malfunction. Look for the icon in the menu bar.

If it is missing, check whether the menu bar is simply full. On a MacBook with a notch, menu bar items are silently truncated when there is not enough room between the notch and the app menus, and the icon can be present but unrenderable. Quit a few other menu bar utilities, or install a menu bar manager, and see whether it reappears.

# is the process running?
pgrep -lf Rectangle

# start it without touching the Dock
open -a Rectangle

# check the login item is registered
osascript -e 'tell application "System Events" to get the name of every login item'

If it disappears after every restart, the launch-at-login setting is off, or macOS revoked it. Set it inside the app's own settings rather than only in System Settings → General → Login Items; after a migration or a restore from backup the two can disagree.

Step 2: Accessibility permission, and why the toggle lies

macOS will not let one application move another application's windows without Accessibility permission. This is not negotiable and there is no narrower permission to grant. Everything else in this guide is downstream of it.

Here is the part that wastes people's weekends: the toggle can be on while the permission is not actually working. macOS stores these grants in a database keyed to the application's code signature and path. When the app updates, or is moved, or the system is upgraded, the stored record can end up pointing at something that no longer matches. The interface still draws a switch in the on position because a row exists; the check that matters fails silently.

The fix is not to toggle it off and on. It is to delete the row and let the app request it again, in this exact order:

1. Quit the app completely from its menu bar menu — not just close a window.
2. In System Settings → Privacy & Security → Accessibility, switch the toggle off first, then select the row and remove it with the minus button. Doing it in that order matters; removing an enabled entry can leave a stale grant behind.
3. Restart the Mac. This is genuinely required — the permission daemon caches.
4. Launch the app and grant permission when prompted, rather than pre-adding it with the plus button.

If you prefer the terminal, the equivalent is a single command that resets the app's entry in the privacy database, after which the app must be relaunched and will ask again:

Step 3: is the hotkey even arriving?

With logging open, press a failing shortcut. Nothing printed means the keystroke never reached the app. Two things intercept keystrokes before a background utility sees them: the frontmost application, and another global hotkey registered earlier.

Test by pressing the same shortcut with the Finder in front. If it works in Finder but not in your editor, the editor is capturing it. If it fails everywhere, another background utility owns it. The usual suspects are launchers with their own window commands, keyboard remappers, screenshot tools, screen recorders, remote desktop clients that forward every keystroke to the remote machine, and virtual desktop utilities.

There is a dedicated guide for tracking these down, but the fast test is to quit suspects one at a time with the log window open, pressing the shortcut after each quit. The moment a log line appears, the last app you quit was the culprit.

Step 4: the frontmost application may be the problem

If the menu bar menu shows its movement items greyed out, the app cannot read the frontmost window at all. That is not a fault in the window manager — it means the application in front is not answering the accessibility API.

This is most common with Electron applications, Microsoft Office, Java-based tools and cross-platform frameworks that draw their own window chrome. It is usually transient and clears when the offending application is restarted. If it is greyed out no matter which app is in front, the cause is the permission problem in step 2 rather than the app.

Step 5: two window managers, one keyboard

Running two window managers simultaneously produces exactly the symptom people report as "it randomly stops working": whichever registered a given hotkey first wins, and which one that is can change between reboots. Modern launchers ship window commands of their own, so this happens to people who never deliberately installed a second manager.

Decide on one owner for window shortcuts and disable the window features in everything else. Native macOS tiling is a partial exception — it coexists, but its drag-to-edge gestures overlap with snap areas, which is covered in the snap areas guide.

Step 6: separate the system from your configuration

If you have reached this point, the question worth answering is whether the fault lives in your user account or in the system. Create a new macOS user account, log into it, install nothing else, and test. If it works there, the problem is something in your own login session — another utility, a corrupted preference, a login item. If it fails there too, the problem is system-level.

This single test saves more time than any other and is the one people skip because it feels like a lot of effort. It is ten minutes and it eliminates half of the possibility space.

Step 7: reinstall, but in the correct order

Reinstalling first is the mistake that makes this loop forever. A fresh copy inherits the same broken privacy record, the symptom persists, and reinstalling gets wrongly ruled out. Do it in this order:

# 1. stop it
killall Rectangle

# 2. remove the privacy grant
tccutil reset Accessibility com.knollsoft.Rectangle

# 3. remove preferences (optional — this discards your shortcuts)
defaults delete com.knollsoft.Rectangle
rm -f ~/Library/Preferences/com.knollsoft.Rectangle.plist

# 4. remove the app
rm -rf /Applications/Rectangle.app

# 5. reboot, then install fresh and grant permission when prompted

Install the current build from the official site or with Homebrew. If you use Homebrew and have had settings-persistence trouble before, reinstall with the zap flag so no stale preference files survive:

brew uninstall --zap rectangle
brew install --cask rectangle

Step 8: when it is genuinely a bug

If a fresh account on a fresh install still fails, you have found something worth reporting. A useful report contains the macOS version including build number, the app version and build, the exact reproduction steps, and the contents of the log window while reproducing. Reports without logs are usually unactionable.

Check the issue tracker before filing — regressions tied to a specific macOS point release are often already open, frequently with a workaround in the thread that has not made it into any documentation.

Questions