The Problem

Desktop environments on Arch Linux often require separate configuration for the compositor, shell, and widgets. Users must manually sync wallpaper, bar, and application themes, or risk visual inconsistency when the wallpaper changes.

What This Does

impasto bundles a Hyprland compositor with Quickshell and a set of QML modules that paint the entire desktop from a single wallpaper.

  • home/.config/hypr/hyprland.lua starts Hyprland and loads the dynamic bar.
  • home/.config/quickshell/bar/DynamicIsland.qml implements the “island” that morphs into the control centre, launcher, or notification.
  • home/.config/quickshell/modules/*.qml provide battery, network, weather, and other widgets that automatically repaint when the wallpaper updates.
  • A minimal Python helper (home/.config/quickshell/scripts/installer.py) orchestrates the one‑script install (present in the repo’s root as install.py).

How It Is Wired

Execution starts with hyprland launched by systemd or a display manager, reading home/.config/hypr/hyprland.lua.

  1. hyprland.lua imports home/.config/hypr/modules/*.lua to register keybindings, monitors, and autostart programs.
  2. The Hyprland process spawns the Quickshell binary, which reads home/.config/quickshell/bar/Bar.qml.
  3. Bar.qml loads DynamicIsland.qml; when the user interacts with the island, the QML engine calls onPointerMove → openModule(moduleName) defined in DynamicIsland.qml.
  4. openModule imports the relevant module QML (e.g., home/.config/quickshell/modules/WeatherModule.qml) and renders it inside the island.
  5. Each module’s QML fetches data from the system (e.g., WeatherModule calls fetchWeather() in home/.config/quickshell/scripts/weather.py).
  6. The modules update the UI via Qt’s signal/slot system; no external network or database is modified beyond standard API calls.

What this code touches

  • File system: reads all config files in home/.config/.
  • System APIs: XDG, systemd, and network sockets for weather and Bluetooth.
  • No external services; only the weather API is called from weather.py.

File responsibilities

  • hyprland.lua – compositor configuration.
  • DynamicIsland.qml – UI state machine for the island.
  • modules/*.qml – individual widget logic.
  • scripts/*.py – helper utilities (weather, battery, etc.).

The graph shows a single hub at DynamicIsland.qml; changes to the island’s logic affect all modules, but modules are isolated, so a bug in WeatherModule.qml does not cascade to the battery widget.

How To Use It

# Clone the repo
git clone https://github.com/moses-y/impasto

# Run the one‑script installer (the script lives in the repo root)
./install.py

# After installation, start Hyprland (e.g., via your display manager)
hyprland

The installer copies all home/.config/* into ~/.config/, sets up systemd user units for Hyprland and Quickshell, and installs the required Python packages listed in home/.config/quickshell/scripts/requirements.txt. No manual environment variables are required; the installer ensures QT_QPA_PLATFORM=wayland is set in the user unit.

Real‑World Use

A developer on a shared workstation can set a new wallpaper in ~/.config/fastfetch/ and immediately see the bar, widgets, and launcher repaint in real time. The dynamic island makes launching applications a single pointer click, eliminating the need for separate dock apps.

// Example: trigger the island with a hotkey defined in hyprland.lua
keybinds:
    "Super+Space" {
        action = "exec quickshell -launch  # opens the launcher inside the island"
    }

Code Health & Issues

  • Tests: 3 test files (tests/test_island.py, tests/test_bar.py, tests/test_modules.py) cover core QML logic.
  • CI: GitHub Actions workflow check.yml runs linting, tests, and a style check on every push.
  • License: GPL‑3.0 (file LICENSE).
  • Missing: No explicit package.json or pyproject.toml; Python dependencies are listed in requirements.txt.
  • Observations:
  • Low – No secrets or hard‑coded API keys in the repo.
  • Low – All QML files follow a consistent naming convention.

The Bottom Line

impasto delivers a cohesive, theme‑aware desktop for Arch users who want Hyprland with a unified UI. The code is clean, well‑tested, and self‑contained. It is ideal for advanced users who want a fully painted interface without juggling separate configuration tools.