386 lines
16 KiB
Markdown
386 lines
16 KiB
Markdown
<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
|
||
```
|