MouseMapper

MouseMapper is a small macOS menu bar app for mapping extra mouse buttons to keyboard keys or shortcuts.

The GitHub repository name is simple-mouse-mapper; the app name stays MouseMapper.

Features

• Runs quietly from the macOS menu bar.
• Maps extra mouse buttons, such as forward/back side buttons.
• Supports single keys and keyboard shortcuts.
• Captures mouse buttons by pressing them during setup.
• Supports global enable/disable and per-mapping enable/disable.
• Stores settings locally with UserDefaults.
• Starts at login by default.

Requirements

• macOS 13 or later
• Accessibility permission
• Input Monitoring permission may be required for shortcut capture

Run From Source

swift run MouseMapper

On first launch, grant the required macOS privacy permissions when prompted.

Build App

scripts/build-app.sh

The app bundle is created at:

dist/MouseMapper.app

The build script injects the app icon from MouseMapper.iconset and signs the app locally. This build is not notarized.

Notes

MouseMapper is intentionally narrow in scope. It does not support gestures, macros, app-specific profiles, cloud sync, or mouse vendor integrations.