2026-10-16 14:28:25 -04:00
2026-09-11 15:09:06 -04:00
2026-09-23 10:17:06 -04:00
2026-09-21 09:59:21 -04:00
2026-09-21 09:59:21 -04:00
2026-09-12 19:22:41 -04:00
2026-10-16 14:28:25 -04:00
2026-10-02 23:59:11 -04:00
tmp
2026-10-02 23:59:40 -04:00
2026-09-10 22:41:58 -04:00
2026-09-21 09:59:21 -04:00
2026-09-21 09:59:21 -04:00
2026-09-14 13:19:41 -04:00
2026-09-12 19:22:41 -04:00
2026-09-14 13:19:41 -04:00
2026-10-02 23:59:11 -04:00
2026-10-03 00:07:37 -04:00
2026-10-16 14:28:25 -04:00
2026-10-16 14:28:25 -04:00
2026-10-16 14:28:25 -04:00

skygqts

A small collection of desktop tools built with Quickshell, for Wayland compositors that speak niri or Hyprland.

It ships three apps:

  • app-carousel — a full-screen launcher carousel. Apps sit in a row; the one in the middle is selected. Configure it with a JSON file.
  • workspace-manager — a workspace overview. A carousel of workspace cards (with a live list of their windows), a bar for renaming the current workspace, and a 3D "window loop" for picking a window.
  • workspace-badge — a small box in each bottom corner of every monitor showing the active workspace's name and color. Click one to rename the workspace or pick a color.

Everything here is QML. Talking to the compositor goes through its command line tools (niri msg, hyprctl), so the code is the same on both.


Install

The repository is a flake that exposes a package and an overlay. Replace <flake-url> below with wherever you host it (a Git URL, or . when you are inside a checkout).

# From a checkout of this repo
nix build .#skygqts      # build the package
nix run .#skygqts -- workspace-manager --daemon

# From a remote flake
nix run <flake-url>

# Add to a system config, inside your flake's inputs
inputs.skygqts.url = "<flake-url>";

# then, in a NixOS or Home Manager module
nixpkgs.overlays = [ inputs.skygqts.overlays.default ];
# environment.systemPackages = [ pkgs.skygqts ];

The package installs one binary, skygqts, which is the Nushell CLI described below.

From source

You need these programs on your PATH:

Program Why
quickshell (qs) Runs the QML
nushell (nu) Runs the skygqts CLI
curl Downloads remote app images when caching is on
grim Takes window snapshots on Hyprland
niri or hyprctl Provided by your compositor, used to read/move windows and workspaces

You can skip the Nushell CLI entirely and run the QML directly:

# app carousel
SKYG_APP_CAROUSEL=/path/to/app-carousel.json qs -p ./app-carousel

# workspace manager
qs -n -p ./workspace-manager

# workspace badge
qs -n -p ./workspace-badge

What's available

CLI

skygqts is a Nushell script (skygqts.nu). Its subcommands:

Command What it does
skygqts carousel <config> Opens the app carousel with the given JSON config
skygqts workspace-manager Opens the workspace carousel
skygqts workspace-manager --daemon Same, but detached from the terminal
skygqts workspace-manager --config <file> Same, with a JSON config file
skygqts workspace-manager toggle Toggles the workspace carousel (also closes it)
skygqts workspace-manager goto Opens the workspace carousel
skygqts workspace-manager windows Opens the window loop for the focused workspace
skygqts workspace-manager rename Opens the carousel with the name field focused
skygqts workspace-badge Shows the workspace badge on every monitor
skygqts workspace-badge --daemon Same, but detached from the terminal
skygqts workspace-badge edit Opens the badge editor on the focused monitor

