z-bar-qt/README.md

<div align="center">
    <img src="./assets/logo.svg" alt="ZShell logo" width="480">
</div>

# ZShell

ZShell is a Hyprland-focused desktop shell built with Quickshell + Qt6/QML.

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.

<div align="center">
    <img src="/images/shell.png" alt="ZShell screenshot">
</div>

## Highlights

- Multi-window shell layout driven by `Drawers/Windows.qml` and panel/interactions wrappers
- 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

## Project Layout

```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)
```

## Runtime Requirements

Core requirements:

- Qt6 + Quickshell
- Hyprland (Wayland session integration)
- Python 3 for scheme/wallpaper tooling

Here's a list of package dependencies, names are from arch-packages so they
might differ slightly depending on your distro.

```
python python-pillow python-materialyoucolor libnotify cava
app2unit wl-clipboard dconf cliphist python-typer qt6-canvaspainter
python-build python-installer python-hatch python-hatch-vcs cmake ninja
```

Make sure to have the newest Quickshell version! As of writing, version `0.3.1.r1.g0fed22a-1`.

Used by major features (install as needed for your setup):

- `app2unit` (launcher app execution)
- `nmcli` (network integration)
- `brightnessctl`, `ddcutil` (brightness controls)
- `wl-copy` (clipboard integration)
- `PipeWire` + audio stack + `aubio`/`cava` paths for media visualization
- `libqalculate` (launcher calculator)
- `gsettings` (optional GTK dark/light mode sync)

## Build and Install

### CMake (manual)

```bash
cmake -B build -G Ninja
ninja -C build
sudo ninja -C build install
```

Defaults from `CMakeLists.txt`:

- `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`

### Nix

Nix support has been removed. Reason being that none of us actively develop for Nix. Having a `flake.nix` in the project will give the wrong idea.

Contributions for Nix support are welcome, the caveat being that reviews of these contributions can be of lower quality.

## 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

Primary config file:

- `~/.config/zshell/config.json`

Important state/cache files:

- `~/.local/state/zshell/scheme.json`
- `~/.local/state/zshell/wallpaper_path.json`
- `~/.local/state/zshell/notifs.json`
- `~/.local/state/zshell/apps.sqlite`
- `~/.cache/zshell/`

Config is hot-reloaded and saved through the `Config` singleton. Top-level sections include:

- `general`
- `appearance`
- `background`
- `barConfig`
- `launcher`
- `services`
- `notifs`
- `sidebar`
- `utilities`
- `dashboard`
- `osd`
- `colors`
- `dock`

## Launcher Prefixes

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` — daemon management

| Command   | Description                                                      |
| --------- | ---------------------------------------------------------------- |
| `start`   | Start the shell daemon (pass `--no-daemon` to run in foreground) |
| `kill`    | Kill the running shell daemon                                    |
| `restart` | Kill then restart the daemon                                     |
| `lock`    | Lock the session via IPC                                         |
| `show`    | Show the shell window via IPC                                    |
| `log`     | Print daemon logs                                                |

### `scheme` — color scheme generation

```
Usage: zshell-cli scheme generate [--preset <scheme>:<variant>] [--accent <accent>]
                                   [--mode <dark|light>] [--image-path <path>]

Generate a color scheme from a wallpaper image (Material You) or from
a built-in preset.

Preset selection:
  --preset <scheme>:<variant>    Pick a built-in scheme (e.g. catppuccin:mocha)
  --accent <name>                Accent color for schemes that support it
                                   (catppuccin accepts: blue, green, mauve,
                                   peach, pink, red, rosewater, etc.)
  --mode <dark|light>            Override variant mode

  If variant has both dark and light modes, the mode is auto-detected from
  the current system or config preference.

  List all available presets:
    zshell-cli scheme list-presets         # human-readable
    zshell-cli scheme list-presets --json  # machine-readable (QML UI)

  Examples:
    zshell-cli scheme generate --preset gruvbox:medium
    zshell-cli scheme generate --preset catppuccin:mocha --accent green
    zshell-cli scheme generate --preset everforest:medium --mode light
```

Note: Template rendering (Jinja2) applies generated colors to `~/.config/zshell/templates/*`.

### `screenshot` — area picker

- `start` — open interactive area picker

### `wallpaper` — wallpaper management

- Set wallpaper and generate lockscreen blur background

## 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)
- [end-4 dots-hyprland](https://github.com/end-4/dots-hyprland)

## License

See `LICENSE`.