Klik PRO

Remap the extra buttons on a "pro" mouse to keyboard shortcuts — a lightweight, native macOS menu-bar utility.

This app is open source under the MIT License. If Klik PRO improves your workflow, help support continued development and mouse/browser compatibility testing:

Features · Install · Shortcuts · How it works · Building · Tested with · Support · Contributing · License

Klik PRO remaps middle, forward, and back mouse-button events to recordable keyboard shortcuts. On supported device profiles, enabling Gesture replaces the mouse's standard ⌘Tab output with the configured Klik PRO shortcut; the physical keyboard's ⌘Tab remains unchanged. The horizontal thumb wheel provides configurable browser-tab switching. Left- and right-click are left untouched.

It's a small always-on background helper that does the remapping, plus a settings app for recording supported mouse-button shortcuts and checking for conflicts. Its adaptive Klik PRO menu-bar icon opens Settings with a left-click; right-click provides Settings, About, and Quit. It can be hidden from Settings, and two green button dots appear only while its Accessibility input tap is operational. The optional ChatGPT / Codex & Claude Quick Launch feature adds separate launcher icons and hotkeys, and can temporarily link either launcher to a supported mouse button without replacing that button's normal mapping. Its icons can be hidden while its hotkeys and assigned buttons remain active. Actual button and wheel support varies by hardware.

Welcome guide — first-launch Accessibility setup, ready-to-try defaults, and a direct path to Mappings:

Supported controls — configure compatible mouse controls and see live conflict checks:

Settings — launch-at-login, menu-icon visibility, update-check, and guided Accessibility setup/reset controls:

Features

• Four recordable button shortcuts on the tested mouse — middle, Gesture, forward, and back. When enabled, Gesture overrides the mouse's standard ⌘Tab output with its configured shortcut without changing keyboard ⌘Tab. Left- and right-click are never touched.
• Live conflict checking — flags duplicate assignments, reserved macOS shortcuts, configured browser-extension commands, and combos already claimed system-wide as you record them.
• Thumb-wheel tab switching — the horizontal wheel flips browser tabs, with per-browser combinations and a sensible fallback elsewhere.
• Save applies instantly — no manual restart; the background helper restarts automatically on save.
• Configurable Klik PRO menu-bar icon — left-click opens Settings; right-click provides Settings, About, and Quit. It adapts to light, dark, selected, and inactive menu bars, shows two green button dots only while the main Accessibility input tap is active, and can be hidden from Settings.
• Native & lightweight — Swift + AppKit/Carbon, no dependencies or vendor drivers; standard controls use macOS event taps and Gesture uses a device-scoped macOS HID key map.
• Optional ChatGPT / Codex & Claude Quick Launch — adds separate launcher icons + global hotkeys for ChatGPT / Codex and Claude. Each launcher can also be linked to Middle, Gesture, Forward, or Back while preserving that button's normal mapping underneath. New configurations start with Forward assigned to ChatGPT / Codex and Back assigned to Claude; both remain changeable or removable through None. Its launcher icons can be hidden independently while the hotkeys and assigned mouse buttons continue working. Its master toggle is available only when ChatGPT / Codex or Claude is installed; launcher wrappers alone do not count. Each app-specific hotkey and picker clearly disables when its app or launcher wrapper is missing; a stale picker assignment can still be cleared with None.
• In-app update check — notifies you when a newer GitHub release is available.

Install (pre-built release)

The current release is Klik PRO v1.3.9 (build 18), provided as one universal macOS app for Apple Silicon and Intel Macs. The DMG is the recommended download; the ZIP contains the same app as an alternative. Download Klik PRO v1.3.9.

Klik PRO is not notarized or signed with an Apple Developer ID — it's an ad-hoc-signed, self-built utility — so a downloaded copy is quarantined and Gatekeeper blocks it on first launch. That's expected for any non-notarized app.

Verified Terminal installer

Starting with releases that include a signed checksum, the recommended Terminal path authenticates the DMG before bypassing Gatekeeper. Download the installer, inspect it, and run it as separate steps — never pipe a network response into a shell:

