Skip to content
sandeepbistPublic

About

Quickshell desktop island and portable Arch Linux / Hyprland dotfiles. Luma, local voice, themes and a window companion.

Resources

Contributing

Security policy

Stars

20 stars

Watchers

0 watching

Forks

Repository files navigation

Modesty

A Quickshell desktop for Arch Linux and Hyprland. Three small pills expand into media controls, a calendar and a control center, with a launcher, Luma search and assistant, notifications, a lock screen and a window companion.

Modesty control center on the maintainer's desktop

Install · Use · Update · Screenshots and video · Uninstall · Contribute · Get help

Optional AMD shell memory reduction

The main-shell startup has an opt-in optimization for a verified AMD Mesa Wayland device. It avoids loading unused EGL vendors inside Quickshell. It does not change animations, shaders, or the GPU environment passed to apps. Other desktops keep normal startup by default.

From a working desktop session, enable it locally and restart:

python3 scripts/shell_renderer.py --enable
python3 scripts/session-control.py restart

The selection is saved in local state, outside the dotfiles. Each startup checks the saved device against normal and Mesa EGL initialization. Changed devices, explicit GPU or plugin choices, preload libraries, reconnect mode, unavailable drivers, and missing compiler support keep normal startup. The helper builds once with the installed C compiler and stays in the user's cache. This applies only to main-shell startup through session-control.py, not direct or preview launches. It does not promise a higher frame rate.

To return to normal startup:

python3 scripts/shell_renderer.py --disable
python3 scripts/session-control.py restart

Install

You need x86_64 Arch Linux, working graphics drivers, a normal user account, internet access and sudo. Modesty installs desktop configs and dependencies; it does not install Arch, graphics drivers, a bootloader or a login manager.

sudo pacman -Syu --needed git
git clone https://github.com/sandeepbist/Modesty.git ~/App/Modesty
cd ~/App/Modesty
./install.sh

Run as your desktop user, not root. The interactive installer explains proposed changes and asks for approval. Change approvals default to No; files and backup locations are shown before config replacement.

Installer choice What it sets up
Required dependencies Arch packages and NetworkManager/Bluetooth services
Configs Desktop, shell, apps, bundled fonts and Spotify theme
Wallpapers Supplied collection, or keep your existing wallpaper and palette
Optional plugins Dynamic cursor effects and Super + Tab window overview
Optional local voice Moonshine Small English speech recognition for Luma
Optional extras AUR apps, Spotify tools and extra fonts

After installation, log out and select Hyprland in your login manager, or run start-hyprland from a TTY. Keep the checkout at the same path: startup and shortcuts use it.

Install previews, backups and path requirements
  • Use --dry-run to preview changes without writing anything: ./install.sh --dry-run.
  • Existing files are backed up before replacement. Package installation uses a full Arch update; AUR apps and local voice are separate choices.
  • Declining or cancelling stops that step. Earlier approved package, service and model changes are retained; file rollback only restores configs.
  • --non-interactive explicitly approves all saved configs, but refuses missing dependencies, disabled services and Qt repairs instead of fixing them silently.
  • Home and checkout paths may use letters, numbers, /, _, ., @, + and -; whitespace and shell/Lua metacharacters are refused before installation. This profile uses ~/.config; unset XDG_CONFIG_HOME before installing.
  • Destination parent directories must be real directories, not symlinks. The installer refuses redirected paths before replacing files.
  • The profile uses Hyprland's Lua configuration. Set monitor arrangement, scale, brightness permissions and suspend/hibernate support for your hardware.
  • Firefox, Pavucontrol and Adwaita cursors are defaults; installed Zen and Pwvucontrol take priority.
  • Spotify needs a separate installation and first launch before spicetify backup apply.
Optional cursor effects and window overview
  • The installer asks separately about dynamic cursor effects and window overview. It builds and enables selected plugins through hyprpm, with Modesty's settings.
  • On a fresh TTY install, setup finishes after your first Hyprland login. A terminal opens automatically; enter your sudo password if requested.
  • The terminal lists selected repositories and asks before building, enabling or reloading plugins. Declining keeps the selection pending.
  • Plugin compatibility depends on upstream. Both plugins are optional; a failed upstream build leaves the desktop usable. Run hyprpm update after compositor updates.

Retry setup from the checkout after checking Hyprland compatibility:

python3 install.py --finish-plugins
Optional local voice: installation and privacy

