TomBadash/Mouser

Mouser — Logitech Mouse Remapper

English | 中文文档

A lightweight, open-source, fully local alternative to Logitech Options+ for remapping Logitech HID++ mice. The current best experience is on the MX Master and MX Anywhere families, with detection and fallback UI support for additional Logitech models.

No telemetry. No cloud. No Logitech account required.

Contents

• Download & Run
• Screenshots
• Features
• Device coverage
• Default mappings
• Available actions
• Build from source
• Limitations
• Roadmap
• Contributing
• Acknowledgments
• License

Download & Run

No install required. Just download, extract, and double-click.

1. Open the latest release page.
2. Download the zip for your platform:
   • Windows — Mouser-Windows.zip
   • macOS (Apple Silicon) — Mouser-macOS.zip
   • macOS (Intel) — Mouser-macOS-intel.zip
   • Linux — Mouser-Linux.zip
3. Extract it anywhere (Desktop, Documents, /Applications, wherever).
4. Run the executable: Mouser.exe, Mouser.app, or ./Mouser.

That's it. The app opens, drops a tray / menu-bar icon, and starts remapping immediately.

What to expect on first launch

• The settings window opens to the device-aware Mouse & Profiles page.
• A tray icon appears (next to the clock on Windows / Linux, in the menu bar on macOS).
• Closing the window keeps Mouser running in the tray. Right-click the tray icon → Quit Mouser to fully exit.
• Mouser remembers language and startup behavior between runs.

First-time notes

• Windows SmartScreen may warn the first time — click More info → Run anyway.
• Logitech Options+ must not be running. Both apps fight over HID++ access; quit Options+ before launching Mouser.
• macOS asks for Accessibility permission so the event tap can intercept mouse events. See readme_mac_osx.md for the full setup walkthrough.
• Linux needs read access to /dev/hidraw*, /dev/input/event*, and write access to /dev/uinput. Run the bundled helper once after extracting:

  cd /path/to/extracted/Mouser
  ./install-linux-permissions.sh
  

  Reconnect the mouse, then relaunch.
• Config is saved automatically to:
  • %APPDATA%\Mouser\config.json (Windows)
  • ~/Library/Application Support/Mouser/config.json (macOS)
  • ~/.config/Mouser/config.json (Linux)
• Logs rotate automatically (5 × 5 MB) under %APPDATA%\Mouser\logs, ~/Library/Logs/Mouser, or $XDG_STATE_HOME/Mouser/logs.

Screenshots

Mouse & Profiles	Point & Scroll

Features

Button remapping

• Remap any programmable button — middle click, gesture button, back, forward, mode shift, DPI switch (MX Vertical), and horizontal scroll.
• Mouse-to-mouse remap — bind any button to act as left, right, middle, back, or forward click.
• Per-application profiles — Mouser auto-switches mappings when the foreground app changes (e.g. Chrome vs. VS Code).
• Custom keyboard shortcuts — record any key combination (e.g. Ctrl+Shift+P) directly in the UI.
• 40+ built-in actions — navigation, browser, editing, media, scroll-mode, and DPI shortcuts that adapt per platform.

Device control

• DPI / pointer speed — slider from 200 to the device max (8000 on MX Master) with quick presets, plus a Cycle DPI Presets action you can map to a button.
• Smart Shift — toggle Logitech's ratchet ↔ free-spin scroll mode (HID++ 0x2111), with a sensitivity threshold and a mappable Toggle SmartShift action.
• Switch scroll mode — bind a button to flip ratchet / free-spin without opening the UI; defaults to mode-shift.
• Scroll direction inversion — independent toggles for vertical and horizontal scroll.
• Gesture button + swipe actions — tap for one action, swipe up/down/left/right for four others.

Cross-platform

• Windows, macOS, and Linux — native hooks per platform (WH_MOUSE_LL, CGEventTap, evdev + uinput).
• Native Intel and Apple Silicon macOS builds — separate Mouser-macOS-intel.zip and Mouser-macOS.zip artifacts; the menu-bar app runs as LSUIElement (no Dock icon).
• Resizable UI — main window starts at 1060 × 700 with a 920 × 620 minimum; the mouse diagram and controls reflow as you resize.
• Start at login — Windows registry key, macOS LaunchAgent, and Linux XDG autostart, with an independent Start minimized option that boots straight into the tray. Linux autostart intentionally waits about 15 seconds after login so Bluetooth / HID devices are usually ready before Mouser restores device settings.
• Single-instance guard — launching a second copy brings the existing window to the front instead of starting a duplicate.

Smart connectivity

