The way to use your MX Master 4 on a Mac—without missing the trackpad.
Switch browser tabs and windows, and use everyday shortcuts, right from your mouse. Hold a side button and use the wheel or clicks; release it to use the mouse normally again. The helper identifies MX input so your trackpad keeps working. One Terminal command downloads the compiled helper and installs missing companion apps. There is no Hammerspoon pop-up UI.
| Hold | MX wheel up / down | MX left / right click |
|---|---|---|
| Thumb button | Next / previous browser tab | Close / new tab |
| Third side button | Previous / next app, or window with AltTab; select on release | Copy / paste |
While holding the third side button, click left and right together to select all. Click shortcuts use the usual macOS Command shortcuts in the active app.
- MX Master 4 and macOS 13 or newer, plus Hammerspoon and either OpenLogi 0.8.8+ or Logi Options+. The installer keeps an existing provider and installs OpenLogi by default when neither is present. An administrator password may be needed to install apps in
/Applications. Run only one mouse provider at a time. - AltTab is optional. Apple's built-in switcher works without it. The installer can also download AltTab if you choose individual window thumbnails. Existing apps keep their versions and settings.
- macOS Accessibility and Input Monitoring permissions for the helper and Hammerspoon. AltTab additionally needs Accessibility and Screen Recording when used. Browser tab actions do not need Automation permission.
The prebuilt helper contains Apple Silicon and Intel code and targets macOS 13 or newer. Mouse behavior has been tested on one Apple Silicon Mac running macOS 26.3.1 with native app switching and AltTab 11.6.1 / 11.7.1; the Intel helper tests passed under Rosetta, but a physical Intel Mac and older macOS versions have not been tested. The helper currently recognizes the MX Master 4 hardware ID used by that mouse and accepts the standard Logi Options+ agent path or the signed OpenLogi background agent. OpenLogi needs raw wheel input: keep smooth scrolling off and vertical sensitivity at 14 (1×). Other Logitech mice and other AltTab versions are not verified.
Paste this into Terminal as your normal Mac user:
(s=$(curl -fsSL https://github.com/aytekaksu/mx-master-mac/raw/v0.5.1/scripts/bootstrap.sh)&&[ "$s" ]&&sh -c "$s")The script downloads this release, checks its built-in SHA-256 digest, and installs the helper in ~/.hammerspoon. It installs missing Hammerspoon 1.1.1 from its verified official release, and the official OpenLogi 0.8.8 release for Apple Silicon or Intel after checking its SHA-256 digest, Developer ID signature, and macOS approval. Existing Logi Options+ installs are supported and preserved. If AltTab is missing, it asks “Install AltTab too? [y/N]”: press Return to use macOS, or type y to install the tested AltTab 11.6.1. With no interactive terminal, it defaults to macOS.
No Homebrew, Xcode tools, manual unzip, or source build is needed. The script backs up existing Hammerspoon files, keeps installed apps, and does not launch or reload them. You can run the command again after an interrupted install.
After the command finishes:
- OpenLogi: follow the short OpenLogi setup guide to grant the Agent permissions and assign held F13/F14 shortcuts in its configuration file. Options+: assign the MX thumb button to F13 and the third side button to F14 as keystrokes.
- Grant the requested macOS permissions, then start Hammerspoon or reload it if already running. Enable Hammerspoon's Launch at Login setting and your mouse provider's login agent so the macros return after a restart. To use AltTab's thumbnails, start AltTab, grant its permissions, and enable its login setting too. Detection happens automatically; its keyboard shortcuts stay as you set them.
- Hold a button and try one wheel notch in each direction. If you granted a permission after an app started, quit and reopen that app before testing again.
The helper is ad hoc signed, not Developer ID signed or notarized. macOS may ask you to approve this specific download in System Settings → Privacy & Security before it can run. The release also provides a .sha256 checksum file for the ZIP. Do not disable Gatekeeper system-wide.
Download mx-master-mac-v0.5.1-macos-universal.zip from the latest GitHub release, unzip it, and run sh install.sh in the unzipped folder. Install Hammerspoon and either OpenLogi or Logi Options+ yourself; add AltTab if you want its thumbnails. GitHub's automatic “Source code” ZIP does not contain the compiled helper.
If you prefer to build the helper yourself, install Xcode Command Line Tools, clone this repository, then run make and make test. The resulting universal helper is build/mx4-device-helper; copy it and the two Lua files from hammerspoon/ into ~/.hammerspoon/, then add the loader lines from init.lua.example to your Hammerspoon config.
MX Master 4 + OpenLogi or Options+ (held F13/F14)
↓
Native helper: checks the mouse source and groups wheel steps
↓ tagged actions
Hammerspoon: browser shortcuts + automatic switcher detection
↓
Your browser, Apple's app icons, or AltTab's window thumbnails
The helper consumes a wheel or click only when it recognizes the MX Master 4 action. Trackpad and unknown-device input pass through. The thumb-wheel sends Control+Tab and Control+Shift+Tab to the focused app, with no browser list, tab Accessibility lookup, AppleScript, or per-browser setup. Safari, Chrome/Chromium, Firefox, and Vivaldi support these tab shortcuts; other browsers work when they support the same keys. Each browser chooses its own cycling order, which may be recently used tabs or visible tab order. The thumb-button clicks send Command+W and Command+T for close and new tab. These shortcuts may act differently in a browser that remaps them or in a non-browser app.
| What's running | Third-button wheel behavior |
|---|---|
| No AltTab | Apple's Command+Tab app icons. One step moves to the next or previous app. |
| AltTab | AltTab's thumbnails. One step moves to the next or previous window, including windows from the same app. |
Release the mouse button to select the highlighted item. Apple's standard switcher groups by app; AltTab provides individual windows. Start or quit AltTab to change modes, with no Hammerspoon reload. A running AltTab copy is detected even outside /Applications.
Trackpad scrolling or an ordinary mouse click cancels a mouse-opened native preview and passes through unchanged. Release the third button before starting another selection. A switcher opened from the keyboard keeps its normal behavior.
For macOS, Hammerspoon opens the native switcher and uses Accessibility to select, confirm, and cancel its app icons. It never presses and holds a modifier key. For AltTab, it uses its CLI and sends reverse navigation only to AltTab. Neither mode draws a Hammerspoon overlay or changes your keyboard shortcuts.
Quit Hammerspoon to stop the macros; reopen it to resume. In Hammerspoon's console, mx4runtime.pause() and mx4runtime.resume() also work. mx4runtime.status() reports whether the helper is running. After a wheel gesture, mx4.status() reports windowBackend (macos or alttab) and any switcherError.
- No mouse actions: check the F13/F14 mappings and macOS permissions, then reload Hammerspoon.
- Tabs do not switch: press Control+Tab and Control+Shift+Tab on your keyboard in the focused browser. If those keys do not cycle its tabs, check that browser's shortcut settings. If they work on the keyboard but not the wheel, check
mx4.status()andmx4.trace()in Hammerspoon's console;tab-skip:focus-changedmeans another app took focus before the queued step ran. No browser-specific Automation permission is needed. - Native app switching fails: check Hammerspoon's Accessibility permission and that Command+Tab opens Apple's switcher. Other apps that replace Command+Tab may conflict.
- AltTab switching fails: check its permissions and version. If its CLI is incompatible or unavailable, update or quit AltTab to use macOS. We leave a running AltTab's shortcuts alone instead of sending keystrokes into a conflicting switcher.
- Wheel actions fail with another Logitech mouse connected: the current helper accepts senderless Logi wheel events only when the MX Master 4 is the sole connected Logitech pointing device.
- Build a small native Mac app with a simple settings screen that installs and configures this existing stack for new users, including OpenLogi button setup without editing a file.
- Move the Hammerspoon actions and native helper into that app, while keeping MX-only input filtering and configurable shortcuts.
- Add individual window thumbnails inside the app, alongside native app switching, so that feature also works without AltTab. The current project does not include AltTab's code.
These are plans, not features in this release. The current setup uses AltTab's internal --qa-state command when AltTab is running, plus two nonpublic macOS HID functions in the helper. macOS or AltTab updates may require changes.
Issues and pull requests are welcome. Changes to main require the repository owner's review; see CONTRIBUTING.md. The code is MIT licensed; logo artwork has separate attribution notices. Hammerspoon, AltTab, OpenLogi, and Logi Options+ are separate dependencies with their own licenses. The helper's HID sender technique was informed by LinearMouse; see third-party notices.