fanguolai

Decouple mouse and trackpad scroll directions on macOS.

English | 中文 | 한국어 | 日本語 | Deutsch | Русский | Français | Español | Tiếng Việt | हिन्दी | 粵語 | Svenska | Norsk | Suomi | Català

macOS has one global "Natural Scrolling" toggle. Turn it on and your trackpad feels right, but your mouse wheel goes the wrong way. Turn it off and it's the opposite. There's no built-in way to set them independently.

fanguolai (翻过来, "flip it") fixes this. It sits between your mouse and macOS, reversing only mouse scroll events while leaving trackpad gestures alone.

• ~150 KB single binary, no dependencies
• Per-axis control (vertical / horizontal)
• Daemon mode + LaunchAgent for autostart
• Uses CGEventTap under the hood

# Download from GitHub Releases, or build from source:
git clone https://github.com/chansigit/fanguolai.git
cd fanguolai && make build
sudo make install

# Run it
fanguolai start

First run: macOS will prompt for Accessibility permission. Grant it in System Settings → Privacy & Security → Accessibility.

fanguolai start              # foreground
fanguolai start --daemon     # background
fanguolai stop               # stop daemon
fanguolai status             # show status & config

fanguolai config                        # show current settings
fanguolai config --vertical reverse     # reverse vertical (default)
fanguolai config --horizontal reverse   # reverse horizontal too
fanguolai config --lang zh              # switch CLI language

fanguolai install     # add LaunchAgent
fanguolai uninstall   # remove LaunchAgent

fanguolai start --debug   # print raw scroll events for diagnosis

macOS scroll events carry a flag scrollWheelEventIsContinuous:

The reversal is done by intercepting events via CGEventTap at the session level, copying the event with negated scroll deltas, and returning the modified copy. Trackpad events are never touched.

~/.config/fanguolai/config.json

{
  "horizontal": "normal",
  "lang": "en",
  "vertical": "reverse"
}

v1.0.1 — Fixed scroll reversal requiring double instances. Added --debug flag. v1.0.0 — Initial release.

See CHANGELOG.md for details.

MIT