• Bluetooth and Logi Bolt — both transports are supported on all three platforms; the UI labels the live connection (Logi Bolt only when the receiver PID is positively identified).
• Auto-reconnection — Mouser watches for power-off / on cycles and rebinds HID++ + the OS mouse hook without a restart; SmartShift settings are replayed on every reconnect (including wake-from-sleep).
• Live connection status — real-time Connected / Not Connected badge, model name, and active layout in the UI.
• Device-aware UI — interactive MX Master and MX Anywhere diagrams with clickable hotspots; generic fallback card for other models, with an experimental layout-override picker.

Multi-language UI

• English / Simplified Chinese / Traditional Chinese — switch instantly, no restart required.
• Language preference is saved to config.json and restored on next launch.
• Covers nav, mouse page, settings page, dialogs, system tray / menu bar, and permission prompts.

Privacy first

• Fully local — config is a plain JSON file, all processing happens on your machine.
• System tray / menu bar — runs quietly in the background.
• Zero telemetry, zero cloud, zero account required.

Device coverage

MX Master and MX Anywhere devices have dedicated visual overlays. Other devices are still detected, show their model name, and can opt into an experimental layout override — button positions just may not line up until a real overlay lands. See CONTRIBUTING_DEVICES.md to add yours.

Default mappings

Available actions

Action labels adapt per platform. Windows exposes Win+D and Task View; macOS exposes Mission Control, Show Desktop, App Exposé, and Launchpad; Linux falls back to compositor-native equivalents.

Build from source

You only need this if you want to hack on Mouser or run a development build. Most users should grab a release zip — see Download & Run.

Common prerequisites

• Windows 10/11, macOS 12+ (Monterey), or Linux (X11; KDE Wayland for app detection)
• Python 3.10+ (tested up to 3.14)
• A supported Logitech HID++ mouse paired via Bluetooth or a USB receiver
• Logitech Options+ must NOT be running — it conflicts with HID++ access
• git and a working build toolchain

git clone https://github.com/TomBadash/Mouser.git
cd Mouser
python -m venv .venv

.\.venv\Scripts\activate
pip install -r requirements.txt

# Run from source
python main_qml.py

# Or start straight into the tray
python main_qml.py --start-hidden

# Build a portable zip
build.bat                # standard
build.bat --clean        # force clean rebuild

source .venv/bin/activate
pip install -r requirements.txt

# Run from source
python main_qml.py
python main_qml.py --start-hidden     # launch directly to menu bar

# Build the native menu-bar bundle
pip install pyinstaller
./build_macos_app.sh

MOUSER_SIGN_IDENTITY="ABCD1234..." ./build_macos_app.sh   # local signed build

source .venv/bin/activate
pip install -r requirements.txt

# Run from source
python main_qml.py

# Install device permissions (only needed once, then reconnect the mouse)
./packaging/linux/install-linux-permissions.sh

# Build a portable bundle
sudo apt-get install libhidapi-dev
pip install pyinstaller
pyinstaller Mouser-linux.spec --noconfirm

~/.local/share/applications/io.github.tombadash.mouser.desktop

~/.config/autostart/io.github.tombadash.mouser.desktop

Automated releases: pushing a v* tag triggers .github/workflows/release.yml, which builds Windows, macOS (Apple Silicon + Intel), and Linux artifacts in CI and uploads them to the GitHub Release.

For project layout, the architecture diagram, the HID++ gesture detector, the Engine + reconnection flow, debug CLI flags (--hid-backend=iokit|hidapi|auto), and how to run the test suite, see DEVELOPMENT.md. To add a new device, see CONTRIBUTING_DEVICES.md.

Limitations

• Per-device mappings aren't fully separated yet — layout overrides are stored per detected device, but profile mappings are still global.
• Conflicts with Logitech Options+ — both apps fight over HID++ access. Quit Options+ before running Mouser.
• Scroll inversion uses coalesced post-injection on Windows to avoid LL-hook deadlocks; it's stable in mainstream apps but may misbehave in some games or low-level drivers.
• Admin not required — but injected keystrokes may not reach elevated windows or some games. Run Mouser elevated if you need that path.
• Linux app detection is partial — X11 works via xdotool, KDE Wayland works via kdotool, GNOME / other Wayland compositors still fall back to the default profile.
• Linux device permissions — Mouser needs access to /dev/hidraw*, /dev/input/event*, and /dev/uinput. Use install-linux-permissions.sh once instead of running as root.

Roadmap

