Skip to content

feat(hyprshell): add hyprshell window switcher with Super+Tab #893

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
shunkakinoki merged 5 commits into from
Feb 22, 2026
Merged

feat(hyprshell): add hyprshell window switcher with Super+Tab #893

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
b3f8b1e
feat(hyprshell): add hyprshell window switcher with Super+Tab
claude Feb 22, 2026
1cd3666
Revert "feat(hyprshell): add hyprshell window switcher with Super+Tab"
claude Feb 22, 2026
b7740cf
feat(packages): add hyprshell to Linux desktop packages
claude Feb 22, 2026
9af2cdc
feat(hyprshell): add exec-once and update Super+Tab binding
claude Feb 22, 2026
f139a4a
feat(hyprshell): add hyprshell config module with Super+Tab switching
claude Feb 22, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions config/default.nix
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,7 @@ in
./gtk
./hyprland
./hyprpanel
./hyprshell
./rofi
]
else
Expand Down
1 change: 1 addition & 0 deletions config/hyprland/default.nix
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,7 @@ in
extraConfig = ''
plugin = ${hyprexpoPlugin}/lib/libhyprexpo.so
exec-once = ${pkgs.hyprpanel}/bin/hyprpanel
exec-once = ${pkgs.hyprshell}/bin/hyprshell run &

@coderabbitai coderabbitai Bot Feb 22, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🛠️ Refactor suggestion | 🟠 Major

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Search for flake.nix and check its hyprshell configuration
fd -e nix "flake.nix" -x cat {} -n \; 2>/dev/null

Repository: shunkakinoki/dotfiles

Length of output: 9025

🏁 Script executed:

#!/bin/bash
# Also check if there's any hyprland input defined in flake.nix
fd -e nix "flake.nix" -x grep -n "hyprland\|hyprshell" {} \; 2>/dev/null

Repository: shunkakinoki/dotfiles

Length of output: 47

🏁 Script executed:

#!/bin/bash
# Check the structure of the repo to understand the context
git ls-files | grep -E "(flake|hyprland)" | head -20

Repository: shunkakinoki/dotfiles

Length of output: 361

Add explicit hyprland version pinning for hyprshell to prevent header mismatch crashes.

Hyprshell builds a Hyprland plugin at runtime which requires C headers matching the running Hyprland instance. Since flake.nix doesn't currently pin hyprland, hyprshell may receive headers from a different version than your system runs, causing runtime crashes.

Add a hyprshell input that follows your hyprland version (or use nixpkgs-unstable consistently):

hyprshell = {
  url = "github:H3rmt/hyprshell?ref=hyprshell-release";
  inputs.hyprland.follows = "nixpkgs-unstable";
};