Choose voice during installation, or open Settings → Luma → Voice → Install local voice. The panel also offers repair/retry. Terminal setup uses the same installer:

python3 install.py --install-voice
  • Setup downloads and verifies Moonshine Small English and installs an isolated CPU runtime. Models and the Python environment stay outside the checkout.
  • Hold Ctrl + backtick to speak to Luma; release to submit. Transcription runs locally and needs no API key.
  • Voice loads on demand; Settings can keep it ready.
  • AI answers use your configured cloud provider. Submitted speech becomes text sent to that provider, together with enabled context and tool results. Local speech recognition does not make the assistant itself local.
  • Application launching, calculations and local search work without an AI key.

Use

Input Opens
Album-art pill Media controls
Clock pill Clock; calendar available from the clock panel
Status pill Control center
Tap Super Application launcher
Super + Space Luma search and assistant
Super + comma Settings
Super + Alt + N Quick Notes; customizable in Settings
Super + L Lock screen
Escape / outside click Dismiss the current panel
Feature What to expect
Volume and brightness Changes temporarily widen the clock pill
Settings Spacing, motion, colors, control-center layout, notifications and companion; reduced motion supported
Privacy indicators Microphone/camera activity while capture is active; microphone mute controls in the privacy panel
Luma Applications, files, file contents, clipboard entries, calculations, web search and desktop actions; AI answers use your configured cloud provider
Quick Notes Plain text and Markdown capture, search, pins, Archive, Trash, restore, and Markdown export
Reminders One-time advance notices and daily, weekly, weekday, or monthly calendar recurrence with a timezone
Agent activity T3 Code task status: working, waiting and completion feedback

Settings uses five categories with page tabs and remembers the last page in each category. Search individual controls with Ctrl+F, then use Up/Down and Enter. Unavailable controls stay visible and link to their prerequisite. Music and media share one page. Unsaved personal notes and provider key inputs remain in the current Settings window when you switch pages or search.

For palette-matched folder icons, enable Settings → Colors & typography → Palette folders. Adwaita and Papirus are supported; other icons keep your existing theme. This option starts off. Disabling it restores the original icon theme; uninstall also restores it. Thunar uses a translucent selection tint with opaque text; this is not a blur effect.

Optional animated terminal: the interactive installer offers a separate Kitty profile, with the choice off by default. Foot cannot animate cursor movement. Accepting this option leaves Foot, Super+T, launcher defaults and your normal Kitty configuration unchanged. Missing Kitty requires a separate approval for a full Arch upgrade. The upgrade can change Qt/Quickshell compatibility; file rollback and uninstall do not undo packages. Final file approval covers the profile, native effects include, palette include and Fish wrapper. Default noninteractive installs and ordinary dry runs omit these files.

After installation, run modesty-terminal from Fish or use Settings → Terminal → Open animated terminal. Native cursor trail enables or disables the installed profile. New Modesty Kitty windows pick up changes; existing windows keep their current setting. Settings offers approved setup or repair when Kitty or the owned profile is unavailable. To install only this option later, run python3 install.py --install-terminal-effects. This interactive branch does not reapply desktop files. Uninstall backs up later edits and restores recorded originals for all four optional files. Declining the option on reinstall preserves a previous opt-in.

Luma permissions and supported agent integrations
  • Configure an optional provider key in Settings. Desktop access defaults to Review, and knowledge folders start empty. Every generic command asks for confirmation in Review mode.
  • Full access allows broader automatic actions; enable it deliberately. Read security and privacy before enabling AI context/tools.
  • Agent activity tracking currently works with T3 Code only. Modesty reads task status metadata, not T3 prompts or credentials.
  • Standalone Codex, Claude Code and OpenCode CLI integration is planned and is not implemented yet.

Open Notes from the control center or its shortcut. Start typing in the body; the title is optional. Library searches your notes and opens Archive or Trash. The overflow menu has pin, archive, trash, and export actions. Notes keep your draft, cursor, and scroll position when the panel closes. Wait for Saved before ending the session. A failed save keeps the draft available for retry.

Typed and spoken Luma requests use the same native controls. For example, say "Take a note: buy milk", "Append eggs to this note", or "Remind me to drink water every weekday at 9 AM". Luma asks when a note or time is ambiguous. It reads note bodies only through scoped Notes tools. Edits require the current revision and cannot overwrite unsaved typing.