• Dedicated overlays for more devices — real hotspot maps and artwork for MX Vertical and other Logitech families
• True per-device config — separate mappings cleanly when multiple Logitech mice are used on the same machine
• Dynamic button inventory — build button lists from discovered REPROG_CONTROLS_V4 controls instead of the current fixed sets
• Improved scroll inversion — explore driver-level or interception-driver approaches
• Gesture swipe tuning — improve swipe reliability and defaults across more devices
• Per-app profile auto-creation — detect new apps and prompt to create a profile
• Export / import config — share configurations between machines
• Tray icon badge — show the active profile name in the tray tooltip
• Broader Wayland support — extend app detection beyond X11 / KDE and validate across more distros
• Plugin system — allow third-party action providers

Contributing

Contributions are welcome.

• Code, fixes, and features: fork → branch → PR. The dev setup, architecture overview, debug flags, and test instructions live in DEVELOPMENT.md.
• Adding a new Logitech mouse: follow the discovery-dump walkthrough in CONTRIBUTING_DEVICES.md. Even a partial dump helps.
• Help wanted:
  • Testing with other Logitech HID++ devices
  • Scroll inversion improvements
  • Broader Linux / Wayland validation
  • UI/UX polish, accessibility, and translations

Support the project

If Mouser saves you from installing Logitech Options+, consider supporting development:

Every bit helps keep the project going — thank you.

Acknowledgments

• @andrew-sz — macOS port: CGEventTap mouse hooking, Quartz key simulation, NSWorkspace app detection, and NSEvent media key support.
• @thisislvca — significant expansion of the project including macOS compatibility improvements, multi-device support, new UI features, and active triage of open issues.
• @awkure — cross-platform login startup (Windows registry + macOS LaunchAgent), single-instance guard, start-minimized option, and MX Master 4 detection.
• @hieshima — Linux support (evdev + HID++ + uinput), mode-shift mapping, Smart Shift toggle, custom keyboard shortcut support, Linux connection-state stabilization, and macOS CGEventTap reliability fixes (auto re-enable on timeout, trackpad scroll filtering).
• @pavelzaichyk — Next Tab / Previous Tab browser actions, persistent rotating log file storage, Smart Shift enhanced support (HID++ 0x2111) with sensitivity control and scroll-mode sync.
• @nellwhoami — Multi-language UI system (English, Simplified Chinese, Traditional Chinese) and Page Up / Page Down / Home / End navigation actions.
• @guilamu — Mouse-to-mouse button remapping (left, right, middle, back, forward click) and HID++ stability fixes (stuck-button auto-release, auto-reconnect after consecutive timeouts, async dispatch queue for the Windows hook).
• @vcanuel — Logi Bolt receiver support on macOS via the hidapi fallback path.
• @farfromrefug — smaller macOS bundle (Qt Quick Controls trim, QtDBus, Qt asset filtering).
• @MysticalMike60t — README structure ideas (collapsible per-OS build sections).
• @davidnoyes - Full Logitech MX Master 4 support: Actions Ring radial menu, per-slot haptics, stroke-aware gestures, dual-CID HID++ routing, and force-sensitivity control, integrating and adapting a range of community contributions; plus a charging-state indicator on the battery badge.
• @hughesyadaddy - MX Master 4 firmware-first HID++ runtime, hardware-reported DPI persistence, Backend list-property memoization, and OS mouse-event passthrough when no Logitech device is connected.
• @laziukdavid - Reworked swipe-gesture recognition and faster HID++ device detection.
• @FunJim - Shift+wheel horizontal scroll on macOS/Windows/Linux, and preserving a symlinked config.json on atomic save.
• @chenqianhe - macOS nested app-identity matching for per-app profiles.
• @liuxuAP369 - Fractional macOS horizontal scroll delta handling.
• @winniesi - Ping-pong desktop cycling action (macOS).
• @Archetipo95 - Physical scroll-wheel tilt support and reduced remapping latency on macOS.
• @zeward-lee - Scan-code injection on remapped keystrokes so side-button copy/paste reaches UWP / Store apps.
• @ArtisticZhao - Background HID polling no longer resets the system idle timer, so the display can sleep and the system can idle while Mouser runs (visibility-gated polling with an idle-grace period).
• @mizi - Scroll Force control: adjustable ratchet firmness for enhanced SmartShift (HID++ 0x2111) devices, with a per-device Scroll page slider.
• @kevin-nous - Original per-button slide-gesture concept (event-tap arming, dual-mode tap/gesture), which inspired the cross-platform "Gesture Swipe" action: any device-advertised button becomes a hold-and-slide gesture pad on Windows, macOS, and Linux.
• @unijiang - Logitech M585/M590 Multi-Device Mouse support: device catalog entry (name/alias matched to avoid over-claiming the shared receiver PID), interactive hotspot layout, and wheel-tilt exposure as configurable left/right controls.

License

This project is licensed under the MIT License.

Mouser is not affiliated with or endorsed by Logitech. "Logitech", "MX Master", and "Options+" are trademarks of Logitech International S.A.