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.
• 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.
• 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.
• 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

Compatibility

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, repeat rate, and delay.
• Mouse/Touchpad: Adjust mouse sensitivity and window focus behavior (Follow Mouse).
• Direct Save: Changes are written directly to your hyprland.conf input block.

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.

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.