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 using CGEventTap for mouse hooking, Quartz CGEvent for key simulation, and NSWorkspace for app detection. See macOS Setup Guide for details.
Experimental Linux support — evdev/uinput button remapping, HID++ gesture support, X11 foreground-app detection, and KDE Wayland app detection via kdotool
macOS start at login — manages a per-user LaunchAgent from the UI, with an optional "Launch hidden after login" mode for menu-bar startup
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)
Desktop navigation actions — includes previous/next desktop switching on Windows, macOS, and Linux (GNOME/KDE defaults), plus Mission Control, App Expose, Launchpad, and Show Desktop on macOS
Platform-aware 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 REPROG_CONTROLS_V4, 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 / menu bar — runs in background, hides on close, and exposes quick open / toggle / quit actions
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 `mx_master` 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

Action labels adapt by platform. For example, Windows exposes Win+D and Task View, while macOS exposes Mission Control, Show Desktop, App Expose, and Launchpad.

Category	Actions
Navigation	Alt+Tab, Alt+Shift+Tab, Show Desktop, Previous Desktop, Next Desktop, Task View (Windows), Mission Control (macOS), App Expose (macOS), Launchpad (macOS)
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

Go to the latest release page
Click Mouser.zip to download it
Extract the zip to any folder (Desktop, Documents, wherever you like)
Run Mouser.exe

That's it. The app will open and start remapping your mouse buttons immediately.

For macOS setup, native bundle packaging, and Accessibility / login-item notes, see the macOS Setup Guide.

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 does not quit the app — it keeps running in the tray
To fully quit: right-click the tray icon and select Quit Mouser

First-time notes

Windows SmartScreen may show a warning the first time — click More info then Run anyway
Logitech Options+ must not be running (it conflicts with HID++ access and will cause Mouser to malfunction or crash)
Config is saved automatically to %APPDATA%\Mouser

Installation (from source)

Prerequisites

Windows 10/11, macOS 12+ (Monterey), or Linux (experimental; X11 plus KDE Wayland app detection)
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)
Linux only: xdotool enables per-app profile switching on X11; kdotool additionally enables KDE Wayland detection
Linux only: read access to /dev/input/event* and write access to /dev/uinput are required for remapping (you may need to add your user to the input group)

Steps

# 1. Clone the repository
git clone https://github.com/TomBadash/Mouser.git
cd Mouser

# 2. Create a virtual environment
python -m venv .venv

# 3. Activate it
.venv\Scripts\activate        # Windows (PowerShell / CMD)
source .venv/bin/activate      # macOS / Linux

# 4. Install dependencies
pip install -r requirements.txt

Dependencies

Package	Purpose
`PySide6`	Qt Quick / QML UI framework
`hidapi`	HID++ communication with the mouse (gesture button, DPI)
`Pillow`	Image processing for icon generation
`pyobjc-framework-Quartz`	macOS CGEventTap / Quartz event support
`pyobjc-framework-Cocoa`	macOS app detection and media-key support

Running

# Option A: Run directly
python main_qml.py

# Option B: Start directly in the tray / menu bar
python main_qml.py --start-hidden

# Option C: Use the batch file (shows a console window)
Mouser.bat

# Option D: Use the desktop shortcut (no console window)
# Double-click Mouser.lnk

Tip: To run without a console window, use pythonw.exe main_qml.py or the .lnk shortcut. On macOS, --start-hidden is the same switch used by the Start at login LaunchAgent.

Temporary macOS transport override for debugging:

python main_qml.py --hid-backend=iokit
python main_qml.py --hid-backend=hidapi
python main_qml.py --hid-backend=auto

Use this only for troubleshooting. On macOS, Mouser now defaults to iokit; hidapi and auto remain available as manual overrides for debugging. Other platforms continue to default to auto.

Creating a Desktop Shortcut

A Mouser.lnk shortcut is included. To create one manually:

