handy-keys

handy-keys is a Rust library for registering system-wide, global keyboard shortcuts that fire no matter which application currently has focus. It works across macOS, Windows, and Linux behind a single type-safe API, so you can add global hotkey support to a desktop app or background service without writing platform-specific input code.

Beyond basic registration, it supports modifier-only shortcuts like Cmd+Shift, blocks registered hotkeys from reaching other applications, parses hotkeys from human-readable strings such as “Ctrl+Alt+Space”, and exposes a low-level keyboard listener for building “record a hotkey” UI flows. All of its types implement Serde’s Serialize and Deserialize for easy persistence of user-configured shortcuts.

What You Get

• A HotkeyManager for registering and receiving system-wide hotkey events
• Cross-platform support for macOS, Windows, and Linux behind one API
• String parsing of hotkeys plus modifier-only and blocking shortcut support
• A low-level keyboard listener for hotkey-recording UIs and Serde-serializable types

Common Use Cases

• Adding global show/hide or command shortcuts to a desktop application
• Building a settings screen where users record their own hotkeys
• Persisting and reloading user-defined shortcuts via Serde serialization

Under The Hood

Architecture - The public API centers on HotkeyManager (src/manager.rs), which owns registration state and hands out hotkey events over a channel consumed via recv. Hotkey values and their Modifiers/Key components live in src/types with FromStr parsing for string forms, while src/listener.rs provides the lower-level keyboard listener used for recording flows. Platform-specific event capture and blocking are isolated under src/platform, so the cross-platform surface stays uniform while each OS backend handles native input hooks.

Tech Stack - Rust with per-OS backends for macOS, Windows, and Linux under src/platform, plus Serde derives across the public types for serialization. It builds as a standard Cargo crate; the platform layer wraps the native global-hotkey and keyboard-hook facilities of each target.

Code Quality - The crate ships a dedicated error module (src/error.rs) and a small, well-separated module layout (manager, listener, types, platform). Development activity is high and the API is versioned with type-safe constructors, though the project is still young with limited community footprint.

API Design - The quick-start is concise: build a HotkeyManager, register a Hotkey created either via the type-safe constructor or a parsed string, then loop on recv for events. Consistent naming, string parsing, and Serde support make it easy to persist user-configured shortcuts and wire up recording UIs with minimal boilerplate.