Mouser — Logitech Mouse Remapper

<p align="center"> <img src="images/logo_icon.png" width="128" alt="Mouser logo" /> </p>

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 family, with early detection and fallback UI support for additional Logitech models.

No telemetry. No cloud. No Logitech account required.

---

Features

🖱️ Button Remapping

• Remap any programmable button — middle click, gesture button, back, forward, mode shift, and horizontal scroll
• Per-application profiles — automatically switch mappings when you switch apps (e.g., Chrome vs. VS Code)
• Custom keyboard shortcuts — define arbitrary key combinations (e.g., Ctrl+Shift+P) as button actions
• 30+ built-in actions — navigation, browser, editing, media, and desktop shortcuts that adapt per platform

⚙️ Device Control

• DPI / pointer speed — slider from 200–8000 DPI with quick presets, synced live via HID++
• Smart Shift toggle — enable or disable Logitech's ratchet-to-free-spin scroll mode switching
• Scroll direction inversion — independent toggles for vertical and horizontal scroll
• Gesture button + swipe actions — tap for one action, swipe up/down/left/right for others

🖥️ Cross-Platform

• Windows, macOS, and Linux — native hooks on each platform (WH_MOUSE_LL, CGEventTap, evdev/uinput)
• Start at login — Windows registry and macOS LaunchAgent, with an independent "Start minimized" tray-only option
• Single instance guard — launching a second copy brings the existing window to the front

🔌 Smart Connectivity

• Auto-reconnection — detects power-off/on and restores full functionality without restarting
• Live connection status — real-time "Connected" / "Not Connected" badge in the UI
• Device-aware UI — interactive MX Master diagram with clickable hotspots; generic fallback for other models

🌐 Multi-Language UI

• English / Simplified Chinese / Traditional Chinese - switch instantly in-app, no restart required
• Language preference is automatically saved to config.json and restored on next launch
• Covers all major UI surfaces: navigation, mouse page, settings page, dialogs, system tray/menu bar, and permission prompts

🛡️ Privacy First

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

Screenshots

<p align="center"> <img src="images/Screenshot_mouse.png" alt="Mouser — Mouse & Profiles page" /> </p> <p align="center"> <img src="images/Screenshot_settings.png" alt="Mouser — Point & Scroll settings" /> </p>

Current Device Coverage

| Family / model | Detection + HID++ probing | UI support | |---|---|---| | MX Master 4 / 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 | | Mode shift (scroll click) | 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), Next Tab (Ctrl+Tab), Previous Tab (Ctrl+Shift+Tab) | | Editing | Copy, Paste, Cut, Undo, Select All, Save, Find | | Media | Volume Up, Volume Down, Volume Mute, Play/Pause, Next Track, Previous Track | | Custom | User-defined keyboard shortcuts (any key combination) | | Other | Do Nothing (pass-through) |

---

Download & Run

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

<p align="center"> <a href="https://github.com/TomBadash/Mouser/releases/latest"> <img src="https://img.shields.io/github/downloads/TomBadash/Mouser/latest/Mouser-Windows.zip?style=for-the-badge&color=00d4aa&logo=windows&label=Windows&displayAssetName=false" alt="Windows Downloads" /> </a> <a href="https://github.com/TomBadash/Mouser/releases/latest"> <img src="https://img.shields.io/github/downloads/TomBadash/Mouser/latest/Mouser-macOS.zip?style=for-the-badge&color=00d4aa&logo=apple&label=macOS&displayAssetName=false" alt="macOS Downloads" /> </a> <a href="https://github.com/TomBadash/Mouser/releases/latest"> <img src="https://img.shields.io/github/downloads/TomBadash/Mouser/latest/Mouser-Linux.zip?style=for-the-badge&color=00d4aa&logo=linux&label=Linux&displayAssetName=false" alt="Linux Downloads" /> </a> <br /> <img src="https://img.shields.io/github/downloads/TomBadash/Mouser/total?style=for-the-badge&color=00d4aa&label=Total%20Downloads%20(all%20versions)" alt="Downloads" /> </p>

Steps

1. Go to the latest release page
2. Download the zip for your platform: Mouser-Windows.zip, Mouser-macOS.zip, or Mouser-Linux.zip
3. Extract the zip to any folder (Desktop, Documents, wherever you like)
4. Run the executable: Mouser.exe (Windows), Mouser.app (macOS), or ./Mouser (Linux)

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

For macOS Accessibility permissions and 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 (Windows), ~/Library/Application Support/Mouser (macOS), or ~/.config/Mouser (Linux)

---

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 | | evdev | Linux mouse grab and virtual device forwarding (uinput) |

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 tray-first startup path used when you launch Mouser directly in the background. The login item uses your saved startup settings.

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