QMKonnect
Cross-platform window activity notifier for QMK keyboards
Project maintained by dabstractor
Hosted on GitHub Pages — Theme by mattgraham
Usage Guide
QMKonnect runs in the background, automatically detecting window changes and communicating with your QMK keyboard. Here’s how to start, stop, and manage the application.
Starting QMKonnect
Windows
- Automatic startup: If installed via MSI, starts automatically with Windows
- Manual start: Find “QMKonnect” in Start Menu or double-click the desktop shortcut
- System tray: Look for the QMKonnect icon in your system tray when running
Linux
- Automatic startup:
systemctl --user enable qmkonnect (runs on login)
- Manual start:
qmkonnect or systemctl --user start qmkonnect
- Check status:
systemctl --user status qmkonnect
macOS
- Manual start: Launch QMKonnect.app from Applications folder
- Menu bar: Look for the QMKonnect icon in your menu bar when running
Stopping QMKonnect
Windows
Right-click the system tray icon and select “Quit”
Linux
systemctl --user stop qmkonnect
macOS
Quit from the menu bar icon or application menu
Auto-Start on Boot
Windows
Auto-start is automatically configured when using the MSI installer. To disable:
- Open Task Manager → Startup tab
- Find “QMKonnect” and disable it
Linux
# Enable auto-start on login
systemctl --user enable qmkonnect
# Disable auto-start
systemctl --user disable qmkonnect
macOS
- System Preferences → Users & Groups → Login Items
- Add QMKonnect.app to start automatically
How It Works
Once running, QMKonnect automatically:
- Monitors window changes - detects when you switch between applications
- Extracts window information - gets the application name and window title
- Sends data to your keyboard - your QMK firmware receives this information
- Triggers layer changes - your keyboard responds based on your configuration
The magic happens in your QMK firmware configuration - QMKonnect just provides the window information your keyboard needs to make intelligent decisions.
System Integration
Windows
- System tray integration: Right-click the tray icon for settings and status
- Runs in background: Minimal resource usage
- Auto-updates: Receives automatic updates when available
Linux
- Systemd service: Integrates with your system’s service management
- Hyprland support: Currently supports Hyprland window manager only
- Lightweight: Designed for minimal system impact
macOS
- Menu bar integration: Access settings and status from the menu bar
- Accessibility permissions: Requires one-time setup for window monitoring
- Native app bundle: Standard macOS application behavior
What QMKonnect Enables
With QMKonnect running, your keyboard becomes context-aware:
- Development environments: Automatically switch to coding-focused layouts when opening IDEs
- Gaming: Enter gaming mode when launching games
- Browser work: Activate browser-specific shortcuts and layers
- Terminal usage: Switch to terminal-optimized layouts
- Media control: Enable media keys when using music/video applications
The behavior is entirely customized in your QMK firmware - QMKonnect just provides the window information your keyboard needs.
Status and Monitoring
Check if QMKonnect is Running
- Windows: Look for the QMKonnect icon in your system tray
- Linux:
systemctl --user status qmkonnect
- macOS: Look for the QMKonnect icon in your menu bar
Verify Keyboard Connection
If your layers aren’t switching as expected:
- Check that QMKonnect shows as “connected” in the system tray/menu bar
- Verify your QMK firmware is properly configured with the qmk-notifier module
- Test by switching between different applications
For detailed troubleshooting, see the troubleshooting guide.
Next Steps