# AutoRaise: focus-follows-mouse for macOS, and how to install it > AutoRaise raises and focuses the window under your cursor on macOS, with a delay you choose. It is a command-line binary plus a menu bar app, and it is not a window manager. **sbmpost/AutoRaise** — AutoRaise (and focus) a window when hovering over it with the mouse - Repository: https://github.com/sbmpost/AutoRaise - Stars: 2,806 · Forks: 125 - Language: Objective-C++ - License: GPL-3.0 - Published: 2026-09-28 · Updated: 2026-09-28 · Language: en - Canonical page: https://hysenlabs.com/projects/sbmpost-autoraise ## What AutoRaise actually changes about macOS window behaviour macOS has no built-in focus-follows-mouse. Clicking a window is what raises it and gives it keyboard focus. AutoRaise changes that: when the pointer hovers a window, the window is raised to the front and receives focus after a delay you configure. The README describes the delay as being of your choosing, and the command line exposes it as -delay, measured in units of pollMillis. The scope is narrow and worth stating plainly. AutoRaise works on windows. Panes drawn inside a single window, such as tmux or iTerm splits, are not windows as far as macOS is concerned, so they cannot be focused separately. If your workflow is entirely inside one terminal window, AutoRaise does nothing for you. The project is split in two. The repository holds AutoRaise itself, the part that raises and focuses, with all the command line options. The menu bar app with its preferences window lives in a separate project, AutoRaise-UI. Anything about the interface belongs there; anything about raising and focusing belongs here. That split matters when you go looking for a setting and cannot find it in this repository. ## How the polling loop, delay and warp options fit together The mechanism is polling, not event subscription. AutoRaise checks the mouse position at an interval set by -pollMillis. The README states the minimum is 20 and the default is 50. Lower values increase responsiveness and also CPU load; that trade-off is stated in the README, not discovered by benchmark. The -delay parameter is expressed in units of pollMillis, not in milliseconds. A delay above 1 requires the mouse to stop for a moment before raising, and a delay of 0 disables raising. There is a separate -focusDelay for the focus step, but the README notes it is only supported when the binary is compiled with the EXPERIMENTAL_FOCUS_FIRST flag, so on a default build that flag is inert. Warping is the second behaviour. -warpX and -warpY are factors between 0 and 1 that make the mouse jump to the activated window, and both are disabled by default. -scale enlarges the mouse briefly after warping, default 2.0, with 1.0 disabling it. -warpOnlyAcrossScreens limits warping to the case where the activated window sits on a different screen than the mouse. The rest of the flags exist to suppress raising in situations where it would be annoying: -requireMouseStop (default true), -requireMultipleScreens, -requireScreenChange, -ignoreSpaceChanged, -ignoreApps, -ignoreTitles, -stayFocusedBundleIds and -disableKey. The last one defaults to control, so holding control temporarily disables AutoRaise. -ignoreTitles accepts ICU regular expressions, which is the most precise suppression tool in the set. ## Installing AutoRaise on macOS from the release DMG The README gives a numbered quick start. Download the latest release, double click the downloaded file in Finder to unpack it, open the unpacked folder and double click AutoRaise.dmg, single click AutoRaise under Locations in Finder, drag AutoRaise.app into the Applications folder, then open it from Applications. Left click the balloon icon in the menu bar to grant permissions under System/Accessibility; right click the same icon to set preferences. The README flags one failure mode at this step. If you see an older AutoRaise item with a balloon icon already in the Accessibility pane, remove it completely with the minus button first. Then stop and start AutoRaise by left clicking the balloon icon, so the item reappears and you can enable it properly. Skipping that cleanup is how people end up with a permission that looks granted and does nothing. If you prefer to build from source, the README points at the master branch archive and gives this sequence, which unzips into your home directory, cleans, builds and installs into /Applications: ## A first real run: the two binaries and the config file Building produces two artifacts. AutoRaise is the command line version and accepts parameters. AutoRaise.app is the GUI-less background version, relies on a configuration file, and per the README can only be stopped via Activity Monitor or the AppleScript near the bottom of the README. The README gives this invocation as the command line example, showing the full flag surface in one line: ## Advanced compilation flags and the private API they depend on Three compile-time flags change behaviour, and two of them are the reason to think before building. The README gives this example command: ## AutoRaise limitations, and when it is the wrong tool The most concrete limit is the one the README states up front: panes inside a single window are not windows to macOS. tmux splits and iTerm splits cannot be focused separately by AutoRaise. If that is the behaviour you were hoping for, the tool cannot deliver it and no flag changes that. The second limit is application compatibility. OLD_ACTIVATION_METHOD exists because some applications do not raise properly, which the README attributes to non-native graphics toolkits such as GTK or SDL, and to wine applications. The fix is a compile-time flag, and the README notes it introduces a deprecation warning. That means the workaround carries its own maintenance cost. The third limit is the experimental focus path. EXPERIMENTAL_FOCUS_FIRST adds support for focusing the hovered window before raising it, or not raising at all when -delay equals 0. The README is unambiguous that this is experimental, that it relies on undocumented private API calls, and that there is absolutely no guarantee it will be supported in future macOS versions. Treat a focus-before-raise workflow as a build you own, not a supported feature. There is also a cost in the polling model itself. Raising decisions happen on a timer, so responsiveness and CPU use move together: the README ties lower pollMillis values to higher CPU load. On a laptop running on battery, that is a real consideration rather than a theoretical one. ## How AutoRaise differs from a tiling window manager The obvious alternative for people who want window behaviour to change is a tiling window manager for macOS, such as yabai or Amethyst. The difference is in what each one controls. A tiling window manager takes over window placement: it decides where windows go, how they are sized, and how they are rearranged. AutoRaise does not manage layout at all. It leaves every window where macOS and the application put it and only changes which one is raised and focused when the pointer crosses it. That makes the two complementary rather than competing. If your complaint is that windows are scattered and you want them arranged, AutoRaise is the wrong tool. If your complaint is that you have to click before you can type, and you are happy with where your windows already sit, AutoRaise addresses exactly that and nothing else. The README's own framing points at the older Stack Overflow discussion on focus-follows-mouse plus auto-raise on macOS, which is the problem space it occupies. A second alternative is simply not installing anything and using the built-in cmd-tab and cmd-grave switchers. AutoRaise does not replace those; it adds an option to warp the mouse to the centre of the activated window when you use them, which is a small addition on top of the system behaviour rather than a substitute for it. ## Licence, maintenance and upgrade cost AutoRaise is licensed GPL-3.0, per the repository's LICENSE.md and the project metadata. That is a copyleft licence. If you compile it with your own CXXFLAGS and redistribute the resulting binary, the GPL-3.0 obligations attach to that distribution. Running it locally for yourself does not raise a distribution question. This is a description of the licence, not legal advice; if you plan to ship a modified AutoRaise inside a product, have someone qualified read the licence. The repository is not archived, and the last push was on 2026-09-22. Releases are spaced out rather than continuous: v5.7 on 2026-09-02, v5.6 on 2026-02-18, v5.5 on 2025-09-17. That cadence is worth knowing before you plan around a fix landing quickly. Upgrade cost is low in the common case and higher for custom builds. The release DMG path is a drag into Applications. A source build is where the cost sits: the Makefile probes for /System/Library/PrivateFrameworks/SkyLight.framework and links it when present, so the build adapts to the machine rather than pinning a version. If you compiled with OLD_ACTIVATION_METHOD or EXPERIMENTAL_FOCUS_FIRST, you carry those flags forward on every rebuild, and the experimental one is the flag most likely to break on a future macOS release. ## Conclusion Adopt AutoRaise if you want focus-follows-mouse on macOS and are willing to grant Accessibility permission to a GPL-3.0 binary, or to compile it yourself from the master branch. Do not adopt it if you expect panes inside one window (tmux, iTerm splits) to be focusable, or if you need a supported path to focus-before-raise: EXPERIMENTAL_FOCUS_FIRST relies on undocumented private API and the README states there is no guarantee it will be supported in future macOS versions. Before installing, verify two things on your machine: that your macOS version still ships /System/Library/PrivateFrameworks/SkyLight.framework, which the Makefile probes for, and that the Accessibility entry you enable is the current AutoRaise item rather than a stale one. ## FAQ ### How do I install AutoRaise on macOS? Download the latest release, unpack it in Finder, open AutoRaise.dmg, drag AutoRaise.app into the Applications folder and open it. Then left click the balloon icon in the menu bar to grant Accessibility permission. If an older AutoRaise item already sits in the Accessibility pane, remove it completely first and restart AutoRaise. ### Is AutoRaise safe to run? The README does not make a safety claim either way. What it does say is that AutoRaise needs Accessibility permission, granted through the balloon icon in the menu bar, and that the optional EXPERIMENTAL_FOCUS_FIRST build relies on undocumented private API calls. The source is available in this repository under GPL-3.0 if you want to read it before running it. ### What is the difference between AutoRaise and autofocus? AutoRaise raises and focuses a window when you hover it and after a delay you configure. The README also documents a focusDelay parameter for delaying the focus step, but states that focusDelay is only supported when compiled with the EXPERIMENTAL_FOCUS_FIRST flag. The repository does not describe a separate autofocus feature beyond that. ### Is there an alternative to AutoRaise on macOS? The README does not name an alternative. It does point at the Stack Overflow discussion on focus-follows-mouse plus auto-raise on macOS, which is the problem it addresses. If you want window placement handled rather than focus, that is a different class of tool from AutoRaise, which only raises and focuses. ## Sources - [Issues](https://github.com/sbmpost/AutoRaise/issues) - [License: GPL-3.0](https://github.com/sbmpost/AutoRaise/blob/master/LICENSE) - [README](https://github.com/sbmpost/AutoRaise/blob/master/README.md) - [Releases](https://github.com/sbmpost/AutoRaise/releases) - [sbmpost/AutoRaise on GitHub](https://github.com/sbmpost/AutoRaise) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/sbmpost-autoraise