# Skygqts A small collection of desktop tools built with [Quickshell](https://quickshell.org/), for Wayland compositors that speak [niri](https://github.com/YaLTeR/niri) or [Hyprland](https://hyprland.org/). It ships two 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. 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 ### With Nix (recommended) The repository is a flake that exposes a package and an overlay. Replace `` below with wherever you host it (a Git URL, or `.` when you are inside a checkout). ```sh # From a checkout of this repo nix build .#skygqts # build the package nix run .#skygqts -- workspace-manager --daemon # From a remote flake nix run # Add to a system config, inside your flake's inputs inputs.skygqts.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: ```sh # app carousel SKYG_APP_CAROUSEL=/path/to/app-carousel.json qs -p ./app-carousel # workspace manager qs -n -p ./workspace-manager ``` --- ## What's available ### CLI `skygqts` is a Nushell script (`skygqts.nu`). Its subcommands: | Command | What it does | | ------------------------------------------- | ------------------------------------------------- | | `skygqts carousel ` | 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 ` | 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 | 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): ```sh skygqts workspace-manager --daemon --config ~/.config/skygqts/workspace-manager.json ``` Then bind them in your compositor, e.g.: ```conf # 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: ```sh 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 ./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 | --- ## App carousel ```sh 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: ```json { "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 ```sh 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`. --- ## Theming Colors, sizes, and animation timings live in one place per app: - `app-carousel/Theme.qml` - `workspace-manager/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 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 ```