This commit is contained in:
ari committed 2026-10-03 00:04:57 -04:00
1 parent 36bceddd58
commit f4b0a69370
1 file changed
+311
+311
View File
@@ -0,0 +1,311 @@
# 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
`<flake-url>` 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 <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:
```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 <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 |
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
```