vibed readme updates
This commit is contained in:
@@ -1,39 +1,61 @@
|
|||||||
<div align="center">
|
<div align="center">
|
||||||
<img src="/images/shell.png">
|
<img src="/images/shell.png" alt="ZShell screenshot">
|
||||||
</div>
|
</div>
|
||||||
|
|
||||||
# ZShell
|
# ZShell
|
||||||
|
|
||||||
A feature-rich desktop shell for [Hyprland](https://hypr.land/) built with [Quickshell](https://quickshell.outfoxxed.me/) and Qt6/QML. Provides a modern, Material Design 3 inspired status bar, application launcher, notification center, wallpaper manager with dynamic color theming, and lock screen.
|
ZShell is a Hyprland-focused desktop shell built with Quickshell + Qt6/QML.
|
||||||
|
|
||||||
## Features
|
It includes a configurable top bar, launcher, notifications daemon + sidebar, wallpaper and dynamic color pipeline, lock screen, OSD widgets, dashboard, dock, desktop icons, and a separate greetd-compatible greeter.
|
||||||
|
|
||||||
- **Status Bar** - Configurable top panel with workspace indicators, audio controls, system resource monitors (CPU/RAM/GPU), system tray, clock with calendar, and notification bell
|
## Highlights
|
||||||
- **Application Launcher** - Fuzzy search with app frequency tracking, special search prefixes for filtering by category, description, keywords, etc.
|
|
||||||
- **Notification Center** - Full notification daemon with grouped notifications, popups, persistent storage, and Do Not Disturb mode
|
|
||||||
- **Wallpaper Manager** - Browse and select wallpapers with live preview carousel
|
|
||||||
- **Dynamic Color Theming** - Automatic Material Design 3 color palette generation from wallpapers
|
|
||||||
- **Lock Screen** - Secure session lock with PAM authentication
|
|
||||||
- **Hyprland Integration** - Deep integration with Hyprland for workspaces, window focus, keyboard state, and more
|
|
||||||
|
|
||||||
## Dependencies
|
- Multi-window shell layout driven by `Drawers/Windows.qml` and panel/interactions wrappers
|
||||||
|
- Configurable bar entries and popouts (audio, tray, network, power, resources, clock, active window)
|
||||||
|
- Launcher with app DB frequency tracking, action commands, fuzzy search modes, and wallpaper/scheme flows
|
||||||
|
- Notification server with persistence (`~/.local/state/zshell/notifs.json`) and sidebar UI
|
||||||
|
- Dynamic Material 3 palette generation from wallpaper, optional template rendering, terminal sequence application
|
||||||
|
- Lock module with PAM support, idle monitors, optional fingerprint integration, and blur background generation
|
||||||
|
- Additional modules: dock, desktop icons, dashboard, OSD, polkit agent, area picker/screenshot flow
|
||||||
|
|
||||||
- Qt 6.9+
|
## Project Layout
|
||||||
- [Quickshell](https://quickshell.outfoxxed.me/)
|
|
||||||
- [Hyprland](https://hyprland.org/)
|
|
||||||
- Python 3 with `materialyoucolor` and `Pillow` (for dynamic color generation)
|
|
||||||
- PipeWire (for audio)
|
|
||||||
- Aubio
|
|
||||||
- DDCUtil
|
|
||||||
- Mpris
|
|
||||||
|
|
||||||
## Installation
|
```text
|
||||||
|
.
|
||||||
|
├── shell.qml # Main shell entry point (qs config: zshell)
|
||||||
|
├── Drawers/ # Window, panel, interaction composition
|
||||||
|
├── Modules/ # UI/feature modules (bar, launcher, lock, notifs, settings, etc.)
|
||||||
|
├── Config/ # JSON-backed config schema + serializers
|
||||||
|
├── Daemons/ # Notification/audio/network daemons
|
||||||
|
├── Helpers/ # Shared runtime helpers and integration glue
|
||||||
|
├── Paths/ # Runtime paths (XDG + state/cache/data locations)
|
||||||
|
├── Plugins/ZShell/ # Native Qt/QML plugin (C++)
|
||||||
|
├── Greeter/ # Separate Quickshell greeter app and scripts
|
||||||
|
├── cli/ # Python CLI (`zshell-cli`)
|
||||||
|
└── scripts/ # Utility scripts (greeter prep, updates, fuzzy helpers)
|
||||||
|
```
|
||||||
|
|
||||||
### Arch Linux
|
## Runtime Requirements
|
||||||
|
|
||||||
For arch-based distros, there is a pkgbuild available [here](https://git.zach-dev.cc/zach/zshell-PKGBUILD)
|
Core requirements:
|
||||||
|
|
||||||
### Manual install
|
- Qt6 + Quickshell
|
||||||
|
- Hyprland (Wayland session integration)
|
||||||
|
- Python 3 for scheme/wallpaper tooling
|
||||||
|
|
||||||
|
Used by major features (install as needed for your setup):
|
||||||
|
|
||||||
|
- `app2unit` (launcher app execution)
|
||||||
|
- `nmcli` (network integration)
|
||||||
|
- `brightnessctl`, `ddcutil` (brightness controls)
|
||||||
|
- `wl-copy`, `swappy` (picker/screenshot flow)
|
||||||
|
- `libqalculate` (launcher calculator)
|
||||||
|
- `PipeWire` + audio stack + `aubio`/`cava` paths for media visualization
|
||||||
|
- `gsettings` (optional GTK dark/light mode sync)
|
||||||
|
|
||||||
|
## Build and Install
|
||||||
|
|
||||||
|
### CMake (manual)
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
cmake -B build -G Ninja
|
cmake -B build -G Ninja
|
||||||
@@ -41,52 +63,62 @@ ninja -C build
|
|||||||
sudo ninja -C build install
|
sudo ninja -C build install
|
||||||
```
|
```
|
||||||
|
|
||||||
This installs the QML plugin to `/usr/lib/qt6/qml`.
|
Defaults from `CMakeLists.txt`:
|
||||||
|
|
||||||
### NixOS
|
- `ENABLE_MODULES="plugin;shell"`
|
||||||
|
- QML plugin install dir: `usr/lib/qt6/qml`
|
||||||
|
- shell config install dir: `etc/xdg/quickshell/zshell`
|
||||||
|
- greeter install dir: `etc/xdg/quickshell/zshell-greeter`
|
||||||
|
|
||||||
**Note that not all features work well. This is due to limited testing on NixOS.**
|
### Nix Flake
|
||||||
|
|
||||||
In your flake.nix file, add the following in your inputs.
|
The flake exposes:
|
||||||
|
|
||||||
```nix
|
- `packages.<system>.zshell`
|
||||||
inputs = {
|
- `packages.<system>.zshell-cli`
|
||||||
nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
|
|
||||||
z-bar-qt = {
|
|
||||||
url = "git+ssh://git@git.zach-dev.cc/zach/z-bar-qt.git";
|
|
||||||
inputs.nixpkgs.follows = "nixpkgs";
|
|
||||||
};
|
|
||||||
};
|
|
||||||
```
|
|
||||||
|
|
||||||
Below a full example of what it could look like.
|
Add it as an input in your system flake:
|
||||||
|
|
||||||
```nix
|
```nix
|
||||||
{
|
{
|
||||||
inputs = {
|
inputs = {
|
||||||
nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
|
nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
|
||||||
z-bar-qt = {
|
z-bar-qt = {
|
||||||
url = "git+ssh://git@git.zach-dev.cc/zach/z-bar-qt.git";
|
# or: git+ssh://git@git.zach-dev.cc/zach/z-bar-qt.git
|
||||||
inputs.nixpkgs.follows = "nixpgks";
|
url = "github:Zacharias-Brohn/z-bar-qt";
|
||||||
|
inputs.nixpkgs.follows = "nixpkgs";
|
||||||
|
};
|
||||||
|
};
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Full `flake.nix` example (`nixosConfigurations`):
|
||||||
|
|
||||||
|
```nix
|
||||||
|
{
|
||||||
|
inputs = {
|
||||||
|
nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
|
||||||
|
z-bar-qt = {
|
||||||
|
# or: git+ssh://git@git.zach-dev.cc/zach/z-bar-qt.git
|
||||||
|
url = "github:Zacharias-Brohn/z-bar-qt";
|
||||||
|
inputs.nixpkgs.follows = "nixpkgs";
|
||||||
};
|
};
|
||||||
};
|
};
|
||||||
|
|
||||||
outputs =
|
outputs = inputs@{ nixpkgs, ... }:
|
||||||
inputs@{
|
|
||||||
nixpkgs,
|
|
||||||
self,
|
|
||||||
...
|
|
||||||
}:
|
|
||||||
let
|
let
|
||||||
system = "x86_64-linux";
|
system = "x86_64-linux";
|
||||||
in
|
in {
|
||||||
{
|
nixosConfigurations.my-host = nixpkgs.lib.nixosSystem {
|
||||||
nixosConfigurations.nixos = nixpkgs.lib.nixosSystem {
|
|
||||||
specialArgs = {
|
|
||||||
inherit inputs;
|
|
||||||
inherit system;
|
inherit system;
|
||||||
};
|
specialArgs = { inherit inputs; };
|
||||||
modules = [
|
modules = [
|
||||||
|
({ ... }: {
|
||||||
|
environment.systemPackages = [
|
||||||
|
inputs.z-bar-qt.packages.${system}.zshell
|
||||||
|
inputs.z-bar-qt.packages.${system}.zshell-cli
|
||||||
|
];
|
||||||
|
})
|
||||||
./configuration.nix
|
./configuration.nix
|
||||||
];
|
];
|
||||||
};
|
};
|
||||||
@@ -94,76 +126,127 @@ Below a full example of what it could look like.
|
|||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
Now you can add z-bar-qt as a nixpkg in environment.systemPackages (or optionally in your homePackages). It is named zshell and for cli options; zshell-cli.
|
Then install shell + CLI from the flake packages:
|
||||||
|
|
||||||
```nix
|
```nix
|
||||||
{ pkgs, inputs, ... }:
|
{ pkgs, inputs, ... }:
|
||||||
|
let
|
||||||
{
|
system = pkgs.stdenv.hostPlatform.system;
|
||||||
environment.systemPackages = with pkgs; [
|
in {
|
||||||
|
environment.systemPackages = [
|
||||||
inputs.z-bar-qt.packages.${system}.zshell
|
inputs.z-bar-qt.packages.${system}.zshell
|
||||||
inputs.z-bar-qt.packages.${system}.zshell-cli
|
inputs.z-bar-qt.packages.${system}.zshell-cli
|
||||||
];
|
];
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
You can now run `zshell` to run the bar. `zshell-cli` can be used for additional options.
|
If you use Home Manager, the same packages can be added to `home.packages`.
|
||||||
|
|
||||||
|
Quick test without adding it permanently:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
nix run github:Zacharias-Brohn/z-bar-qt#zshell
|
||||||
|
```
|
||||||
|
|
||||||
|
Run shell via wrapper binary:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
zshell
|
||||||
|
```
|
||||||
|
|
||||||
|
CLI entrypoint:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
zshell-cli
|
||||||
|
```
|
||||||
|
|
||||||
|
## Running
|
||||||
|
|
||||||
|
- Start shell directly with Quickshell config name: `qs -c zshell`
|
||||||
|
- Start through CLI helper: `zshell-cli shell start`
|
||||||
|
- Lock through IPC helper: `zshell-cli shell lock`
|
||||||
|
|
||||||
## Configuration
|
## Configuration
|
||||||
|
|
||||||
Configuration is stored in `~/.config/zshell/config.json`. Options include:
|
Primary config file:
|
||||||
|
|
||||||
| Option | Description |
|
- `~/.config/zshell/config.json`
|
||||||
| :-------------------------------: | :---------------------------------------------------------: |
|
|
||||||
| `appCount` | Max apps shown in launcher |
|
|
||||||
| `wallpaperPath` | Directory containing wallpapers |
|
|
||||||
| `baseBgColor` / `baseBorderColor` | Fallback colors when dynamic colors disabled |
|
|
||||||
| `accentColor` | Custom accent color override |
|
|
||||||
| `useDynamicColors` | Enable Material Design 3 theming from wallpaper |
|
|
||||||
| `barConfig` | Enable/disable widgets and configure popouts |
|
|
||||||
| `transparency` | UI transparency levels |
|
|
||||||
| `baseFont` | System font |
|
|
||||||
| `animScale` | Animation speed multiplier |
|
|
||||||
| `gpuType` | GPU type for resource monitoring (`amd`, `nvidia`, `intel`) |
|
|
||||||
|
|
||||||
## Launcher Search Prefixes
|
Important state/cache files:
|
||||||
|
|
||||||
| Prefix | Filter |
|
- `~/.local/state/zshell/scheme.json`
|
||||||
| ------------- | ------------------- |
|
- `~/.local/state/zshell/wallpaper_path.json`
|
||||||
| `>i` | App ID |
|
- `~/.local/state/zshell/notifs.json`
|
||||||
| `>c` | Categories |
|
- `~/.local/state/zshell/apps.sqlite`
|
||||||
| `>d` | Description/comment |
|
- `~/.cache/zshell/`
|
||||||
| `>e` | Exec command |
|
|
||||||
| `>w` | WM class |
|
|
||||||
| `>g` | Generic name |
|
|
||||||
| `>k` | Keywords |
|
|
||||||
| `>t` | Terminal apps only |
|
|
||||||
| `>wallpaper ` | Wallpaper picker |
|
|
||||||
|
|
||||||
## Project Structure
|
Config is hot-reloaded and saved through `Config/Config.qml` serializers. Top-level sections include:
|
||||||
|
|
||||||
```
|
- `general`
|
||||||
├── shell.qml # Main entry point
|
- `appearance`
|
||||||
├── Bar.qml # Status bar
|
- `background`
|
||||||
├── Wallpaper.qml # Wallpaper display layer
|
- `barConfig`
|
||||||
├── Components/ # Reusable UI components
|
- `launcher`
|
||||||
├── Config/ # Configuration singletons
|
- `services`
|
||||||
├── Modules/ # Main functional modules (Launcher, NotificationCenter, etc.)
|
- `notifs`
|
||||||
├── Daemons/ # Background services (notifications, audio)
|
- `sidebar`
|
||||||
├── Helpers/ # Utility singletons
|
- `utilities`
|
||||||
├── Plugins/ZShell/ # Native C++ plugins
|
- `dashboard`
|
||||||
└── scripts/ # Helper scripts (color generation, fuzzy search)
|
- `osd`
|
||||||
```
|
- `colors`
|
||||||
|
- `dock`
|
||||||
|
|
||||||
## Inspiration and Acknowledgements
|
## Launcher Prefixes
|
||||||
|
|
||||||
This project was inspired by the following repositories and resources, which helped me learn both Quickshell and QML:
|
Default prefixes are defined in `Config/Launcher.qml`:
|
||||||
|
|
||||||
|
- `actionPrefix`: `>`
|
||||||
|
- `specialPrefix`: `@`
|
||||||
|
|
||||||
|
Special app-search filters (`@` prefix by default):
|
||||||
|
|
||||||
|
- `@i ` app id/name
|
||||||
|
- `@c ` categories
|
||||||
|
- `@d ` description/comment
|
||||||
|
- `@e ` exec string
|
||||||
|
- `@w ` WM class
|
||||||
|
- `@g ` generic name
|
||||||
|
- `@k ` keywords
|
||||||
|
- `@t ` terminal-only apps
|
||||||
|
|
||||||
|
Action-driven flows (`>` prefix by default) include calculator, wallpaper picker, and scheme variant selection.
|
||||||
|
|
||||||
|
## CLI Commands
|
||||||
|
|
||||||
|
`zshell-cli` provides these subcommands:
|
||||||
|
|
||||||
|
- `shell` - start/kill/log/IPC calls
|
||||||
|
- `screenshot` - open area picker (`start`, `start-freeze`)
|
||||||
|
- `wallpaper` - set wallpaper + generate lockscreen blur image
|
||||||
|
- `scheme` - generate and apply dynamic/preset color schemes
|
||||||
|
|
||||||
|
Note: `cli/src/zshell/subcommands/scheme.py` uses Jinja2 templating for `~/.config/zshell/templates` rendering.
|
||||||
|
|
||||||
|
## Greeter
|
||||||
|
|
||||||
|
The repository ships a separate greeter shell under `Greeter/` designed for greetd + Hyprland.
|
||||||
|
|
||||||
|
- Greeter shell entry: `Greeter/shell.qml`
|
||||||
|
- Default greeter config path: `/etc/zshell-greeter/config.json`
|
||||||
|
- Startup script: `Greeter/scripts/start-zshell-greeter`
|
||||||
|
- Helper installer script: `scripts/prepare-greeter.sh`
|
||||||
|
|
||||||
|
## Known Caveats
|
||||||
|
|
||||||
|
- `Modules/Launcher/Services/Apps.qml` references `assets/wrap_term_launch.sh`; ensure this script exists in your deployment.
|
||||||
|
- `cli/pyproject.toml` currently does not list `jinja2`, but `scheme.py` imports it.
|
||||||
|
- Some scheme variant naming paths may differ between UI values and CLI expectations (`tonalSpot` vs `tonal-spot`, etc.).
|
||||||
|
|
||||||
|
## Inspiration
|
||||||
|
|
||||||
- [Caelestia](https://github.com/caelestia-dots/shell)
|
- [Caelestia](https://github.com/caelestia-dots/shell)
|
||||||
- [end-4 dots-hyprland](https://github.com/end-4/dots-hyprland)
|
- [end-4 dots-hyprland](https://github.com/end-4/dots-hyprland)
|
||||||
|
|
||||||
Thank you to the maintainers and contributors of these projects for sharing their work.
|
|
||||||
|
|
||||||
## License
|
## License
|
||||||
|
|
||||||
See repository for license information.
|
See `LICENSE`.
|
||||||
|
|||||||
Reference in New Issue
Block a user