https://github.com/user-attachments/assets/0840f496-575c-4ca6-83a8-87bb01a85c5f
## Components
- Widgets: [`Quickshell`](https://quickshell.outfoxxed.me)
- Window manager: [`Hyprland`](https://hyprland.org)
- Dots: [`caelestia`](https://github.com/caelestia-dots)
## Installation
> [!NOTE]
> This repo is for the desktop shell of the caelestia dots. If you want installation instructions
> for the entire dots, head to [the main repo](https://github.com/caelestia-dots/caelestia) instead.
### Package manager
> [!NOTE]
> If you want to make your own changes/tweaks to the shell do NOT edit the files installed by the AUR
> package. Instead, follow the instructions in the [manual installation section](#manual-installation).
The shell is available from the AUR as `caelestia-shell-git`. You can install it with an AUR helper
like [`yay`](https://github.com/Jguer/yay) or manually downloading the PKGBUILD and running `makepkg -si`.
### Manual installation
Dependencies:
- [`caelestia-cli`](https://github.com/caelestia-dots/cli)
- [`quickshell-git`](https://quickshell.outfoxxed.me) - this has to be the git version, not the latest tagged version
- [`ddcutil`](https://github.com/rockowitz/ddcutil)
- [`brightnessctl`](https://github.com/Hummer12007/brightnessctl)
- [`app2unit`](https://github.com/Vladimir-csp/app2unit)
- [`cava`](https://github.com/karlstav/cava)
- [`networkmanager`](https://networkmanager.dev)
- [`lm-sensors`](https://github.com/lm-sensors/lm-sensors)
- [`fish`](https://github.com/fish-shell/fish-shell)
- [`aubio`](https://github.com/aubio/aubio)
- [`libpipewire`](https://pipewire.org)
- `glibc`
- `qt6-declarative`
- `gcc-libs`
- [`material-symbols`](https://fonts.google.com/icons)
- [`jetbrains-mono-nerd`](https://www.nerdfonts.com/font-downloads)
- [`grim`](https://gitlab.freedesktop.org/emersion/grim)
- [`swappy`](https://github.com/jtheoof/swappy)
- [`libqalculate`](https://github.com/Qalculate/libqalculate)
To install the shell manually, install all dependencies and clone this repo to `$XDG_CONFIG_HOME/quickshell/caelestia`.
Then compile the beat detector and install it to `/usr/lib/caelestia/beat_detector`.
```sh
cd $XDG_CONFIG_HOME/quickshell
git clone https://github.com/caelestia-dots/shell.git caelestia
g++ -std=c++17 -Wall -Wextra -I/usr/include/pipewire-0.3 -I/usr/include/spa-0.2 -I/usr/include/aubio -o beat_detector caelestia/assets/beat_detector.cpp -lpipewire-0.3 -laubio
sudo mv beat_detector /usr/lib/caelestia/beat_detector
```
## Usage
The shell can be started via the `caelestia shell -d` command or `qs -c caelestia`.
If the entire caelestia dots are installed, the shell will be autostarted on login
via an `exec-once` in the hyprland config.
### Shortcuts/IPC
All keybinds are accessible via Hyprland [global shortcuts](https://wiki.hyprland.org/Configuring/Binds/#dbus-global-shortcuts).
If using the entire caelestia dots, the keybinds are already configured for you.
Otherwise, [this file](https://github.com/caelestia-dots/caelestia/blob/main/hypr/hyprland/keybinds.conf#L1-L39)
contains an example on how to use global shortcuts.
All IPC commands can be accessed via `caelestia shell ...`. For example
```sh
caelestia shell mpris getActive trackTitle
```
The list of IPC commands can be shown via `caelestia shell -s`:
```
$ caelestia shell -s
target drawers
function toggle(drawer: string): void
function list(): string
target notifs
function clear(): void
target lock
function lock(): void
function unlock(): void
function isLocked(): bool
target mpris
function playPause(): void
function getActive(prop: string): string
function next(): void
function stop(): void
function play(): void
function list(): string
function pause(): void
function previous(): void
target picker
function openFreeze(): void
function open(): void
target wallpaper
function set(path: string): void
function get(): string
function list(): string
```
### PFP/Wallpapers
The profile picture for the dashboard is read from the file `~/.face`, so to set
it you can copy your image to there or set it via the dashboard.
The wallpapers for the wallpaper switcher are read from `~/Pictures/Wallpapers`
by default. To change it, change the wallpapers path in `~/.config/caelestia/shell.json`.
To set the wallpaper, you can use the command `caelestia wallpaper`. Use `caelestia wallpaper -h` for more info about
the command.
## Updating
If installed via the AUR package, simply update your system (e.g. using `yay`).
If installed manually, you can update by running `git pull` in `$XDG_CONFIG_HOME/quickshell/caelestia`.
```sh
cd $XDG_CONFIG_HOME/quickshell/caelestia
git pull
```
## Configuring
All configuration options are in `~/.config/caelestia/shell.json`.
Example configuration
```json
{
"bar": {
"workspaces": {
"activeIndicator": true,
"activeLabel": " ",
"activeTrail": false,
"label": " ",
"occupiedBg": false,
"occupiedLabel": " ",
"rounded": true,
"showWindows": true,
"shown": 5
}
},
"border": {
"rounding": 25,
"thickness": 10
},
"dashboard": {
"mediaUpdateInterval": 500,
"visualiserBars": 45,
"weatherLocation": "10,10"
},
"launcher": {
"actionPrefix": ">",
"enableDangerousActions": false,
"maxShown": 8,
"maxWallpapers": 9
},
"lock": {
"maxNotifs": 5
},
"notifs": {
"actionOnClick": false,
"clearThreshold": 0.3,
"defaultExpireTimeout": 5000,
"expandThreshold": 20,
"expire": false
},
"osd": {
"hideDelay": 2000
},
"paths": {
"mediaGif": "root:/assets/bongocat.gif",
"sessionGif": "root:/assets/kurukuru.gif",
"wallpaperDir": "~/Pictures/Wallpapers"
},
"session": {
"dragThreshold": 30
}
}
```
## Credits
Thanks to the Hyprland discord community (especially the homies in #rice-discussion) for all the help and suggestions
for improving these dots!
A special thanks to [@outfoxxed](https://github.com/outfoxxed) for making Quickshell and the effort put into fixing issues
and implementing various feature requests.
Another special thanks to [@end_4](https://github.com/end-4) for his [config](https://github.com/end-4/dots-hyprland)
which helped me a lot with learning how to use Quickshell.
Finally another thank you to all the configs I took inspiration from (only one for now):
- [Axenide/Ax-Shell](https://github.com/Axenide/Ax-Shell)
## Stonks 📈