curl --proto '=https' --tlsv1.2 -fLO \
  https://raw.githubusercontent.com/AminudinMurad/klik-pro/main/install.sh
less install.sh
chmod +x install.sh
./install.sh

The installer verifies the checksum with the dedicated Klik PRO Ed25519 release key, checks the DMG, both bundle identifiers and versions, universal architectures, and code-signature integrity, then asks before staging the app in /Applications and removing quarantine. Existing configuration and logs are preserved. Release-key fingerprint: SHA256:Evg4ITqpPJY/aIT48Zv9Cp3psQfo977uCz/35a2k79E. After installation succeeds, it opens Klik PRO automatically; continue with the first-launch steps below. This installer workflow has been tested from a fully clean state as well as against an older two-service installation.

Manual installation

To install manually through the standard macOS interface:

1. Download the universal macOS DMG from the latest release, open it, then drag Klik PRO.app onto the Applications shortcut. Alternatively, extract the universal ZIP and move Klik PRO.app to /Applications.

2. Double-click it. macOS says "Klik PRO can't be opened because Apple cannot check it for malicious software." Click Done — do not move it to Trash.

3. Open System Settings → Privacy & Security, scroll to Security, find "Klik PRO was blocked…", click Open Anyway, authenticate, and confirm. (On macOS 15+ the old right-click → Open shortcut no longer bypasses Gatekeeper for unsigned apps — use this Settings flow.)

   Or clear the quarantine flag from Terminal:

   xattr -dr com.apple.quarantine "/Applications/Klik PRO.app"

Continue with the same first-launch steps used by the Terminal installer.

First launch and Accessibility

1. The welcome sheet should report Accessibility — Setup required. Click Set Up Accessibility…. Klik PRO creates and starts its single combined background helper, asks the actual input helper to register the correct Klik PRO Helper.app entry, and opens System Settings → Privacy & Security → Accessibility.
2. Turn Klik PRO Helper.app on. macOS may require Touch ID or the account password; Klik PRO cannot approve this security permission itself.
3. Return to Klik PRO. The status normally updates automatically; click Recheck if macOS has not reported Granted yet.
4. A fresh v1.3.9 installation uses only local.klik-pro.input. Upgrading from an older release automatically unloads and removes the obsolete local.klik-pro.menu service.

Choosing View Mappings keeps onboarding open as a review: use the visible Back to Welcome button in the footer to return and continue setup. See docs/INSTALL.md for repair steps, logs, and the confirmed Reset Access… workflow.

Prefer to compile it yourself? See Building.

Default shortcuts

