hyprKCS

A fast, lightweight, and graphical keybind manager for Hyprland, built with Rust and GTK4.

Overview

hyprKCS provides a simple and intuitive interface to view, edit, and manage your Hyprland keybinds. It automatically parses your hyprland.conf (and any sourced files), detects conflicts, and allows you to make changes safely.

Features

• Native GTK4 Interface: Integrates seamlessly with your system theme, supporting both light and dark modes via Libadwaita.
• Real-time Fuzzy Search: Instantly find keybinds as you type.
• Advanced Search Syntax: Use tags like mod:, key:, action:, or desc: to filter keybinds with precision.
• Visual Keyboard Map: Interactive layout to visualize used and available keys for any modifier combination. Supports multiple physical layouts including ANSI, ISO, JIS, ABNT2, or Hungarian.
• Category Filtering: Filter binds by common categories like Workspace, Window, Media, or Custom scripts.
• Conflict Detection: Automatically identifies and highlights duplicate keybinds, resolving Hyprland variables (e.g., $mainMod) for accuracy.
• Broken Bind Detection: Automatically validates exec and execr commands, flagging keybinds that point to missing executables or scripts with a red exclamation mark.
• Bind Flags Support: Full support for Hyprland's specialized bind flags like binde (repeat), bindl (locked), bindr (release), and more, selectable via a dropdown in the editor.
• Mouse Button & Scroll Support: Easily bind actions to mouse buttons (Left/Right/Middle/Side), scroll wheel events, and dragging actions (bindm) using a dedicated UI mode.
• Full Keybind Management: Add, edit, and delete keybinds directly from the UI. Changes are written back to the correct configuration files.
• Configuration Backup: Create a timestamped backup of your configuration files with a single click or set the automatic backup behavior in the settings (it's set to true by default).
• Interactive Restore: Easily browse previous backups and restore your entire configuration tree with a single click.
• Visual Diffs: Compare any backup with your current configuration using a Git-style color-coded diff view before restoring.
• Conflict Resolution Wizard: A guided tool to help resolve duplicate keybinds one by one.
• Bulk Replace: Find and replace modifiers, keys, or commands across multiple keybinds at once, with a live case-insensitive preview.
• Smart Autocomplete: Suggests valid Hyprland dispatchers as you type.
• Macro Builder (Chain Actions): Visually create complex keybinds that execute multiple dispatchers in sequence (e.g., move window AND switch workspace).
• Favorites: Pin frequently used keybinds for quick access.
• Input Device Configuration: Manage your input { ... } block (layout, sensitivity, repeat rate) directly from the settings.
• Settings Editor: Configure UI, backup behavior, and appearance directly within the app.
• Automatic Backups: Automatically backup your configuration on every change, with optional retention limits.
• Command-Line Interface: Quickly search and print keybinds from the terminal.
• Gesture Configuration (Hyprland v0.51+): Dedicated interface to configure workspace swipe gestures using the new gesture = ... syntax, replacing the deprecated gestures { ... } block.
• Keybind Exporting: Export your keybinds to a simple markdown file for easy sharing or documentation.

Installation

From AUR (Arch Linux)

yay -S hyprkcs-git

From Crates.io

cargo install hyprKCS

From Nix

nix run github:kosa12/hyprKCS

From Source

Ensure you have rust, cargo, and gtk4 development headers installed.

Using Make (Recommended):

git clone --depth=1 https://github.com/kosa12/hyprKCS.git
cd hyprKCS
make
sudo make install

Using Cargo directly:

git clone --depth=1 https://github.com/kosa12/hyprKCS.git
cd hyprKCS
cargo build --release
# The binary will be at ./target/release/hyprkcs

Configuration

You can customize the appearance and behavior of hyprKCS by creating a configuration file at ~/.config/hyprkcs/hyprkcs.conf. If a value is invalid or omitted, a default will be used.

# Window dimensions
width = 1000px
height = 800px

# Appearance
opacity = 0.95
fontSize = 10pt
borderSize = 2px
borderRadius = 10px
alternatingRowColors = true
shadowSize = 0 4px 24px rgba(0,0,0,0.4)

# UI Elements
showSubmaps = false
showArgs = true
showFavorites = true
defaultSort = mods
keyboardLayout = ANSI
showDescription = true

# Behavior
autoBackup = true
maxBackupsEnabled = true
maxBackupsCount = 20

# Spacing
monitorMargin = 20px
rowPadding = 5px

Usage

Graphical Interface

Launch hyprkcs from your application menu or terminal to open the main window.

Keyboard Shortcuts

Advanced Search Syntax The search bar supports specific tags to filter results:

• mod:<value> / mods:<value>: Filter by modifiers (e.g., mod:super).
• key:<value>: Filter by key (e.g., key:return).
• action:<value> / disp:<value>: Filter by dispatcher/action (e.g., action:exec).
• arg:<value>: Filter by arguments (e.g., arg:volume).
• desc:<value>: Filter by description (e.g., desc:screenshot).

Example: mod:super action:exec firefox finds all Super-bound execution commands for Firefox.

Visual Keyboard Map Click the keyboard icon in the top toolbar to open an interactive keyboard layout.

• Select Modifiers: Toggle SUPER, SHIFT, CTRL, or ALT to see which keys are bound to those modifiers.
• Color Coding: Keys bound to actions are highlighted. Hover over them to see the exact dispatcher and arguments.
• Find Free Keys: Easily spot unhighlighted keys to find available shortcuts for your configuration.
• Multiple Layouts: Switch between ANSI, ISO, JIS, ABNT2, or Hungarian layouts in the Settings to match your physical hardware.

Input Configuration Manage your system's input behavior without manual text editing.

• Keyboard Settings: Set your layout code, variant, options (XKB), repeat rate, and delay.
• Mouse/Touchpad: Adjust mouse sensitivity (-1.0 to 1.0) and window focus behavior (Follow Mouse).
• Direct Save: Changes are written directly to your hyprland.conf input block.

Macro Builder Create complex multi-step actions without writing scripts.

1. Click the "Add Keybind" button.
2. Enable Macro mode using the macro toggle/switch in the keybind editor.
3. Use the visual builder to add steps (e.g., Step 1: exec -> grim, Step 2: exec -> notify-send "Screenshot taken").
4. hyprKCS automatically formats this into a Hyprland-compatible macro command using bash and hyprctl (e.g., bind = ..., exec, bash -c "hyprctl dispatch exec grim; hyprctl dispatch exec 'notify-send \"Screenshot taken\"'").

Bulk Replace Quickly update multiple keybinds at once (e.g., swapping SUPER for ALT or changing your terminal emulator).

1. Click the "Bulk Replace" icon in the top toolbar.
2. Select the target field (Modifiers, Key, Dispatcher, or Arguments).
3. Enter the text to find and the replacement text. The search is case-insensitive.
4. Review the matches in the "Preview" list. Hover over any item to see the full keybind definition.
5. Click "Apply Changes" to update all matches. A backup is automatically created before applying.

Backup and Restore Safely manage your configuration versions.

• Full Tree Backup: Backs up your entire ~/.config/hypr directory recursively, preserving folder structures and external scripts.
• Interactive Restore: Access the Restore menu from Settings to see all available timestamped backups.
• Visual Diffs: Before restoring, click "View Diff" to see a color-coded comparison (additions/removals) between the backup and your current files.
• One-Click Recovery: Restore your entire setup instantly if a change breaks your workflow.

Command-Line Interface

hyprKCS also includes a CLI for quick lookups and scripting.

• Print all keybinds:

  hyprkcs --print
  # Short: hyprkcs -p
  

• Search for a keybind:

  hyprkcs --search "firefox"
  # Short: hyprkcs -s "firefox"
  

• Advanced search via CLI:

  hyprkcs --search "mod:super action:exec"
  

• Use a custom config file:

  hyprkcs --config ~/.config/hypr/custom.conf
  # Short: hyprkcs -c ~/.config/hypr/custom.conf
  

• System Check: Check your system environment for compatibility issues:

  hyprkcs --doctor
  

Troubleshooting

System Compatibility Check

If the application fails to start or keybinds aren't saving, run the doctor command to diagnose your environment:

hyprkcs --doctor

This tool verifies:

• Config Access: Checks if hyprland.conf is found and writable.
• Dependencies: Confirms GTK4/Libadwaita runtime versions.
• Hyprland IPC: Ensures hyprctl can communicate with the compositor.
• Input Devices: Lists detected keyboards and guesses physical layout (ANSI/ISO).
• Backups: Verifies backup directory permissions.

AUR Installation Issues (yay)

If you encounter errors during installation via yay (such as "cannot stat" or build failures after a package update), it may be due to a stale cache. Try clearing the cache and installing again:

rm -rf ~/.cache/yay/hyprkcs-git
yay -S hyprkcs-git

GPG Key Import Issues

If you encounter errors like gpg: keyserver receive failed when installing from the AUR, you may need to import the required PGP key manually.

Try importing from the Ubuntu keyserver:

gpg --keyserver keyserver.ubuntu.com --recv-keys D2059131FDE2EECC7C90A549F2CB939C8AA67892

Or from OpenPGP:

gpg --keyserver keys.openpgp.org --recv-keys D2059131FDE2EECC7C90A549F2CB939C8AA67892

Contributing

Contributions are welcome. Please see CONTRIBUTING.md for guidelines.

License

This project is licensed under the MIT License. See the LICENSE file for details.