The last four talk to an already-running workspace manager over IPC, so start it as a daemon first (for example from your compositor's startup):

skygqts workspace-manager --daemon --config ~/.config/skygqts/workspace-manager.json

Then bind them in your compositor, e.g.:

# Hyprland
bind = SUPER, TAB, exec, skygqts workspace-manager toggle
bind = SUPER, G,   exec, skygqts workspace-manager windows
bind = SUPER, N,   exec, skygqts workspace-manager rename

The same calls are available over Quickshell IPC if you prefer not to use the CLI:

qs ipc -p ./workspace-manager call workspace toggle
qs ipc -p ./workspace-manager call workspace goTo
qs ipc -p ./workspace-manager call workspace openWindowSelection
qs ipc -p ./workspace-manager call workspace openWorkspaceRename

qs ipc -p ./workspace-badge call badge edit

qs ipc -p ./app-carousel call launcher toggle
qs ipc -p ./app-carousel call launcher open
qs ipc -p ./app-carousel call launcher close

Environment variables

Variable Used by Meaning
SKYG_APP_CAROUSEL app-carousel Path to its JSON config
SKYG_WORKSPACE_MANAGER workspace-manager Path to its JSON config (optional)
NIRI_SOCKET workspace-manager Set by niri; used to detect the compositor
HYPRLAND_INSTANCE_SIGNATURE workspace-manager Set by Hyprland; used to detect the compositor
XDG_RUNTIME_DIR workspace-manager Where window snapshots are written

skygqts carousel ~/.config/skygqts/app-carousel.json

A full-screen overlay with one card per app. Move left and right, press Enter to launch the selected one.

Config

See example.json. Top level:

Field Type Default Meaning
apps array — The apps. Required.
enableCacheFolder bool false Cache remote images on disk
backgroundMode bool false Keep the carousel on the background layer (see below)
autoStart bool — Accepted by the parser but has no effect in the current code

Each entry in apps:

Field Type Default Meaning
name string — Label under the icon. Required.
image string — Icon name or image path/URL. Required.
isIcon bool false Treat image as a theme icon name instead of a picture
dims [width, height] [100, 100] Icon size. Only allowed when isIcon is true
exec string[] — Command and arguments to run
hyprlandDispatch string — Hyprland dispatch to run instead of exec

Specify exactly one of exec or hyprlandDispatch.

image resolution:

  • isIcon: true looks the name up in the icon theme (e.g. "chromium", "system-settings").
  • Otherwise it accepts an http(s):// or file:// URL, a ~/… path, or a path relative to the config file's own directory.

Example:

{
  "enableCacheFolder": true,
  "apps": [
    {
      "name": "Chromium",
      "image": "chromium",
      "isIcon": true,
      "exec": ["chromium"]
    },
    {
      "name": "Netflix",
      "image": "https://assets.nflxext.com/us/ffe/siteui/common/icons/nficon2023.ico",
      "hyprlandDispatch": "exec chromium --app=https://www.netflix.com"
    }
  ]
}

When enableCacheFolder is true, remote images are downloaded with curl into ~/.config/skygqts/carousel-image-cache and reused from there.

Background mode

With "backgroundMode": true the carousel lives on the bottom layer and is always visible — it behaves like a wallpaper you can launch from. The toggle/open IPC calls then dispatch workspace empty on Hyprland instead of showing a window, and Escape/clicking no longer closes it.

Keys

Key Action
Left / Right Move the selection
Enter Launch the selected app
Escape Close (unless in background mode)
Scroll Move the selection horizontally

Workspace manager

skygqts workspace-manager --config ~/.config/skygqts/workspace-manager.json

It detects your compositor from the environment (niri or hyprland) and shows one column of workspace cards per monitor, each card listing the workspace's windows. From there you can focus a workspace, rename it, or open a window loop.

Config

The config file is optional. Anything missing or malformed falls back to the default below, and the file is watched for changes. See workspace-manager.example.json.

Field Type Default Meaning
keys.rename string "Ctrl+N" Key that focuses the name field
keys.windows string "Tab" Key that opens the window loop
hints.show bool true Show the small key hints
hints.rename string "{key}: to switch here" Hint text
hints.windows string "{key}: to see windows" Hint text
hints.exitWindows string "{key} or Esc: to exit window carousel" Hint text

In any hint, {key} is replaced by the matching key. Keys are written as modifiers plus one key, joined by +. Recognised modifiers are Ctrl (Control), Alt, Shift, and Meta (Super); the key may be a letter, a digit, F1–F12, Space, or Tab (for example Ctrl+N, Super+Space).

Keys

Carousel

Key Action
Up / Down Previous / next workspace on this monitor
Left / Right Previous / next monitor
Enter Focus the selected workspace
Escape Close without switching
keys.rename (default Ctrl+N) Focus the name field
keys.windows (default Tab) Open the window loop
Scroll Vertical = workspaces, horizontal = monitors

Renaming

Key Action
Enter Apply the new name
Escape Leave without renaming

Window loop

Key Action
Left / Right Previous / next window
Enter Focus the selected window
Up / Down Previous / next workspace and show its windows
Escape Fold back to the carousel (closes entirely if opened via windows)
keys.windows (default Tab) Fold back to the carousel

Tab and Shift+Tab also step windows, unless keys.windows is Tab (the default), in which case Tab folds the loop back instead.

Previews

The window loop can show window previews:

  • On Hyprland, live previews are used.
  • Snapshots are also taken: with grim on Hyprland, and with niri's own screenshot-window on niri. Snapshot files go to $XDG_RUNTIME_DIR (or /tmp if that is not set).

These are toggled by the livePreviews, snapshotPreviewsHyprland, and snapshotPreviewsNiri properties in workspace-manager/Theme.qml.


Workspace badge

skygqts workspace-badge --daemon

Two small glass boxes, one in each bottom corner of every monitor. Both show the name of the workspace active on that monitor (or its number when it has no name), on a background of that workspace's color. Each box has a round top corner facing into the screen and curves where it runs into the screen edges, as if it grows out of the corner.

Click either box to open the editor in the middle of the screen:

  • Rename workspace — Enter or OK applies the name. An empty name clears it (on Hyprland it goes back to the number).
  • Color — pick a swatch, drag along the hue strip, or type a hex value like #7aa2f7. Below it, the Opacity slider sets how solid the badge background is (80% by default). The badge changes right away.

Escape or a click anywhere else closes it.

Colors and opacity are saved per workspace in $XDG_STATE_HOME/skygqts/workspace-colors.json (or ~/.local/state/skygqts/...), as entries like { "color": "#ffd60a", "opacity": 0.8 }. Named workspaces are saved by name, and the entry moves along when you rename one from the badge. Unnamed workspaces are saved by id; niri gives out new ids after a restart, so name a workspace if its color should stick.

On niri, renaming a workspace that has no name first focuses its monitor, because niri can only point at an unnamed workspace through the focused monitor.


Theming

Colors, sizes, and animation timings live in one place per app:

  • app-carousel/Theme.qml
  • workspace-manager/Theme.qml
  • workspace-badge/Theme.qml

Edit those files to restyle the carousel, glass effect, hints, and window loop.

Repository layout

app-carousel/       # launcher: shell.qml, config, theme, cards
workspace-manager/  # overview: carousel, rename bar, window loop, compositor bridge
workspace-badge/    # corner badge: name, color, rename and color editor
skygqts.nu          # the `skygqts` CLI (Nushell)
package.nix         # package definition
flake.nix           # flake: package, overlay, dev shell
example.json               # sample app-carousel config
workspace-manager.example.json  # sample workspace-manager config
S
Description
No description provided
Readme
544 KiB
0 Stars 1 Watchers 0 Forks
Languages
QML 96.8%
Nix 1.3%
GLSL 1%
Nushell 0.9%