readme
This commit is contained in:
1 parent
36bceddd58
commit
f4b0a69370
1 file changed
+311
@@ -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
|
||||
```
|
||||
Reference in new issue
Block a user