ArchEclipse: an Arch and Hyprland desktop built on Quickshell

One script installs the whole desktop

The pitch in the README is a single command. The stated prerequisites are Arch or an Arch-based system, Hyprland and Python 3, and the README says the rest is auto-installed. The install command pipes a script straight from the repository into Python:

python3 <(curl -fsSL https://raw.githubusercontent.com/AymanLyesri/ArchEclipse/refs/heads/master/.config/hypr/maintenance/install.py)

That is worth pausing on as a design choice. The convenience comes from the script being fetched and executed in one step, which also means you are running code you have not read, from a branch rather than from a release. There is no GitHub release for this repository, so `master` is the only version there is.

Updates go through a different path, a shell function rather than a script:

archeclipse   # update anytime (zsh fn → runs maintenance/update.py)

The README names the files behind both paths. The installer and the updater are `install.py` and `update.py` under the maintenance directory, and the package list they work from is embedded in a `components/packages.py` file, so the set of things installed is data in the repository rather than a hidden script. The repository root also carries a `.zshrc`, a `.icons` directory, a `.config` directory, a `docs` directory and a `.github` directory, which is the usual shape for a dotfiles repository that expects to be read alongside.

Four languages, and the layer boundaries are explicit

The README describes the stack as QML/QtQuick through Quickshell, Python 3 and Bash, C for performance utilities, and Hyprland on Wayland. The architecture diagram in the documentation makes the boundaries concrete, and they are worth understanding before you change anything.

The Hyprland layer is Lua. An `hyprland.lua` entry point loads the configuration files under `config`, which cover bindings, animations, monitors, window rules, gestures and input, and it spawns the shell. Alongside that sit the Hyprland scripts for screenshot, screen recording, brightness, clipboard and the wallpaper loop, a wallpaper daemon on hyprpaper or mpvpaper, and evremap for key remapping.

The Quickshell layer is the UI. A `shell.qml` bootstrap gives you the bar, the launcher, the side panels and the core layers, and the core layers split into reusable QML components under `widgets/shared`, services such as BarState, Brightness, ScreenRecorder, Ipc, Supabase and Weather, utilities such as SettingsUtils, MonitorUtils, TimeUtils and WindowManager, and a theme module with a typed config.

Underneath the QML sit native helper scripts. Small C loops handle system resources, bandwidth and a keystroke visualizer, Python scripts handle the chatbot, booru, manga, crypto and auth callback, and shell scripts fetch wallpapers, translate, list keybinds and extract image colours. The C part is the interesting engineering choice: pulling high-frequency sampling out of the shell and into a compiled loop is what keeps the resource widgets cheap.

The bar is a state machine with island widgets

The bar is not a row of independent applets. In the architecture diagram it is described as a state machine with states for default, search, control, volume, brightness and recording, and the bar widgets list covers Battery, Volume, Bandwidth, Brightness, Player and Recording.

The islands are the visible variant of that design. The diagram names SearchIsland, ControlIsland, PlayerIsland, WallpaperIsland, WeatherIsland and RightIsland, and the README's feature table adds workspaces, bandwidth, weather, player, tray and crypto to the modular widget list. An island is a panel that appears on demand in place of the bar, so the bar stays out of the way while a search or a volume overlay is open, and the arrow from the islands to the launcher panel is marked as the island opening it.

The two panels are where the ambition shows. The right panel holds the player, notifications, calendar, crypto and an anime viewer, and the left panel holds a chatbot, a booru browser, a manga reader that the README marks as work in progress, keybinds and settings. That is a lot of surface area for a shell, and it is the reason the project is described as performance-focused rather than minimal.

The launcher replaces Rofi and several utilities at once

The feature table is blunt about the launcher. App search, clipboard, emoji, calculator, URLs and custom commands, with the note that there is no Rofi.

This is the difference between a dotfiles repository and a dotfiles product. Most dotfiles collections give you a bar, a launcher and a notification daemon as three separate programs, each with its own configuration, its own theme file and its own idea of what a keybinding means. Here they are one Quickshell application, so the clipboard history and the app search share a component library, the panels can be opened from the bar islands, and the theme applies to all of them at once.

The cost is that you inherit the design decisions. The left panel opens a booru browser and a chatbot, the right panel opens an anime viewer, and the features are documented as shipped rather than as optional modules to disable. The README's own summary of the project is that the UI, the scripts and the theming ship as one product and that this is not a set of random dotfiles, which is a fair description and also a warning about how tightly coupled the parts are.

The wallpaper drives the colour scheme

Theming is described as wallpaper to full system colors, with a light and dark toggle, hot reload, and no manual edits. The `.sh` helper that extracts image colours is part of the native script layer, and the theme module in the core layers holds a typed config that the rest of the UI styles itself from.

This is the feature that most shapes the daily use of the desktop. In a setup where the shell is written by hand rather than assembled from third-party applets, the colour pipeline is what makes a change of wallpaper feel like a change of system rather than a background swap. Hot reload is what makes it usable, since you change the picture and the bars, panels and launcher follow without a session restart.

The wallpaper picker is bound to `SUPER + W` according to the README's quick reference, and the full key list lives in `bind.lua` in the Hyprland configuration, which is also the file the README points to for the complete set of bindings. Custom wallpapers are picked up from `$HOME/.config/wallpapers/custom`, and the avatar comes from `$HOME/.face.icon`.

Workspaces and app placement are fixed conventions

The README assigns meaning to specific workspace numbers, and this is worth reading before you install it, because the binding is not something you discover later. Workspaces W2, W4, W5, W6, W7 and W10 open the browser, Spotify, Btop, Discord, Steam and games respectively, while W1, W3, W8 and W9 are general. The table also notes that apps auto-launch to their workspace at login.

That last behaviour is the most opinionated part of the configuration. A desktop that puts your applications on fixed workspaces at startup is convenient if you always work the same way and irritating if you do not, and the keybinding for the wallpaper picker, the avatar location and the laptop hint about installing `upower` for battery support all point the same way. This is a configuration built by one person for one workflow.

The Hyprland customisation points are named too: the tweaks live in `$HOME/.config/hypr/config/custom`, and the keybindings in `bind.lua` or in the left panel of the application.

Supabase and the panel APIs are part of the dependency list

The last group in the architecture diagram is the one with a privacy and reliability dimension. The services layer includes a Supabase service, and the backend box is Supabase for auth, RLS and settings sync, alongside external booru, manga, crypto, weather and chatbot APIs. The native scripts make HTTP calls to those APIs, and there is a dedicated auth-callback Python script, which is how an external provider returns to the desktop.

So the desktop has a server-side component in the design even if you never sign in. The chatbot, the booru browser, the crypto panel and the weather widget all need a network, and the settings sync path needs an account. That is a different dependency profile from a purely local shell, and it is worth deciding before the install whether you want a desktop that reaches out to third-party services on your behalf.

On the licensing and maintenance side: the repository is licensed under GPL-3.0 with the LICENSE file at the root, it is not archived, and the last push was on 2026-10-22. There are no GitHub releases, so there is no tagged version to pin and no upgrade notes to read, and the README points to a Discord server for questions, which is the usual support channel for a configuration project of this kind.

Editorial conclusion

ArchEclipse fits a Linux user on Arch or an Arch derivative who already runs Hyprland, wants the wallpaper to drive the whole colour scheme, and prefers a hand-written shell to assembling one from a bar, a launcher and a notification daemon separately. It is the wrong choice for a non-Arch machine, for a Wayland compositor other than Hyprland, and for anyone who does not want the Supabase account and the third-party API calls the panels make. Verify first that the installer only pulls what you want, since the documented command pipes a downloaded script straight into Python, and read the licence, which is GPL-3.0.

Frequently asked questions

Official sources

1. AymanLyesri/ArchEclipse on GitHub
2. Issues
3. License: GPL-3.0
4. README