$s = (New-Object -ComObject WScript.Shell).CreateShortcut("$([Environment]::GetFolderPath('Desktop'))\Mouser.lnk")
$s.TargetPath = "C:\path\to\mouser\.venv\Scripts\pythonw.exe"
$s.Arguments = "main_qml.py"
$s.WorkingDirectory = "C:\path\to\mouser"
$s.IconLocation = "C:\path\to\mouser\images\logo.ico, 0"
$s.Save()

Building Distribution Artifacts

Windows portable build:

# 1. Install PyInstaller (inside your venv)
pip install pyinstaller

# 2. Build using the included spec file
pyinstaller Mouser.spec --noconfirm

# — or simply run the build script —
build.bat

The output is in dist\Mouser\. Zip that entire folder and distribute it.

macOS native bundle:

# 1. Install PyInstaller (inside your venv)
pip install pyinstaller

# 2. Build the native menu-bar app bundle
./build_macos_app.sh

The output is dist/Mouser.app. The script prefers images/AppIcon.icns when present, otherwise it generates an .icns icon from images/logo_icon.png, then ad-hoc signs the bundle with codesign --sign -.

How It Works

Architecture

┌────────────────┐     ┌──────────┐     ┌────────────────┐
│ Logitech mouse │────▶│ Mouse    │────▶│ Engine         │
│ / HID++ device │     │ Hook     │     │ (orchestrator) │
└────────────────┘     └──────────┘     └───────┬────────┘
                         ▲                    │
                    block/pass           ┌────▼────────┐
                                         │ Key         │
┌─────────────┐     ┌──────────┐        │ Simulator   │
│ QML UI      │◀───▶│ Backend  │        │ (SendInput) │
│ (PySide6)   │     │ (QObject)│        └─────────────┘
└─────────────┘     └──────────┘
                         ▲
                    ┌────┴────────┐
                    │ App         │
                    │ Detector    │
                    └─────────────┘

Mouse Hook (`mouse_hook.py`)

Mouser uses a platform-specific mouse hook behind a shared MouseHook abstraction:

Windows — SetWindowsHookExW with WH_MOUSE_LL on a dedicated background thread, plus Raw Input for extra mouse data
macOS — CGEventTap for mouse interception and Quartz events for key simulation
Linux — evdev to grab the physical mouse and uinput to forward pass-through events via a virtual device

Both paths feed the same internal event model and intercept:

WM_XBUTTONDOWN/UP — side buttons (back/forward)
WM_MBUTTONDOWN/UP — middle click
WM_MOUSEHWHEEL — horizontal scroll
WM_MOUSEWHEEL — vertical scroll (for inversion)

Intercepted events are either blocked (hook returns 1) and replaced with an action, or passed through to the application.

Device Catalog & Layout Registry

core/logi_devices.py resolves known product IDs and model aliases into a ConnectedDeviceInfo record with display name, DPI range, preferred gesture CIDs, and default UI layout key
core/device_layouts.py stores image assets, hotspot coordinates, layout notes, and whether a layout is interactive or only a generic fallback
ui/backend.py combines auto-detected device info with any persisted per-device layout override and exposes the effective layout to QML

Gesture Button Detection

Logitech gesture/thumb buttons do not always appear as standard mouse events. Mouser uses a layered detector:

HID++ 2.0 (primary) — Opens the Logitech HID collection, discovers REPROG_CONTROLS_V4 (feature 0x1B04), ranks gesture CID candidates from the device registry plus control-capability heuristics, and diverts the best candidate. When supported, Mouser also enables RawXY movement data.
Raw Input (Windows fallback) — Registers for raw mouse input and detects extra button bits beyond the standard 5.
Gesture tap/swipe dispatch — A clean press/release emits gesture_click; once movement crosses the configured threshold, Mouser emits directional swipe actions instead.

App Detector (`app_detector.py`)

