TomBadash / Mouser

Mouser — Logitech Mouse Remapper A lightweight, open-source, fully local alternative to **Logitech Options+** for remapping Logitech HID++ mice. The current best experience is on the **MX Master** family, with early detection and fallback UI support for additional Logitech models. No telemetry. No cloud. No Logitech account required. --- Features • **macOS support** — **full macOS compatibility added thanks to andrew-sz**, using CGEventTap for mouse hooking, Quartz CGEvent for key simulation, and NSWorkspace for app detection. See macOS Setup Guide for details. • **Remap supported programmable controls** — MX Master-family layouts expose middle click, gesture button, back, forward, and horizontal scroll actions • **Per-application profiles** — automatically switch button mappings when you switch apps (e.g., different bindings for Chrome vs. VS Code) • **22 built-in actions** across navigation, browser, editing, and media categories • **DPI / pointer speed control** — slider from 200–8000 DPI with quick presets, synced to the device via HID++ • **Scroll direction inversion** — independent toggles for vertical and horizontal scroll • **Device-aware HID++ gesture support** — discovers , ranks gesture candidates per device, and diverts the best control it can find • **Auto-reconnection** — automatically detects when the mouse is turned off/on or disconnected/reconnected and restores full functionality without restarting the app • **Live connection status** — the UI shows a real-time "Connected" / "Not Connected" badge that updates as the mouse connects or disconnects • **Device-aware Qt Quick UI** — interactive MX Master layout today, plus a generic fallback card and experimental manual map picker for other detected devices • **System tray** — runs in background, hides to tray on close, toggle remapping on/off from tray menu • **Auto-detect foreground app** — polls the active window and switches profiles instantly • **Zero external services** — config is a local JSON file, all processing happens on your machine Screenshots _The UI is now device-aware. MX Master-family mice get the interactive diagram; other detected Logitech mice fall back to a generic device card with an experimental map override picker._ Current Device Coverage | Family / model | Detection + HID++ probing | UI support | |---|---|---| | MX Master 3S / 3 / 2S / MX Master | Yes | Dedicated interactive layout | | MX Anywhere 3S / 3 / 2S | Yes | Generic fallback card, experimental manual override | | MX Vertical | Yes | Generic fallback card | | Unknown Logitech HID++ mice | Best effort by PID/name | Generic fallback card | > **Note:** Only the MX Master family currently has a dedicated visual overlay. Other devices can still be detected, show their model name in the UI, and try the experimental layout override picker, but button positions may not line up until a real overlay is added. Default Mappings | Button | Default Action | |---|---| | Back button | Alt + Tab (Switch Windows) | | Forward button | Alt + Tab (Switch Windows) | | Middle click | Pass-through | | Gesture button | Pass-through | | Horizontal scroll left | Browser Back | | Horizontal scroll right | Browser Forward | Available Actions | Category | Actions | |---|---| | **Navigation** | Alt+Tab, Alt+Shift+Tab, Show Desktop (Win+D), Task View (Win+Tab) | | **Browser** | Back, Forward, Close Tab (Ctrl+W), New Tab (Ctrl+T) | | **Editing** | Copy, Paste, Cut, Undo, Select All, Save, Find | | **Media** | Volume Up, Volume Down, Volume Mute, Play/Pause, Next Track, Previous Track | | **Other** | Do Nothing (pass-through) | --- Download & Run > **No install required.** Just download, extract, and double-click. Steps • **Download** → **Mouser.zip** (45 MB) • **Extract** the zip to any folder (Desktop, Documents, wherever you like) • **Run** That's it — the app will open and start remapping your mouse buttons immediately. What to expect • The **settings window** opens showing the current device-aware mouse page • A **system tray icon** appears near the clock (bottom-right) • Button remapping is **active immediately** • Closing the window **doesn't quit** the app — it keeps running in the tray • To fully quit: right-click the tray icon → **Quit Mouser** First-time notes • **Windows SmartScreen** may show a warning the first time → click **More info → Run anyway** • **Logitech Options+** must not be running (it conflicts with HID++ access) • Config is saved automatically to --- Installation (from source) Prerequisites • **Windows 10/11** or **macOS 12+ (Monterey)** • **Python 3.10+** (tested with 3.14) • **A supported Logitech HID++ mouse** paired via Bluetooth or USB receiver. MX Master-family devices currently have the most complete UI support. • **Logitech Options+ must NOT be running** (it conflicts with HID++ access) • **macOS only:** Accessibility permission required (System Settings → Privacy & Security → Accessibility) Steps Dependencies | Package | Purpose | |---|---| | | Qt Quick / QML UI framework | | | HID++ communication with the mouse (gesture button, DPI) | | | System tray icon (legacy, may be removed) | | | Image processing for icon generation | Running > **Tip:** To run without a console window, use or the shortcut. Temporary macOS transport override for debugging: Use this only for troubleshooting. On macOS, Mouser now defaults to ; and remain available as manual overrides for debugging. Other platforms continue to default to . Creating a Desktop Shortcut A shortcut is included. To create one manually: Building the Portable App To produce a standalone that anyone can download and run without Python: The output is in . Zip that entire folder and distribute it. --- How It Works Architecture Mouse Hook ( ) Mouser uses a platform-specific mouse hook behind a shared abstraction: • **Windows** — with on a dedicated background thread, plus Raw Input for extra mouse data • **macOS** — for mouse interception and Quartz events…