Native actions cover notes, reminders, audio devices and microphone mute, Wi-Fi, Bluetooth, media, recording, notifications, appearance, wallpaper, display, presentation preferences, and session and update controls. Hardware capabilities determine which actions are available. Passwords, pairing, display confirmation, and administrator authentication stay in their native panels. Access and privacy permissions require Settings. Requested means completion is pending; Saved and Verified require a persistence receipt or observed result.

Update

Versioned downloads and release notes · Changelog. Release archives are installation snapshots; clone the repository for Settings updates. Published versions appear on GitHub Releases.

Modesty has a built-in updater in Settings → System → Updates.

  1. Choose Check for updates.
  2. Choose Download to validate the new revision.
  3. Choose Install and reload to apply it and restart the shell.

Checks and downloads run only when requested. The updater uses the latest main revision with passing GitHub checks, validates it in a separate checkout, then switches and reloads. If startup fails, it attempts to restore and restart the previous revision. Roll back restores the revision saved before the last update.

Don't see Updates in Settings? Your installation may predate the updater. Review upstream changes and local edits, then run from your Modesty checkout on main:

git pull --ff-only
python3 scripts/session-control.py restart

If Git reports local changes or diverged history, resolve those first; keep your custom work. If the release needs new configs or dependencies, review and rerun ./install.sh before restarting. Future updates can then use Settings.

Update requirements and what stays unchanged
Requirement Details
Checkout Clean main branch with the official origin
Local changes Edits, untracked files, diverged history and forks need manual updates; conflicting ignored files also block installation
Session Finish voice input, assistant work and recording first; reload is refused while the desktop is locked
Free space At least 256 MiB on both checkout and state filesystems; larger downloads can require more
  • Updates preserve installed configs, packages, plugins, keys and model files. They do not apply new setup/ defaults or install dependencies.
  • For new configs or packages, review changes and rerun the installer separately. It skips identical files and backs up replacements, including customized configs.
  • Update Arch separately with a full system upgrade. Rebuild your installed AUR Quickshell variant when Qt changes; run hyprpm update after compositor updates.
  • Do not remove a pacman lock to bypass an active package transaction.

For a manual update that also applies reviewed installation defaults:

git pull --ff-only
./install.sh
python3 scripts/session-control.py restart
Supported versions and optional Qt repair
Runtime Supported versions
Hyprland 0.56.x
Quickshell 0.3.1 or newer within 0.3.x
Package variants Stable and -git, checked by actual runtime version; variants are not changed
  • Requirements live in runtime-requirements.json. Missing dependencies, mixed Qt major/minor versions, Quickshell Qt warnings and a compositor that differs from the installed binary block installation.
  • New minor releases need a reviewed compatibility range. These checks do not guarantee every driver or plugin works.
  • If Quickshell was built against a different Qt version, the interactive installer offers an optional rebuild before applying configs. It preserves quickshell or quickshell-git, builds as your normal user and uses sudo only for package dependencies and installation.
  • Compilation may take several minutes and needs at least 3 GiB free in the temporary filesystem. It defaults to two jobs unless you set CMAKE_BUILD_PARALLEL_LEVEL.
  • Stable 0.3.1-1 needs a checksummed upstream Qt 6.12 fix, which the repair backports without switching to the development package.
  • Declining repair or using --non-interactive stops before replacing configs. OTA never performs this rebuild; rerun the interactive installer to repair Qt.
Interrupted update or unavailable Settings panel

Run from the checkout:

python3 scripts/updates.py status
python3 scripts/updates.py rollback

Rollback requires the saved revision, a clean checkout and a compatible runtime. It does not undo a separate system upgrade or installer run.

Screenshots and video

Captured from the maintainer's live Hyprland desktop, using the installed shell and personal wallpaper. The installer supplies a separate, credited wallpaper collection. Colors, panel layout and apps can differ on your machine.

Calendar Themes
Live calendar panel Live theme picker
Launcher Local voice setup
Live application launcher Local voice settings on the live desktop

Watch island transitions

Watch the full-resolution clip · Watch volume and brightness transitions

Customize

Location Purpose
$XDG_STATE_HOME/modesty (normally ~/.local/state/modesty) User preferences
~/.config/modesty/desktop/hypr-vars.lua Apps and shortcuts
setup/ Public installation templates; the installer does not copy the maintainer's live home directory

Keys, saved network credentials, Bluetooth pairings, conversations, personal notes and model caches are not part of the install.