Polls the foreground window every 300ms using GetForegroundWindow → GetWindowThreadProcessId → process name. Handles UWP apps by resolving ApplicationFrameHost.exe to the actual child process.

Engine (`engine.py`)

The central orchestrator. On app change, it performs a lightweight profile switch — clears and re-wires hook callbacks without tearing down the hook thread or HID++ connection. This avoids the latency and instability of a full hook restart. The engine also forwards connected-device identity to the backend so QML can render the right model name and layout state.

Device Reconnection

Mouser handles mouse power-off/on cycles automatically:

HID++ layer — HidGestureListener detects device disconnection (read errors) and enters a reconnect loop, retrying every 2–5 seconds until the device is back
Hook layer — MouseHook listens for WM_DEVICECHANGE notifications and reinstalls the low-level mouse hook when devices are added or removed
UI layer — connection state and device identity flow from HID++ → MouseHook → Engine → Backend (cross-thread safe via Qt signals) → QML, updating the status badge, device name, and active layout in real time

Configuration

All settings are stored in %APPDATA%\Mouser\config.json (Windows) or ~/Library/Application Support/Mouser/config.json (macOS). The config supports:

Multiple named profiles with per-profile button mappings, including gesture tap + swipe actions
Per-profile app associations (list of .exe names)
Global settings: DPI, scroll inversion, gesture tuning, appearance, debug flags, and macOS startup preferences (start_at_login, start_minimized)
Per-device layout override selections for unsupported devices
Automatic migration from older config versions

Project Structure

mouser/
├── main_qml.py              # Application entry point (PySide6 + QML)
├── Mouser.bat               # Quick-launch batch file
├── Mouser-mac.spec          # Native macOS app-bundle spec
├── build_macos_app.sh       # macOS bundle build + icon/signing flow
├── README.md
├── readme_mac_osx.md
├── requirements.txt
├── .gitignore
│
├── core/                    # Backend logic
│   ├── accessibility.py     # macOS Accessibility trust checks
│   ├── engine.py            # Core engine — wires hook ↔ simulator ↔ config
│   ├── mouse_hook.py        # Low-level mouse hook + HID++ gesture listener
│   ├── hid_gesture.py       # HID++ 2.0 gesture button divert (Bluetooth)
│   ├── logi_devices.py      # Known Logitech device catalog + connected-device metadata
│   ├── device_layouts.py    # Device-family layout registry for QML overlays
│   ├── key_simulator.py     # Platform-specific action simulator
│   ├── autostart.py         # macOS LaunchAgent helpers
│   ├── config.py            # Config manager (JSON load/save/migrate)
│   └── app_detector.py      # Foreground app polling
│
├── ui/                      # UI layer
│   ├── backend.py           # QML ↔ Python bridge (QObject with properties/slots)
│   └── qml/
│       ├── Main.qml         # App shell (sidebar + page stack + tray toast)
│       ├── MousePage.qml    # Merged mouse diagram + profile manager
│       ├── ScrollPage.qml   # DPI slider + scroll inversion toggles
│       ├── HotspotDot.qml   # Interactive button overlay on mouse image
│       ├── ActionChip.qml   # Selectable action pill
│       └── Theme.js         # Shared colors and constants
│
└── images/
    ├── AppIcon.icns        # Committed macOS app-bundle icon
    ├── mouse.png            # MX Master 3S top-down diagram
    ├── icons/mouse-simple.svg # Generic fallback device card artwork
    ├── logo.png             # Mouser logo (source)
    ├── logo.ico             # Multi-size icon for shortcuts
    ├── logo_icon.png        # Square icon with background
    ├── chrom.png            # App icon: Chrome
    ├── VSCODE.png           # App icon: VS Code
    ├── VLC.png              # App icon: VLC
    └── media.webp           # App icon: Windows Media Player

UI Overview

The app has two pages accessible from a slim sidebar:

Mouse & Profiles (Page 1)

