Hyprshell

Overview

Hyprshell (previously hyprswitch) is a Rust-based GUI designed to enhance window management in Hyprland. It provides a powerful and customizable interface for switching between windows using keyboard shortcuts and GUI. The application also includes a launcher for running applications, doing calculations, etc.

Features

• Window Switching: Switch between windows using keyboard shortcuts in a GUI.
• Customizable Keybindings: Define your own keybindings for window switching and GUI interactions.
• Config: Interactive config file generation for easy setup.
• Launcher Integration: Launch applications directly from the GUI, sorted by usage frequency.
• Launcher Plugins: Different plugins like Web search, actions or calculations can be enabled.
• Theming: Customize the GUI appearance (gtk4) using CSS.
• Dynamic Configuration: Automatically reloads configuration/style changes without restarting the application.
• Debug command: Many Commands to debug desktop files, icons and default applications.

Installation

From Source

gtk4 and gtk4-layer-shell[1.1.1] must be installed

cargo install hyprshell

hyprland-devel is needed for the hyprland headers (needed to build hyprland plugin) Fedora: sudo dnf install gtk4-layer-shell-devel gtk4-devel hyprland-devel Arch: sudo pacman -Sy gtk4-layer-shell gtk4

Minimum required rustc version: 1.87.0

Arch Linux

paru -S hyprshell
# or
yay -S hyprshell

NixOS

This repository contains a flake and a home-manager module for configuration.

More information can be found in the NixOS section.

Usage

Run hyprshell --help to see available commands and options.

Config generation

To generate a default configuration file, run:

hyprshell config generate

This launches an interactive prompt to set up your configuration. The generated file will be located at ~/.config/hyprshell/config.ron.

If you want to modify these settings, look at the Documentation for the config file.

Config validation

To validate your configuration file, run:

hyprshell config explain

This checks for any syntax errors or issues in your configuration file and shows a explanation of how to use hyprshell.

Initialization

Enable the systemd service (generated with hyprshell config generate) [recommended]:

systemctl --user enable --now hyprshell.service

Or add the following to your Hyprland configuration (~/.config/hypr/hyprland.conf):

exec-once = hyprshell run &

Debugging

Debug commands are provided to help troubleshoot desktop files, icons, default applications and launcher functionality, see Debug.md for detailed information about available commands and their usage.

Env Variables

• HYPRSHELL_NO_LISTENERS: Disable all config listeners (config file, css file, hyprland config, monitor count)
• HYPRSHELL_NO_ALL_ICONS: Don't check for all icons on fs and just use the ones provided by the gtk4 icon theme.
• HYPRSHELL_RELOAD_TIMEOUT: Set the timeout for reloading the config file in milliseconds (default: 1500).
• HYPRSHELL_LOG_MODULE_PATH: Add the module path to each log message. (use with -vv)
• HYPRSHELL_NO_USE_PLUGIN: Disable the use of the hyprland plugin to capture switch mode events.
• HYPRSHELL_EXPERIMENTAL: Enables experimental features (grep through the source code for "HYPRSHELL_EXPERIMENTAL" to see them)
• HYPRSHELL_RUN_ACTIONS_IN_DEBUG: Run actions from launcher plugin in debug mode

Feature Flags

• default: ["json5_config", "generate_config_command", "launcher_calc", "debug_command"]
• generate_config_command: Adds the hyprshell config generate command to interactively generate a config file.
• json5_config: Adds support for a toml config file.
• launcher_calc: Adds support for the calc plugin in the launcher.
• debug_command: Adds the hyprshell debug command to debug icons, desktop files, etc.
• config_check: (used for ci tests) Adds a command to check if the loaded config is equal to the default config or the full config. Also diables loading of configs without all values.