Buttons & Scroll Wheels	Klik PRO default key combination	System Default / Routing
Middle Button (scroll-wheel click)	⇧⌘7	Native middle click
Gesture Button	⇧⌘6	⌘Tab
Forward Button	⌘] (fallback)	Native Forward side-button event
Back Button	⌘[ (fallback)	Native Back side-button event
Scroll Mode Button	None — Coming soon	Native behavior (not intercepted)
Horizontal Thumb Wheel	⌘⌥← / ⌘⌥→, with ⇧⌘← / ⇧⌘→ for a supported browser override	Native horizontal scrolling

Browser Back and Forward

Default Back and Forward use the original side-button events in compatible browsers, so browser extensions cannot claim synthetic keyboard shortcuts. The recorded combo is only a fallback; custom assignments are always sent exactly as recorded.

Editing and saving shortcuts

• Recordable button shortcuts are remappable and checked for duplicate, reserved, browser-extension, and system-wide conflicts.
• The ↶ control restores a shortcut's original Klik PRO combination.
• Thumb-wheel tab switching can be enabled separately for each supported browser.
• Every state-changing toggle, shortcut field, dropdown, and reset control rechecks the red Unsaved changes note. Save clears it after a successful write; restoring the saved or opening values also clears it.

ChatGPT / Codex & Claude Quick Launch

• The independently recordable hotkeys default to ⌃⌥⌘G and ⌃⌥⌘C.
• On a new configuration, Forward opens ChatGPT / Codex and Back opens Claude while the Special Feature is on. Choosing None, another button, or turning the feature off restores the normal saved button behavior.
• Each app has a Mouse Button menu with None, Middle, Gesture, Forward, and Back. One button cannot serve both apps, and Scroll Mode remains excluded while it is Coming soon.
• A linked button mirrors its launcher hotkey. Turning the feature off, selecting None, or losing the launcher restores that button's normal mapping.
• The master toggle requires at least one supported app. Klik PRO refreshes app and launcher availability while open; unavailable existing assignments remain removable through None.

How it works

Klik PRO is one compiled input helper, automatically registered as a single per-user LaunchAgent, plus a separate settings app:

• Input helper (Sources/KlikProInput.swift) — runs from a small Klik PRO Helper.app bundle nested inside Klik PRO.app, so its Accessibility entry shows "Klik PRO Helper" with the app icon rather than a bare binary name. The helper is launched by the single local.klik-pro.input LaunchAgent, which owns the mouse's extra buttons, device-isolated Gesture sentinel, thumb wheel, persistent Klik PRO status icon, and (when Special Feature is enabled) the ChatGPT / Codex and Claude launcher icons and global hotkeys. The settings app writes this service definition automatically before setup; the helper reads the saved Special Feature setting and enables or disables the optional capabilities in the same process. Upgrades automatically unload and remove the legacy separate menu helper, if one is still installed.
• Settings app (Sources/KlikProApp.swift) — a small AppKit window with two tabs plus a one-time welcome sheet for fresh installations. The sheet explains the required Accessibility approval, the ready-to-try defaults, and where to customize them. Mappings records shortcuts for the four supported mouse controls, toggles them on/off, checks for conflicts, switches the optional Quick Launch toggle, and links ChatGPT / Codex or Claude to a supported mouse button when requested. Settings covers launch-at-login, main and Special Feature menu-icon visibility, automatic update checks, and guided Accessibility setup with live status, a manual Recheck action, and a confirmed reset that restarts onboarding. The header has a Check for Updates button (lights up when a newer GitHub release exists), and the footer links to the project's GitHub repo and its GitHub Sponsors / Ko-fi / PayPal support pages.

For browser-local conflict warnings, the settings app reads local supported-browser profile Preferences files, extracts and retains only configured extension shortcut keys, and never modifies, logs, or transmits their contents.

Everything is config-driven — see Sources/KlikProConfig.swift for the shared model both executables read, persisted to:

~/Library/Application Support/Klik PRO/config.json

The Special Feature card (ChatGPT / Codex & Claude Quick Launch) is the one optional, non-portable part — it depends on a specific dual-instance launcher setup. See docs/SPECIAL_FEATURE.md for requirements and setup.

App Profiles — in development for v2.0.0

Not in the current release. This describes planned functionality for Klik PRO v2.0.0; it is not available in v1.3.9.

The v2 development line generalizes the ChatGPT / Codex & Claude Quick Launch into App Profiles: pick a verified app and run a second, isolated instance of it — its own profile, login, and settings. Each profile gets an entry in Klik PRO's Instances menu, with an optional pinned menu-bar icon, global hotkey, and mouse-button assignment. It launches the original, untouched app against a separate profile (nothing is copied or re-signed), so each instance always runs the current source app. For an app to be Verified, testing must confirm its isolated profile retains sign-in across relaunches and app updates. The initial v2.0.0 target is a verified set of Electron/Chromium apps. The production compatibility registry remains empty until login persistence and real app-update survival are proven, so engine detection alone never enables a managed profile. See the draft design in docs/klik-pro-app-profiles-rfc.md and the roadmap in docs/klik-pro-v2.0.0-release-plan.md.

Building

./tools/check.sh
./tools/build-release.sh

The builder produces verified universal Apple Silicon + Intel DMG and ZIP downloads with an explicit macOS 13 deployment target. The DMG provides a standard drag-to-Applications layout. The input helper is packaged into a nested Klik PRO Helper.app inside Klik PRO.app and runs all background capabilities from one LaunchAgent. See docs/INSTALL.md for the full build, Gatekeeper, LaunchAgent, Accessibility, logging, and config details.

Repo layout

• Sources/ — the two Swift executables plus the shared config model.
• LaunchAgents/ — the launchd plist for the combined input and optional launcher helper.
• App/ — the app bundle's Info.plist.
• assets/ — shared frosted-white mouse master, the generated centered app icon with its overlapping PRO badge and soft bottom fade shadow, the device illustration, and the settings previews above.
• Tests/ — focused standalone regression checks.
• tools/ — verification, reproducible device/icon artwork, previews, and release packaging.
• diagnostics/ — probes for inspecting how a given mouse's buttons and thumb wheel report to macOS (a development aid, not part of the shipped app).
• docs/ — install/setup notes.
• CHANGELOG.md — user-facing release history.
• HANDOFF.md — current maintainer release state, signing custody, validation, and clean-install checklist.

Tested with

Behavior on a programmable mouse is hardware- and macOS-dependent, so these are the setups Klik PRO has been tested against:

macOS	26.5.2 (build 25F84)
Klik PRO	v1.3.9 (build 18), universal Apple Silicon + Intel build
Primary mouse	Logitech MX Master 3 (Mac edition), firmware MPM19.01_0015, connected over Bluetooth (BLE)
Additional tested mouse	Logi M650, firmware RBM16.10_0014
Vendor software / driver	None — no mouse driver or manufacturer software installed
ChatGPT / Codex desktop app (Special Feature target)	/Applications/ChatGPT.app — version 26.707.62119 (build 5211), bundle ID com.openai.codex
Claude Desktop app (Special Feature target)	/Applications/Claude.app — version/build 1.20186.1, bundle ID com.anthropic.claudefordesktop
Browsers (thumb-wheel tab switching)	Google Chrome 150.0.7871.115, Brave 150.1.92.139, Firefox 152.0.5, Safari 26.5.2
Browser Back/Forward routing	Native side-button navigation in Chrome, Brave, and Firefox; Safari fallback uses Back ⌘[ and Forward ⌘]

The Special Feature validates those exact standard desktop-app paths and bundle IDs. Its separate second-instance launcher wrappers are still required for launching, but do not count as installed desktop apps.

The generic middle and forward/back controls have also been tested with the Logi M650. Gesture isolation currently targets only the tested MX Master 3 Mac (0x046D:0xB023). Scroll Mode remains Coming soon and is not intercepted. The horizontal thumb wheel is hardware-specific — use the tools in diagnostics/ to check how your mouse reports before adapting. Product names are referenced for compatibility only (see NOTICE.md).

Adapting to a different mouse

Button naming, thumb-wheel behavior, and the device-isolated Gesture path in Sources/KlikProInput.swift were developed for the Logitech MX Master 3 Mac profile; the generic controls were additionally checked on the Logi M650. If you're adapting this for a different device, start with the tools in diagnostics/ to see how your mouse's buttons and wheel actually report to macOS before changing the mapping logic.

Scroll Mode Button: Coming soon. Klik PRO currently leaves this control untouched and preserves its native behavior.

Support development

Optional tips and other support help fund continued development, compatibility testing, and future mouse support:

• GitHub Sponsors — recurring support
• Ko-fi — quick one-time support
• PayPal — direct support

Thank you for helping keep Klik PRO improving and freely available.

Contributing

Contributions are welcome. See CONTRIBUTING.md for how to build, preview, and verify changes; please follow the Code of Conduct. To report a security issue privately, see SECURITY.md.

Trademark notice

Not affiliated with Logitech. "Logitech", "MX Master", and "Options+" are trademarks of Logitech International S.A.

References to specific compatible hardware describe compatibility only. Other product names and trademarks remain the property of their respective owners.

License

This app is open source under the MIT License. See LICENSE.