Left panel: List of profiles. The "Default (All Apps)" profile is always present. Per-app profiles show the app icon and name. Select a profile to edit its mappings.
Right panel: Device-aware mouse view. MX Master-family devices get clickable hotspot dots on the image; unsupported layouts fall back to a generic device card with an experimental "try another supported map" picker.
Add profile: ComboBox at the bottom lists known apps (Chrome, Edge, VS Code, VLC, etc.). Click "+" to create a per-app profile.

Point & Scroll (Page 2)

DPI slider: 200–8000 with quick presets (400, 800, 1000, 1600, 2400, 4000, 6000, 8000). Reads the current DPI from the device on startup.
Scroll inversion: Independent toggles for vertical and horizontal scroll direction.
Startup controls: On macOS, this page also exposes Start at login and Launch hidden after login.

Known Limitations

Early multi-device support — only the MX Master family currently has a dedicated interactive overlay; MX Anywhere, MX Vertical, and unknown Logitech mice still use the generic fallback card
Per-device mappings are not fully separated yet — layout overrides are stored per detected device, but profile mappings are still global rather than truly device-specific
Bluetooth recommended — HID++ gesture button divert works best over Bluetooth; USB receiver has partial support
Conflicts with Logitech Options+ — both apps fight over HID++ access; quit Options+ before running Mouser
Scroll inversion is experimental — uses coalesced PostMessage injection to avoid LL hook deadlocks; may not work perfectly in all apps
Admin not required — but some games or elevated windows may not receive injected keystrokes
Linux app detection is still limited — X11 works via xdotool, KDE Wayland works via kdotool, and GNOME / other Wayland compositors still fall back to the default profile
Linux remapping needs device permissions — Mouser must be able to read /dev/input/event* and write /dev/uinput

Future Work

Contributing

Contributions are welcome! To get started:

Fork the repo and create a feature branch
Set up the dev environment (see Installation)
Make your changes and test with a supported Logitech HID++ mouse (MX Master family preferred for now)
Submit a pull request with a clear description

Areas where help is needed

Testing with other Logitech HID++ devices
Scroll inversion improvements
Linux porting
UI/UX polish and accessibility

Support the Project

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

Every bit helps keep the project going — thank you!

License

This project is licensed under the MIT License.

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 involvement in triaging and resolving open issues

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

Name		Name	Last commit message	Last commit date
Latest commit History 72 Commits
.github		.github
core		core
images		images
tests		tests
ui		ui
.gitignore		.gitignore
DEVELOPMENT.md		DEVELOPMENT.md
LICENSE		LICENSE
Mouser-mac.spec		Mouser-mac.spec
Mouser.bat		Mouser.bat
Mouser.spec		Mouser.spec
README.md		README.md
build.bat		build.bat
build_macos_app.sh		build_macos_app.sh
main_qml.py		main_qml.py
readme_mac_osx.md		readme_mac_osx.md
requirements.txt		requirements.txt

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

Mouser — Logitech Mouse Remapper

Features

Screenshots

Current Device Coverage

Default Mappings

Available Actions

Download & Run

Steps

What to expect

First-time notes

Installation (from source)

Prerequisites

Steps

Dependencies

Running

Creating a Desktop Shortcut

Building Distribution Artifacts

How It Works

Architecture

Mouse Hook (mouse_hook.py)

Device Catalog & Layout Registry

Gesture Button Detection

App Detector (app_detector.py)

Engine (engine.py)

Device Reconnection

Configuration

Project Structure

UI Overview

Mouse & Profiles (Page 1)

Point & Scroll (Page 2)

Known Limitations

Future Work

Contributing

Areas where help is needed

Support the Project

License

Acknowledgments

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 3

Sponsor this project

Uh oh!

Packages 0

Uh oh!

Contributors 8

Languages

Mouse Hook (`mouse_hook.py`)

App Detector (`app_detector.py`)

Engine (`engine.py`)

Packages