Uninstall and restore

Preview removal, then confirm it interactively:

./install.sh --uninstall --dry-run
./install.sh --uninstall

Uninstall backs up current installed files, including later edits, restores the first recorded originals and removes files Modesty originally created. It stops the running shell after safety checks. Finish assistant work, voice input and recording first; log out before using the restored desktop.

Unrelated files, packages, accounts, keys, conversations, model caches and the checkout remain in place.

Receipts, backups, interrupted installs and older setups
Record Location
Installation receipt ~/.local/state/modesty-install/receipt.json
Backups ~/.local/state/modesty-install-backups/<timestamp>/, or your custom state directory

The installer records files it replaces in the receipt. Keep backups until you have checked the restored files.

Interrupted file transaction: further changes are blocked. Preview recovery with ./install.sh --recover-install --dry-run, then run ./install.sh --recover-install. Recovery previews affected files, asks for approval and backs up surviving files first.

Older installation with no receipt: review ./install.sh --adopt-existing --dry-run, then use ./install.sh --adopt-existing to record exact template matches. Customized files are excluded. Original contents are unknown, so uninstall backs up and removes adopted files; restore pre-Modesty configs from older backups manually. Adoption cannot reconstruct missing originals.

Existing Caelestia Lua setup: ./launch.sh --switch performs a reversible shell handoff; ./launch.sh --restore restores it when its backup exists. A fresh installation does not require Caelestia.

Troubleshooting

Found a bug, stuck during setup, or unable to fix an issue? Open an issue ticket. Include what you tried, steps to reproduce, the command, error and package versions. Remove keys and personal data from logs or screenshots before sharing.

Problem Try this
Shell did not start From the checkout, run quickshell ipc -p "$PWD/shell.qml" call island health. If no instance exists, run python3 scripts/session-control.py restart and keep its error output
Plugin failed to build Check Hyprland compatibility, then retry python3 install.py --finish-plugins
Voice is missing Use Install/Repair under Settings → Luma → Voice
Updates page is missing Pull the latest revision and restart
External monitor has no brightness slider DDC brightness is not implemented; the slider uses supported backlight devices
What has been tested
  • Offline checks passed with Qt 6.11.2 and 6.12.0, each using a matching Quickshell build, and in an Arch container.
  • Fresh-container tests covered package provisioning, stable Quickshell Qt 6.12 repair, interactive installation as a normal user and uninstall.
  • Disposable-home checks covered repeat installs, original config restoration, edited-file backups and preservation of personal files, keys and model caches.
  • UI, audio and reload were checked on the live desktop.
  • File drops passed centre/edge, quick-release, cancellation and rejected-offer checks with Qt 6.11.2 and 6.12.0, each using a matching Quickshell build.
  • Physical GPU drivers, login behavior and optional plugin builds remain outside container coverage.

Contribute

Bug reports, small fixes, accessibility improvements and feature proposals are welcome. Read the contribution guide, fork the repo and open a pull request. Discuss larger changes in an issue first. The maintainer reviews and merges contributions. Opening a PR does not grant write access. Maintainers: see checks, review and releases.

Checks to run and source layout

Run offline checks before submitting code:

python3 tests/check.py
  • Checks need desktop dependencies, Node.js and Lua. They cover real Git update and rollback transactions, installer backups and recovery, template isolation, backend behavior, isolated D-Bus services, security boundaries and QML loading.
  • Live input/hardware checks require explicit --live and are not part of this command. QML loading checks do not replace visual review.

With required packages and services already installed, run the real CLI as a normal user in a disposable home and source copy:

python3 tests/installer-cli.py --isolated-home

This check does not install packages, start a desktop or change your real home. It checks dry-run, install, repeat install and uninstall, including preservation of original files, edits, keys and model data.

Directory Responsibility
services/ Shared state
modules/ UI
components/ and theme/ Shared visuals
scripts/ System integration
setup/ Portable installation defaults

Research, private notes and disposable outputs stay out of the public source tree.

License and credits

Modesty code and adapted configs use GPL-3.0. Hyprland configs are adapted from Caelestia. Fonts, icons, vendored code and third-party images retain their own terms; see third-party notices.

About

Quickshell desktop island and portable Arch Linux / Hyprland dotfiles. Luma, local voice, themes and a window companion.

Resources

Contributing

Security policy

Stars

20 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages