Hyprscratch

Hyprscratch makes scratchpads in Hyprland painless in a well-integrated and flexible way.

Features

• Scratchpads are part of your current workspace by default.
• Can be configured in hyprland.conf or a dedicated configuration file.
• Makes special workspace scratchpads simpler to set up.
• Many options to easily tweak behaviour of scratchpads.
• Event listeners to automate scratchpad management.
• Allows cycling and restoring previous scratchpads.
• Supports many scratchpads active at the same time.

Installation

Crates:

cargo install hyprscratch

AUR:

paru -S hyprscratch

Nix:

Nix installation options can be found here.

Usage

Basic

In hyprland.conf:

# Start the hyprscratch daemon
exec-once = hyprscratch init [DAEMON_OPTIONS]

# Configure scratchpads
bind = $mainMod, $KEY, exec, hyprscratch $CLIENT_TITLE "$HYPRLAND_EXEC_COMMAND" [SCRATCHPAD_OPTIONS]

Example scratchpad configuration:

exec-once = hyprscratch init clean eager

bind = $mainMod, b, exec, hyprscratch btop "[size 70% 80%] alacritty --title btop -e btop" persist pin
bind = $mainMod, f, exec, hyprscratch "Mozilla Firefox" firefox special monitor 1

Optional Configuration File

If you consider it more convenient to use a separate configuration file, you can create a ~/.config/hypr/hyprscratch.conf or ~/.config/hyprscratch/config.conf and configure scratchpads in the following way:

# Optional globals that apply to all scratchpads
daemon_options = clean
global_options = special
global_rules = size 90% 90%

scratchpad1 {
    # Mandatory fields
    command = command

    # At least one is mandatory, title takes priority
    title = title
    class = class

    # Optional fields
    options = option1 option2 option3
    rules = rule1;rule2;rule3
}

# Groups that manage multiple scratchpads are also supported
group:group1 {
    # Add the already defined scratchpad to the group
    name = scratchpad1

    # Define a new scratchpad that can also be used independently
    scratchpad2 {
        title = title
        command = command
    }
}

And in hyprland.conf, using the given name:

exec-once = hyprscratch init

bind = $mainMod, t, hyprscratch toggle scratchpad1
bind = $mainMod, s, hyprscratch show scratchpad1
bind = $mainMod, h, hyprscratch hide scratchpad1

bind = $mainMod, g, hyprscratch toggle group1

Using a configuration file can be combined with normally configured scratchpads.

Options:

Daemon options:

• clean: automatically hides all scratchpads on workspace change.

• spotless: automatically hides all scratchpads on focus change.

• eager: spawns all scratchpads hidden on start.

• no-auto-reload: does not reload the configuration when the files are modified.

• config </path/to/config>: specify a path to the configuration file.

Scratchpad options:

• ephemeral: closes the scratchpad when it is hidden.

• persist: prevents the scratchpad from getting replaced when a new one is summoned.

• cover: prevents the scratchpad from replacing an already active one.

• sticky: prevents the scratchpad from being hidden by clean.

• shiny: prevents the scratchpad from being hidden by spotless.

• lazy: prevents the scratchpad from being spawned by eager.

• show: only creates or brings up the scratchpad.

• hide: only hides the scratchpad if active.

• poly: toggles all scratchpads with the same title simultaneously.

• pin: keeps the scratchpad active through workspace changes.

• tiled: spawns the scratchpad tiled instead of floating.

• monitor <id|name>: restricts the scratchpad to a specific monitor.

• group <name>: adds the scratchpad to the specified group.

• special: uses the special workspace. Does not work with all other options.

Extra subcommands:

• toggle <name>: toggles the scratchpad with the given name.

• show <name>: shows the scratchpad with the given name.

• hide <name>: hides the scratchpad with the given name.

• cycle [normal|special]: cycles between scratchpads (optionally only normal or special ones) in the order they are defined in the configuration file.

• previous [show|hide]: toggles the last used scratchpad that is not currently active.

• hide-all: hides all scratchpads, useful mostly when stacking multiple of them.

• kill-all: closes all scratchpad clients that are open.

• reload [config]: re-parses the configuration file without restarting the daemon.

• menu [fzf|rofi] [show|hide]: spawns a menu to search through and trigger scratchpads (rofi for keybinds, fzf for cli).

• get-config: prints out the parsed configuration.

• kill: kills the hyprscratch daemon.

• logs: shows logs.

Other Relevant Information

The title of a scratchpad has to be either the initialTitle or initialClass field of the client, which can be found with hyprctl clients. An incorrect title results in the scratchpad not being hidden and a new one being spawned every time.

Terminal applications often all use the title of the terminal emulator. Usually the title can be set with the --title flag to differentiate them.

Multiple commands can be bound to a single scratchpad by separating them with ? (e.g. hyprscratch title "[rules1] command1 ? [rules2] command2"). Can be useful with the poly option to allow different window rules for each client.

If there are multiple clients with the same title, the program just grabs the first one it finds. This usually results in cycling between them, every time one is shown.