hyprstack

English · 日本語

hyprstack is a Hyprland plugin that adds a stable per-workspace window stack.

Hyprland already has focus history, z-order, layout order, and other ordering concepts. hyprstack provides a separate stack model for keybind-friendly next, prev, last, and swap operations.

Features

• Keeps a stable order per workspace
• Tracks the current window and the last-focused window
• Focuses next, prev, and last from keybinds
• Swaps the current window with its neighbor
• Exposes stack state through hyprctl

Versioning

hyprstack versions use <tested Hyprland version>.<build>. For example, 0.56.0.1 means build 1, tested with Hyprland 0.56.0.

Installation

hyprstack is intended to be managed with hyprpm.

hyprpm add https://github.com/ver-1000000/hyprstack.git
hyprpm enable hyprstack

Load hyprpm plugins when Hyprland starts.

Lua:

hl.on("hyprland.start", function()
    hl.exec_cmd("hyprpm reload")
end)

.conf:

exec-once = hyprpm reload

After Updating Hyprland

hyprstack is built against Hyprland's internal plugin API. After every Hyprland update, run the following from the running Hyprland session before relying on the plugin.

hyprpm update
hyprpm reload
hyprctl plugin list

If a build fails, inspect hyprpm update -v: unsupported API changes, missing dependencies, and build environment problems can all cause failures. Do not force-load the previous binary.

Dependency ABI versions come from pkg-config at build time, since Hyprland's cached version.h can describe dependencies from an older build. The Hyprland commit check and rejection of mismatched ABIs remain enabled.

Keybind Examples

Lua configs can call stack actions through hyprctl hyprstack.

hl.bind(mainMod .. " + TAB", hl.dsp.exec_cmd("hyprctl hyprstack focus last"))
hl.bind(mainMod .. " + J", hl.dsp.exec_cmd("hyprctl hyprstack focus next"))
hl.bind(mainMod .. " + K", hl.dsp.exec_cmd("hyprctl hyprstack focus prev"))

hl.bind("SHIFT + " .. mainMod .. " + J", hl.dsp.exec_cmd("hyprctl hyprstack swap next"))
hl.bind("SHIFT + " .. mainMod .. " + K", hl.dsp.exec_cmd("hyprctl hyprstack swap prev"))

.conf configs can call dispatchers directly.

bind = $mainMod, TAB, stackfocus, last
bind = $mainMod, J, stackfocus, next
bind = $mainMod, K, stackfocus, prev

bind = SHIFT $mainMod, J, stackswap, next
bind = SHIFT $mainMod, K, stackswap, prev

Query

Use these commands for scripts and debugging.

hyprctl hyprstack stack list
hyprctl hyprstack stack current
hyprctl hyprstack stack around

stack around returns stable-order prev / next and focus-history-based last.

Floating Stack

hyprstack only handles window order and focus/swap actions. Whether windows float and how large they are is Hyprland config responsibility.

For floating stack workflows, opening normal floating windows at a large size is safer than using maximize / fullscreen.

hl.window_rule({
    name = "floating-stack",
    match = { class = ".*" },
    float = true,
    center = true,
    size = { "monitor_w * 0.96", "monitor_h * 0.94" }, -- leave some room for bars and outer margins
})