Kamalen Shell

A wallpaper-adaptive Wayland shell for MangoWM.
Quickshell surfaces, modular compositor settings, and a desktop that changes character with its wallpaper.

Install · Shortcuts · Screenshots · Documentation

Note

Adaptive by default. Iris extracts the wallpaper palette and applies it across the shell, MangoWM, GTK, Neovim, Kitty, and Starship — without losing the selected visual skin.

Arch Linux is the primary target. Debian 12/13 and Ubuntu 24.04+ use a separate installer; the NixOS port is experimental.

Highlights

Surface	What it brings
Shell	Reactive Quickshell bar, dashboard, launcher, notifications, lock screen, and wallpaper picker.
Appearance	Four adaptive skins — Kamalen, Commonality, Aqua 2009, and Skeuos Workshop — plus wallpaper-driven colors.
Control	A standalone Settings window for Appearance, Monitors, Mango, Binds, and Rules; monitor changes use confirm/revert previews.
Flow	Keyboard-first layers with outside dismissal, shortcut help, global scale, and optional Vim navigation.
Configuration	Modular MangoWM files under .config/mango/conf.d/, with a test suite covering the installer, configuration bridge, QML integration, lock screen, and wallpaper providers.

Requirements

• Arch Linux or a derivative with a Wayland session, or Debian 12/13 or Ubuntu 24.04+ with the Debian installer.
• mango-ext/MangoWM, Quickshell, and the dependencies installed by the installer.
• A backup of any local configuration you do not want the installer to replace.

Install

Review the planned changes before installing:

git clone https://github.com/Guilherme4Colamarco/kamalen-shell.git
cd kamalen-shell
./install.sh --dry-run
./install.sh
./install.sh verify

install.sh backs up existing configuration and links the repository's .config/ into ~/.config/. As a result, repository edits are live configuration edits.

For Debian/Ubuntu, preview and verify through the dedicated installer:

./install-debian.sh --dry-run
./install-debian.sh
./install-debian.sh verify

Optional SDDM theme

If SDDM is already installed, the regular/config installation offers the Kamalen login theme. It mirrors the current wallpaper and Iris palette using static, optimized assets. Installation does no[...]

./install.sh --dry-run sddm
./install.sh sddm
kamalen-sddm-sync
scripts/install/sddm-theme.sh verify
scripts/install/sddm-theme.sh uninstall

The theme lives under /usr/share/sddm/themes/kamalen; synchronized user data is isolated in /var/lib/kamalen-sddm. Activation uses only /etc/sddm.conf.d/99-kamalen-theme.conf, so uninstallin[...]

Everyday use

Shortcut	Action
Super + D	Open the launcher
Super + A	Open the Quick/Media/System dashboard
Super + ,	Open Settings
Super + W	Open the wallpaper picker
Super + V	Open clipboard history
Super + Shift + /	Show the shortcut reference
Super + X	Lock the session
Super + Enter	Open Kitty
Super + Space	Cycle window layouts
Super + Q	Close the focused window

More bindings are available in .config/mango/conf.d/binds.conf.

The wallpaper picker includes Local, Wallhaven, and Live tabs. The Live tab filters DesktopHut results by title, accepts only HTTPS downloads from its allowed /files/ host path, and shows the o[...]

Screenshots

_{One color pipeline, four surfaces — the palette stays responsive while the material changes.}

Desktop overview	Local wallpaper browsing

Appearance and materials	Monitor configuration

MangoWM controls	Wallpaper discovery

See the full screenshot gallery for context.

Repository map

.config/                 Live desktop configuration
  mango/                 MangoWM configuration and Python bridge
  quickshell/            QML shell, shared state, components, and helpers
  scripts/               User-facing helper scripts
docs/                    Architecture, specifications, plans, and reviews
tests/                   Python regression and integration checks
sddm/                    Optional Qt 6 login theme
scripts/                 Cross-distribution installation and SDDM sync helpers
nix port tests/          Experimental NixOS/Home Manager flake
wallpapers/              Bundled wallpaper collection

• Architecture
• Current shell guide
• Roadmap
• Screenshot gallery
• Platform support
• Contributing
• Historical specifications and plans
• Historical technical reviews
• Experimental NixOS port

Tip

Start with the current shell guide for daily use, then use architecture when changing the live configuration.

Development and verification

python3 -m unittest discover -s tests -p 'test_*.py'
qmllint -I .config/quickshell .config/quickshell/LiveWallpaperTab.qml
./install.sh verify

After QML changes, restart Quickshell from the active session:

pkill quickshell
sleep 1
nohup quickshell &>/dev/null &

Credits and provenance

Kamalen Shell is an integration project; it does not claim ownership of the technologies or projects it configures.

• MangoWM is the compositor foundation.
• mango-ext is the MangoWM fork used by this configuration.
• Quickshell provides the Qt Modeling Language (QML) shell runtime.
• Catppuccin informs the base palette used by the color system.
• Wallhaven and DesktopHut are optional wallpaper discovery sources; their content remains subject to their respective terms and creator at[...]
• The NixOS/Home Manager work is an experimental port of this repository, maintained in nix port tests/.
• The SDDM synchronization boundary was inspired by iNiR's Pixel SDDM sync helper; Kamalen uses its own implementatio[...]
• Dynamic Island patterns were studied from Dynamic-island-for-arch, Tide-island, [quickshell[...]
• The broader Linux customization community, including r/unixporn, has influenced the visual language and workflow ideas.

License

Kamalen Shell is distributed under the MIT License. See CONTRIBUTING.md for contribution terms. Third-party projects, wallpapers, fonts, and downloaded media retain [...]