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.
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 restartThe 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 restartYou 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.shRun 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-runto 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-interactiveexplicitly 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; unsetXDG_CONFIG_HOMEbefore 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 updateafter compositor updates.
Retry setup from the checkout after checking Hyprland compatibility:
python3 install.py --finish-pluginsOptional 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.
| 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.
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.
- Choose Check for updates.
- Choose Download to validate the new revision.
- 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 restartIf 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 updateafter 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 restartSupported 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
quickshellorquickshell-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-interactivestops 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 rollbackRollback requires the saved revision, a clean checkout and a compatible runtime. It does not undo a separate system upgrade or installer run.
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 |
|---|---|
![]() |
![]() |
| Launcher | Local voice setup |
|---|---|
![]() |
![]() |
Watch the full-resolution clip · Watch volume and brightness transitions
| 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.
Preview removal, then confirm it interactively:
./install.sh --uninstall --dry-run
./install.sh --uninstallUninstall 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.
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.
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
--liveand 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-homeThis 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.
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.