If version pinning isn't immediately practical, set HYPRSHELL_NO_USE_PLUGIN=1 as a temporary workaround.

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@config/hyprland/default.nix` at line 18, The exec-once line launches
hyprshell and can cause runtime crashes due to hyprshell building a plugin
against mismatched Hyprland headers; add an explicit hyprshell input that
follows your pinned hyprland version (so hyprshell uses the same hyprland
headers) — e.g. create an input named hyprshell with inputs.hyprland.follows set
to the same channel as your hyprland pin — or, as a temporary workaround, ensure
the environment variable HYPRSHELL_NO_USE_PLUGIN=1 is exported before the
exec-once = ${pkgs.hyprshell}/bin/hyprshell run & invocation to disable plugin
building.

⚠️ Potential issue | 🟠 Major

🧩 Analysis chain

🌐 Web query:

hyprshell config file auto-detection TOML RON ~/.config/hyprshell

💡 Result:

Hyprshell does not auto-detect between TOML and RON.

  • Default config path: ~/.config/hyprshell/config.ron (loaded on startup and auto-reloaded on change). You can override the path with -c. Hyprshell also supports .json and .json5 config files. [1]
  • TOML status: TOML was dropped (it couldn’t represent None values). Hyprshell added a TOML → RON migration around v4.6.0. [2]

What to do: put your config at ~/.config/hyprshell/config.ron (or point Hyprshell at a specific file via hyprshell -c /path/to/config.ron).

Sources: [1] [2]

🌐 Web query:

hyprshell run command default config file location format

💡 Result:

  • Default config file path (used by hyprshell run): ~/.config/hyprshell/config.ron.[1][2]
  • Default format: RON (.ron).[1][2]
  • Other supported config formats: .toml and .json / .json5.[1]
  • Override config path: pass -c <path>.[1]

Sources: [1] [2]

🌐 Web query:

hyprshell github repository config loading behavior

💡 Result:

Hyprshell’s config-loading behavior (per the upstream GitHub repo):

  • Default config path: ~/.config/hyprshell/config.ron. You can override this with the -c CLI argument. The config is loaded at startup and auto-reloaded when the file changes. [1]
  • Supported config formats: .ron (default); the docs also state you can use .json(5) and .toml formats (depending on build/features/version). [1]
  • Config versioning/migrations: the config has a version field; on load, Hyprshell checks it to migrate the file if needed. [1]
  • Reload/watch behavior controls: Hyprshell has file/listener-based hot reload; you can disable listeners with HYPRSHELL_NO_LISTENERS, and adjust the reload debounce/timeout via HYPRSHELL_RELOAD_TIMEOUT (default 1500 ms). [2]
  • CSS is similar: default CSS at ~/.config/hyprshell/styles.css, overridable with -s, also loaded at startup and reloaded on change. [1]

Sources:
[1] Hyprshell docs/CONFIGURE.md (raw)
[2] Hyprshell README.md (raw)

hyprshell run requires an explicit config path — config.toml will be silently ignored.

Hyprshell defaults to ~/.config/hyprshell/config.ron (RON format) and does not auto-detect .toml files. Without a -c flag pointing to your config.toml, hyprshell starts with built-in defaults, leaving modifier as "alt" instead of "super" — breaking Super+Tab.

Choose one fix:

  1. Rename to RON (the default format):

    • Move config/hyprshell/config.toml → config/hyprshell/config.ron
    • Update the xdg configFile key accordingly

  2. Or pass -c explicitly:

Option 2 — point to TOML via -c flag 
-      exec-once = ${pkgs.hyprshell}/bin/hyprshell run &
+      exec-once = ${pkgs.hyprshell}/bin/hyprshell -c ${config.xdg.configHome}/hyprshell/config.toml run &
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
exec-once = ${pkgs.hyprshell}/bin/hyprshell run &
exec-once = ${pkgs.hyprshell}/bin/hyprshell -c ${config.xdg.configHome}/hyprshell/config.toml run &
🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@config/hyprland/default.nix` at line 18, The exec-once invocation uses
"${pkgs.hyprshell}/bin/hyprshell run &" which ignores your TOML and falls back
to RON defaults; fix by either renaming the config file to the hyprshell default
(move config/hyprshell/config.toml → config/hyprshell/config.ron and update the
xdg configFile key to point to config.ron) or by keeping the TOML and changing
the exec-once command to include an explicit config flag (invoke hyprshell with
-c /path/to/config.toml) so hyprshell loads your intended modifier ("super").

''
+ builtins.readFile ./hyprland.conf;
};
Expand Down
2 changes: 1 addition & 1 deletion config/hyprland/hyprland.conf
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -258,7 +258,7 @@ bind = $mod SHIFT, F, togglefloating,
bind = CTRL ALT SHIFT SUPER, F, exec, hyprctl --batch "dispatch movetoworkspace empty; dispatch fullscreen 0"
bind = SUPER CTRL, F, fullscreen, 1
bind = $mod SHIFT, Q, exec, hyprpanel toggleWindow power-menu
bind = $mod, TAB, hyprexpo:expo, toggle
# hyprshell handles Super+Tab / Super+Shift+Tab window switching

# Focus (vim keys)
bind = $mod, H, movefocus, l
Expand Down
7 changes: 7 additions & 0 deletions config/hyprshell/config.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
version = 1

[windows]
scale = 8.0

[windows.switch]
modifier = "super"
7 changes: 7 additions & 0 deletions config/hyprshell/default.nix
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
{ pkgs, ... }:
{
xdg.configFile."hyprshell/config.toml" = {
source = ./config.toml;
force = true;
};
}
1 change: 1 addition & 0 deletions home-manager/packages/default.nix
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -135,6 +135,7 @@ with pkgs;
hypridle
hyprlock
hyprpicker
hyprshell

Copilot AI Feb 22, 2026

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The PR description states "Install hyprshell from flake input", but there is no corresponding flake input for hyprshell added to flake.nix. This means the package will be pulled from nixpkgs directly rather than from a dedicated flake input. If hyprshell requires a specific version or custom build not available in nixpkgs, you'll need to add it as a flake input in flake.nix and reference it appropriately (similar to how agenix is used on line 10).

Copilot uses AI. Check for mistakes.

Copilot AI Feb 22, 2026

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The PR description states that Super+Tab will be configured to use hyprshell's switch mode, replacing the previous hyprexpo binding. However, this PR only adds the package - it doesn't include the necessary configuration changes. The hyprland configuration file (config/hyprland/hyprland.conf line 261) still has the binding "bind = $mod, TAB, hyprexpo:expo, toggle" which needs to be updated to use hyprshell instead. Additionally, any hyprshell configuration for the switch mode needs to be added.

Suggested change
hyprshell

Copilot uses AI. Check for mistakes.
hyprshot
hyprsunset
libnotify
Expand Down
Loading