Files
2026-10-27 13:30:14 -04:00

386 lines
16 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
<img src="logo.jpg" width="200" />
# 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 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 vim-style search for windows by
title and app, 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
### 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 |
| `qsb` | Compiles the workspace manager's shaders (from Qt Shader Tools) |
The workspace manager bends its cards onto the globe with a small shader.
Compile it once, and again whenever a file in `workspace-manager/shaders/`
changes. Without it the cards still show, just flat.
```sh
for shader in workspace-manager/shaders/*.vert workspace-manager/shaders/*.frag; do
qsb --glsl "100 es,120,150" --hlsl 50 --msl 12 -o "$shader.qsb" "$shader"
done
```
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
# 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 search` | Opens the carousel with the window search open |
| `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):
```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, SLASH, exec, skygqts workspace-manager search
```
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 openSearch
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 |
---
## 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, open a window
loop, or search windows by title and app.
### 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.windows` | string | `"Tab"` | Key that opens the window loop |
| `hints.show` | bool | `true` | Show the small key hints |
| `hints.windows` | string | `"{key}: to see windows"` | Hint text |
| `hints.exitWindows` | string | `"{key} or Esc: to exit window carousel"` | Hint text |
| `hints.search` | string | `"/: to search windows, n / N: next / previous match"` | Hint text |
The search keys (`/`, `n`, `N`) are fixed, like in vim.
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.windows` (default Tab) | Open the window loop |
| `/` | Search windows |
| `n` / `N` | Next / previous match of the last search |
| Scroll | Vertical = workspaces, horizontal = monitors |
**Search**
`/` opens a search bar, in the carousel or the window loop. As you type, the
view jumps to the first window after the current one whose title or app
(niri `app_id`, Hyprland `class`) contains the text, opening the window loop
on its workspace. A lowercase search ignores case; any capital letter makes
it match case exactly (like vim's `smartcase`). The search wraps round:
monitors left to right, workspaces top to bottom, windows in loop order.
| Key | Action |
| ----------------------- | -------------------------------------- |
| Enter | Keep the match; Enter again focuses it |
| Escape | Go back to where the search started |
| Backspace (empty field) | Same as Escape |
**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 |
| `/`, `n` / `N` | Search windows, as in 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
```sh
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: globe carousel, window search, window loop, compositor bridge
# shaders/ holds the card shader sources; .qsb files are built from them
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
```