Documentation

Everything you need to install, set up and get the most out of Scroll Wheel Mission Control.

Install

Requires macOS 13 Ventura or later, on an Apple Silicon or Intel Mac.

Download ScrollWheelMissionControl.dmg (always the latest version). Older versions and a .zip are on the GitHub Releases page.
Open the DMG and drag Scroll Wheel Mission Control onto the Applications folder.
In Applications, right-click the app, choose Open, then click Open again in the dialog.

Why the extra step? Apple charges developers $99 a year to notarize apps. This is a free project, so it isn't notarized, and macOS says it is "from an unidentified developer". Right-click > Open tells macOS you trust it. You only do it once.

On macOS 15 Sequoia or later, the Open button may be missing. Try to open the app once, then go to System Settings > Privacy & Security, scroll down and click Open Anyway.

First launch

The app needs Accessibility permission to see scroll wheel clicks and to press the desktop-switching shortcuts for you.

Open the app. Its settings window appears together with a macOS prompt.
Click Open System Settings in the prompt, or Open Settings in the app.
In Privacy & Security > Accessibility, turn on Scroll Wheel Mission Control.
The settings window turns green: Accessibility access granted. No restart needed.
Optional: turn on Launch at login.

Settings window asking for Accessibility access, showing the switch to turn on

How to use it

Gesture	What happens
Hold the wheel, drag right	Go to the desktop on the left (natural) or right (standard)
Hold the wheel, drag left	Go to the desktop on the right (natural) or left (standard)
Click the wheel	Open Mission Control (configurable)

Each drag moves one desktop. To move further, release the wheel and drag again.

Only one desktop? Click the wheel to open Mission Control, then click the + at the top right of the screen to add more.

Settings

Open Settings... from the menu bar icon, or open the app again from Spotlight or Launchpad.

Setting	What it does	Default
Enable scroll wheel gestures	Master on/off switch. Also in the menu bar.	On
Launch at login	Start automatically when you log in	Off
Drag direction	Natural: drag right to reveal the desktop on the left. Standard: drag right to go right.	Natural
Drag distance	How far (in points) you must drag before it switches	30 pt
Wheel click	Open Mission Control, show app windows (App Exposé), or a normal middle click	Mission Control
Excluded apps	While one of these apps is in front, the wheel works normally	Blender

Excluding apps

Click Add App to choose a running app, or pick one from your Applications folder. Useful for 3D and design tools (Blender, Cinema 4D, Maya, Fusion 360, Unity, Unreal), and for browsers if you open links in new tabs with a middle click.

Troubleshooting

Nothing happens when I click or drag

Check that the menu bar icon is filled in. An outlined icon means the app is paused.
Open Settings and check that Accessibility access shows as granted.
After an update, macOS may hold on to the old permission. In Privacy & Security > Accessibility, select the app, remove it with −, then open the app again and allow it.

Mission Control opens, but dragging doesn't switch desktops

The app switches desktops by pressing Ctrl + ← / Ctrl + → for you. Make sure they're on: System Settings > Keyboard > Keyboard Shortcuts... > Mission Control, then tick Move left a space and Move right a space. Also check that you have more than one desktop.

Every wheel click triggers two things

You probably also set a mouse button for Mission Control in macOS itself. Go to System Settings > Desktop & Dock > Shortcuts... and set every "Mouse Button 3" back to –.

Middle click stopped working in my browser or editor

Add that app to Excluded apps, or set Wheel click to Normal middle click. Dragging still switches desktops.

macOS says the app is damaged or can't be opened

That's the quarantine flag on a downloaded, un-notarized app. Run this once in Terminal:

xattr -dr com.apple.quarantine "/Applications/Scroll Wheel Mission Control.app"

Updating

Quit the app from the menu bar, download the latest DMG and drag the new version into Applications, replacing the old one. Your settings are kept. If gestures stop working afterwards, re-allow the app in Accessibility as described above.

Uninstall

Click the menu bar icon and choose Quit.
Delete Scroll Wheel Mission Control from Applications.
Optional: remove it from Privacy & Security > Accessibility, and delete its settings:

defaults delete io.github.enso-works.ScrollWheelMissionControl

Build from source

Prefer not to trust a download? Build it yourself in about a minute. You need the Xcode Command Line Tools (xcode-select --install). No Xcode project or dependencies.

git clone https://github.com/enso-works/Mac-Scroll-Wheel-Mission-Control.git
cd Mac-Scroll-Wheel-Mission-Control
make install

Other targets: make app (build only), make dmg (release DMG and zip), make clean. See the README for signing options.

How it works

A CGEventTap listens only for middle mouse button events. Normal clicks, the scroll wheel itself and the keyboard are never touched.
On button down it checks the frontmost app. If that app is excluded, or the app is paused, the events pass through unchanged.
If you drag past the threshold horizontally, it posts Ctrl + ←/→, the shortcut macOS already uses for "Move left/right a space", and ignores the rest of that drag.
If you release without dragging, it runs the wheel click action.

Because it drives the system's own shortcuts, desktops switch with the standard macOS animation, and there are no private APIs to break on OS updates.

Still stuck? Get help.