Files
lucid/README.md
T
Sn3aky d1bcf8a69d Wallpapers: the set as it stands
The bundled wallpapers follow the folder they are curated in: 60 in (new
pictures and live wallpapers, in both the Matugen and the Pywal sets), 55 out.
The README gives the new size for --no-wallpapers.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-13 18:46:06 +01:00

40 KiB
Raw Permalink Blame History

Lucid

Lucid

Lucid is an ecosystem.

A Material 3 Expressive desktop for Hyprland, built on Quickshell.
The shell, its own apps, its own icons, pointer and login screen, all coloured by your wallpaper.

Website  ·  Install  ·  Tour  ·  What's in it  ·  Keybinds  ·  IPC  ·  Changelog

Version Stars Last commit License

Arch Linux Hyprland Built on Quickshell Website

The Lucid desktop in blue: a clock, a calendar, the song playing and the weather on the left, battery, system and to-do widgets on the right, and the visualiser along the bottom

Tip

New in v1.21: Lucid is an ecosystem. Lumen for your files and every app's file dialog, Lens for pictures and videos, LucidShot rebuilt, edit mode on the desktop, a bar that can take the bottom edge, a control centre you lay out yourself, lyrics for whatever plays, and icons and a pointer of Lucid's own. The shell shows the highlights once after you update; everything is in the changelog.

Note

Hear about new versions with Watch → Custom → Releases at the top of this page, or let Lucid tell you: it asks GitHub once a day and updates itself from Settings → About when a release is out. See Updating.

The ecosystem

The shell Its apps Its look

The bar in islands, notches or one full strip, top or bottom
A dock that grows into the launcher
The control centre, laid out by you
Desktop widgets and desktop icons
Edit mode to arrange it all in place
Notifications, the OSD and toasts
Lock and login screen

Lumen, files and every file dialog
Lens, pictures and videos
LucidShot, screenshots, text, colour and recording
Settings, the whole desktop without a config file
Lyrics, music and the visualiser
Emoji, GIFs and the clipboard
A phone, over KDE Connect

One palette from your wallpaper, light or dark
Every app themed along: GTK, Qt, KDE, kitty, Zen, VSCodium
Icons of Lucid's own
A pointer of Lucid's own
Sounds of its own
Motion on springs
Google Sans Flex, built in

A tour

Settings, Lumen and Lens open together in a red palette
Its own apps. Settings, Lumen and Lens, all in the colours of the wallpaper.
Edit mode with the widget panel open
Edit mode. The widget panel beside the desktop it arranges.
The control centre's editor: blocks to add, the panel and layouts to start from
The control centre's editor. Blocks to add, the panel itself, and layouts to start from.
Lumen in a green palette
Lumen. Places, folders and a preview pane, in a green palette.
The Lyrics widget singing along word by word
Lyrics on the desktop. The widget sings along, word by word.
The media panel's Lyrics page
Lyrics in the bar. The media panel follows the song line by line.
The bar as one strip along the bottom edge
The bottom edge. One full bar, the dock's apps in the middle of it.
LucidShot over a frozen screen
LucidShot. Drag out a region or click a window on the frozen screen.
Desktop icons beside a shaped clock, the song playing, today's date and the day's progress
Desktop icons and widgets. Your Desktop folder on the wallpaper, a shaped clock, what is playing, today and how much of the day has gone.

Install

Lucid needs Arch Linux and Hyprland 0.55 or newer (the installer brings Hyprland if it is missing), and installs to ~/.config/quickshell:

git clone https://github.com/Sn3akyy1/lucid.git
cd lucid
./install.sh

In a Wayland session that opens the installer in a window, with a tour of Lucid playing while it works: pick what comes with it with switches, enter your password once, and answer anything it asks with buttons. Start Lucid at the end puts the new binds live and starts the shell. Without a Wayland session, with any option on the command line, or with --terminal, it runs in the terminal instead. Set a wallpaper from Settings → General on first run; that is what your colours come from.

What the installer does
  1. Checks your system and refuses to start anything it cannot finish, rather than leaving you half-installed.
  2. Installs dependencies through paru or yay when there is one, pacman otherwise. It lists everything and asks first; say no and it carries on, naming the features that won't work. This includes the apps the dock ships pinned, several GB and mostly from the AUR (--no-apps skips them).
  3. Copies the shell to ~/.config/quickshell, moving an existing one to ~/.config/quickshell.backup-<timestamp> first, and carries your settings, pins, reminders and keys forward. Lumen and Lens come with it: Lumen opens folders, SUPER+E and every app's open and save dialog, and Lens opens pictures.
  4. Sets up Hyprland: hyprland.lua and its modules, the keybinds, window and layer rules, blur, animations and an autostart. A config of your own is backed up and you are asked first (--no-hypr keeps it untouched, and it still gets the one module Lumen's dialogs need). On a re-run every module is checked against the one in place: new and updated ones are named, and so is one you edited, with your version in the backup.
  5. Sets up theming: the palettes, the wallpaper hook and the matugen templates. An existing matugen/config.toml is appended to, never replaced.
  6. Applies the look: kitty's colours, opacity and fish, the starship prompt, a fastfetch config (only where you have none), the VSCodium theme, and GTK as adw-gtk3-dark with the FairyWren icons, in gsettings and both settings.ini. --no-look skips it.
  7. Builds the tilting cursor, a Hyprland plugin compiled against your own Hyprland and rebuilt by itself after an update (--no-plugins skips it).
  8. Offers the login screen when SDDM is there, or to make SDDM the login screen, and pins the dock with the apps you actually have.
Installer options
Flag What it does
--gui The installer window, its switches set from the other options given. The default in a Wayland session
--terminal Stays in the terminal
--no-theming Skips the palette layer and leaves ~/.config/lucid and ~/.config/matugen alone
--no-hypr Keeps your Hyprland config. Lucid's binds, rules, blur and autostart are not installed
--with-hypr Reinstalls Lucid's Hyprland config even when one is in place
--no-apps Doesn't install the apps the dock ships pinned (Zen, VSCodium, Spotify, Vesktop, Steam, Proton VPN)
--no-look Leaves kitty, starship, fastfetch, your shell rc files, VSCode and GTK alone
--no-wallpapers Doesn't copy the bundled wallpapers (about 1.3 GB, live ones included)
--no-plugins Doesn't build the tilting-cursor plugin
--no-sddm Leaves the login screen theme out
--login-screen Makes Lucid's theme the one the login screen shows (Current=lucid, backed up first)
--skip-deps Never installs packages, only reports what is missing
-y, --yes Accepts every prompt

Updating

From v1.21 on, Settings → About has an Update button whenever a new release is out (the notification that announces it has one too): a warning, your password once, then a pop-up with a progress bar that also asks anything the installer would ask in a terminal. It runs that release's own installer and offers to restart Lucid at the end. The password goes to sudo once and is never stored. Only a published release counts, unless you turn on Beta updates, which offers the newest commit on main and warns that beta builds are untested. By hand it is the same as installing:

git pull
./install.sh
How the update check works, and older versions

Once a day Lucid asks GitHub's public API for the newest release, a plain curl for api.github.com/repos/Sn3akyy1/lucid/releases/latest that carries nothing about you, and posts one notification per version. Settings → About shows what it found and turns it off.

qs ipc call updates status   # what it knows
qs ipc call updates check    # ask now
qs ipc call updates update   # install the new release (warning first)

Older versions stay on the releases page and as tags: git clone --branch v1.20.1 https://github.com/Sn3akyy1/lucid.git.

Uninstall
./uninstall.sh

It moves ~/.config/quickshell aside rather than deleting it, so your settings survive, and leaves the packages alone. The installer notes how things stood before it first changed them, and the uninstaller offers to put those back: the login screen, the GTK theme, icons and dark mode, and your own Hyprland config (or Hyprland's default). It ends by naming the desktop to log back into, and lists what else it left in place, each with a timestamped backup beside it.

What's in it

Every surface is themed from the same palette and moves the same way. Click a part to open it.

The bar

Islands, notches or one full strip, along the top or the bottom

Eleven modules, each a pill that opens into a panel: Workspaces, Media, Tray, Clock, Notifications, System, Privacy, Power, the window title, Start and Apps. Three shapes: islands (floating pills), notches (flush with the edge, blending into it) and the full bar (one strip across the screen, hanging into its corners). Position puts it on the top or the bottom edge, and it slides over to the new one.

  • Panels open as one shape with the bar. On a full bar and with notches an open panel grows out of the bar with no seam, panels side by side merge, and a module at either end can meet the screen's side and curve into it.
  • Joins. In edit mode the link between two neighbours joins them into one island or one notch, and a join holds across a module that has emptied out.
  • Workspaces with live window previews, a run of dots per display, and the scratchpad's apps as glyphs while it is open.
  • Media as a turning disc, a still cover, bars, a progress pill or with previous, play and next; its panel side by side, with a large cover, as a turning record, over the blurred cover, or mini. Lyrics are a click away.
  • Tray, rebuilt: each app in a slot of its own, or three stacked with a count. A click opens the tray, where each app is a row with its real name and its menu opens right in the row.
  • Clock with the date, the time on an accent chip, and behind it today, the month with reminders, timers and a pomodoro, a stopwatch and world clocks.
  • System: whichever of Wi-Fi, Bluetooth, the volume and its level, the microphone and the battery you pick, opening onto the control centre.
  • Start opens the launcher, drawn as the dock's launcher button, Lucid's mark, your distro's logo, your picture or the word Start. Apps puts the dock's apps on the bar, with dots, names, menus and drag to reorder.
  • On the bottom edge the dock steps aside, and on a full bar the launcher rises out of the bar itself, one piece of glass with it.
  • Open on hover, Auto-hide, a bar on every display, and Content size, which scales what is in the bar from 80 to 140% without changing its height.

Control centre

Quick settings on a grid you lay out yourself
The control centre's editor

The System pill opens the control centre: brightness and volume with their devices behind them, Wi-Fi and Bluetooth with full panels, tiles, what is playing, and gauges for the CPU, memory, disk and battery. Untouched it is one column; the pencil opens its editor, lifted off the bar to the middle of the display. Drag blocks in from the library on the left (sliders lying or standing, big tiles and small ones, media, gauges, the weather, the network, power profiles and what is up next), stretch them by any edge, and pick each one's look on the right, or start from a layout. Undo, a right-click menu, keys for everything, and tiles of your own that run your commands. qs ipc call controlcentre toggle opens it from a keybind.

Dock and launcher

A dock that grows into the launcher, with eight modes in one field

A floating toolbar with your pinned apps and running windows, drag to reorder, optional magnification, and auto-hide that can be Dynamic: tucked away only while a window is in the way. Three styles: island, notch (with edge blends) and split, the launcher, the pins and the running apps as three islands that fuse when the launcher opens and spring apart again. Pull a pin up onto the desktop for a shortcut there. With the dock hidden the launcher opens as a notch from the bottom edge.

The launcher is one search field over eight modes, each reachable by a pill, Ctrl and its number, Tab, or a prefix:

Mode Prefix What it does
Apps Fuzzy search over your apps, their own actions and open windows; vsc finds Visual Studio Code
Commands > The shell's commands, power actions included
Emoji : The emoji picker's list; Return copies one
Web ? Searches your engine, or opens what you typed if it is an address
Run $ Runs a command, in the background or in a terminal that stays open
Theme >theme Switches palettes
Wallpaper >wallpaper Your wallpapers as a strip, pills, tiles or a bento grid, live ones beside them
Clipboard >clip What you copied, images included

Type a sum for a calculator. Wallpapers change with a transition you pick (fade, wipe, wave, grow and the rest of what awww does), and live wallpapers play videos behind the desktop, holding still under a fullscreen window.

Desktop widgets

Twenty-five kinds, close to ninety looks, placed on the wallpaper

Open the widget panel (edit mode, the desktop's right-click menu or the launcher's Widgets pill) and drag a widget out, or click it to drop it in the first free spot. Each one has a sheet with every look drawn live, its colour, size and own options, and snaps to the edges, the centre lines and the others.

Widget Looks
Clock Digital, stacked, analog, inside an expressive shape, minimal, world clocks, a band across a round face, a scalloped dial, or the hour over the minute as a poster on the bare wallpaper
Calendar The month, this week, today, or your next reminders
Progress How much of the day, week, month and year has gone, as a wavy ring, bars or dots
System Rings, meters, a graph, tiles or network throughput
Quick toggles Round switches that turn into shapes, a pill of buttons, or Quick Settings tiles
Battery A ring, a cell, full detail, or every wireless device that reports a charge
Media Eight looks, from an artwork card to a cover cut to a shape that morphs with every track
Lyrics Word by word, karaoke, or the whole song scrolling by
Visualiser Bars, mirrored bands or a wave, sized by dragging any edge
Weather and Sun Now, a forecast, a curve of the next hours, sunrise and sunset
Notes and To-do A sticky note, a ruled sheet, one line; a checklist or just the next thing
Timer Countdown, pomodoro or stopwatch
At a Glance The date, the weather and the one thing worth knowing now
And more Photo, Fetch, Thermals, Network, Games, Shortcuts, Search, GitHub, Palette, Phone

Desktop icons

Your Desktop folder on the wallpaper, the way a real desktop has it

Turned on in Settings → General → Desktop icons. Icons from your icon theme (or Lucid's own), thumbnails, the Trash and your drives; click, Ctrl- or Shift-click or draw a box, drag into folders, the Trash, a drive or another app. Right-click for Cut, Copy, Rename and Delete along the top, Open With, Quick Look (Space), Get Info, Compress and Extract, Send To (folders and phones), tags and more; right-click the desktop for New Item, View and Arrange By. Everything can be undone, and every key can be changed on the Keybinds page. Widgets keep their space: icons step aside together and come back after.

Edit mode

Arrange the bar, the dock and the widgets where they stand
Edit mode with the widget panel

Pick Edit Desktop from the desktop's right-click menu, or right-click any bar module, and the wallpaper shades over. Drag a bar module along the bar, into another group, or down off it; join neighbours into one island; drag the dock's handle up to float it or down into the edge to make it a notch. Right-click a module or the dock for a sheet of its options beside it. The toolbar opens the bar, dock, widgets and wallpaper; Undo (Ctrl+Z) and Revert take changes back, and Done or Escape leaves.

Lumen

A file manager of Lucid's own, and every app's file dialog
Lumen

SUPER+E, the dock or any folder opens it, and every app's Open and Save dialog is a Lumen window, with filters and an overwrite check. Tabs you can pin, colour and drag out into a window of their own; bookmarks with names and colours (Ctrl+D); Recent, Trash and your drives; a grid or a list from 24 to 256 pixels and a preview pane. Network drives: Connect to server (Ctrl+K) opens smb://, sftp://, ftp:// or a Windows \\server\share, signs in as a user or a guest with the password in your keyring, and shows the computers nearby. Copies and moves run in the background, and Lumen waits for them before it quits.

Lens

Pictures and videos, with an editor that never loses the original

Open a picture and its whole folder comes along: arrow keys, swipes and a filmstrip, All pictures (G) to search the folder, zoom and pan with a map. Edit (E) crops, turns, straightens, adjusts light and colour or applies one of twelve looks; Draw (D) adds pens, arrows, shapes, words and pixelation. Saving over a picture keeps its original for good, to bring back whenever you like. Videos play in place with a waving time line, speed, frames to save and Trim. Details, slideshow, full screen, and sending to your phone.

LucidShot

Screenshots, recordings, text and colours from one toolbar
LucidShot

Print freezes the screen under a toolbar: Screenshot, Record, Text or Colour, of a region, a window or the whole screen. A magnifier, edges that snap to windows, Shift for a square, Space to move. The capture flies into a card to open in Lens, mark up, pin over your windows, read the text off or drag into an app. Text reads the words in any part of the screen (tesseract, emoji and QR codes included) and pastes paragraphs as paragraphs; Colour copies HEX, RGB or HSL and collects palettes; Record takes what is playing and the microphone, with a countdown, a pill in the bar, and a GIF from the card.

Music

Lyrics, covers, song identification and a visualiser
The media panel's Lyrics page

The media panel's Lyrics page scrolls with the song: the line being sung springs up and fills with colour letter by letter, and a click on a line seeks there. The Lyrics widget sings along on the desktop word by word, as karaoke, or as the whole song scrolling by. Words come from lrclib.net, looked up only while something shows them and kept on disk. Identify names the song playing around you (songrec), and cava draws the visualiser, resting while nothing plays.

Lock, login and session

A lock screen, a matching login screen, and the session screen
  • Lock screen: a real session lock checked through PAM, with an oversized clock in the wallpaper's colour, the weather, battery, network and Bluetooth at a glance, what is playing, notifications and a power bar. It counts your tries against faillock, warns about Caps Lock, plays a live wallpaper behind its blur, and takes a fingerprint (with fprintd) as well as the password.
  • Login screen: the lock ported to SDDM, painted from the shell's own colours, each account with its own wallpaper and palette, live wallpapers included, and fingerprint login if you want it.
  • Session screen (SUPER+Esc): lock, sleep, log out, restart and shut down on expressive shapes; the ones that cost you work ask twice.
  • Authentication: Lucid is the session's polkit agent, so every administrator prompt comes up in its own dialog.

Notifications, OSD and sounds

Grouped notifications, a notch OSD, toasts and Lucid's own sounds

Notifications are grouped by app with inline reply and progress bars, the newest growing out of the bell; do-not-disturb has quiet hours and a rule for fullscreen windows. The OSD shows volume, brightness, the microphone, Caps Lock and Num Lock as a card or as a notch rising out of the bottom edge, and with the dock a notch too, the dock itself turns into it. Toasts say small things under the bar, and any script can raise one (qs ipc call -- toast show game "Game Mode On"). Sounds: eight notification sounds and the system's own, synthesised for Lucid, each with a switch.

Settings

The whole desktop, without a config file

A searchable app (Ctrl+F, or just type) with a page for every part of the system, a reset arrow on anything you changed, and a What's new sheet after each update. Among the pages:

  • General with Interface size (75 to 125%), Corner rounding and Motion
  • Bar, Dock, Launcher, Widgets and Workspaces
  • Theme, Colours, Palettes and Glass
  • Windows (gaps, borders, corners, shadows, tiling, focus) and Input (layouts, repeat, mouse, touchpad, swipes), live through Hyprland
  • Displays: resolution, refresh, scale, rotation, arrangement and mirroring
  • Network, Bluetooth (files both ways) and Phone, a full KDE Connect client with files, notifications, a media remote and a touchpad
  • Sound, every device, socket and profile, a slider per app, and outputs played together
  • Notifications, Idle (hypridle with sliders), Storage (what fills the disk, as a map), Date & Time (location, weather, units, time zone)
  • Environment: cursor, icons, GTK and Qt themes and fonts, set everywhere at once, Lucid's own pointer included
  • Startup: apps at login, system autostart and environment variables
  • Keybinds, Users and Accounts, Screenshots and About

Special workspaces

Scratchpads for music, chats, to-dos and the system monitor
Keys Workspace Opens
SUPER + SHIFT + S Scratchpad Somewhere to park windows
SUPER + SHIFT + M Music Spotify, Feishin, Cider, YouTube Music, TIDAL…
SUPER + SHIFT + D Comms Discord, Vesktop, Telegram, Signal, Element, Slack…
SUPER + SHIFT + R To-do Todoist, Planify, Errands, Obsidian…
CTRL + SHIFT + Esc System btop, Mission Center, Resources…

A key starts its app if needed and slides the workspace over the one you are on; the same key hides it. SUPER+ALT+S stashes a window in the scratchpad. Settings → Workspaces picks the apps, the dimming and blur, and makes workspaces of your own.

Look and motion

Springs, Lucid's own icons and Lucid's own pointer
  • Jelly motion. Panels, pills, menus, the dock, the OSD and widgets settle on a spring with a little wobble. Settings → General → Motion sets how much, or turns it off.
  • Icons. Folders, files, places, drives and many apps share one tonal set drawn from your palette, in Lumen, on the desktop, in the dock and the launcher. An app the set doesn't know keeps its own icon.
  • Pointer. Bibata Modern's shapes in your palette's colours (Dark, Light or Accent), fading along when the palette changes, drawn on your machine from Bibata's source. A tilting cursor leans the arrows and hands as they move, and in a drag the shell draws the pointer itself so it stays on what it holds. Any other cursor theme is a switch away.
  • Glass. One slider for how far the desktop shows through the shell, kitty and your windows.

Theming

One palette from your wallpaper, everywhere

Matugen and Pywal build a palette from your wallpaper, Your colour from one colour you pick, and Catppuccin Mocha, Gruvbox, Nightfox, Nord and Tokyo Night are fixed palettes. Every one has a light mode, and the theme can follow each new wallpaper into light or dark. Settings → Colours sets Matugen's style, its contrast and which of the wallpaper's colours to start from.

The palette reaches beyond the shell: Hyprland's borders, kitty, starship, GTK, Qt and KDE apps (through qt6ct and a colour scheme), Zen, VSCodium and the login screen follow it, and any app can through a matugen template:

[templates.myapp]
input_path = '~/.config/matugen/templates/myapp.css'
output_path = '~/.config/myapp/colors.css'
post_hook = 'pkill -USR1 myapp'   # optional: tell the app to reload

Settings → Colours lists every template with how its last render went, adds the ones Lucid ships for apps you have, and takes your own from a file or a link. Settings → Palettes adds themes from a gallery of a few hundred base16 and base24 schemes, from any scheme repo or file, or from its editor, and exports the palette on screen as a Lucid palette or base16 YAML.

python3 ~/.config/lucid/add-theme.py <repo-url|file|folder> [--list] [--variant <name>] [--name <label>]

Keybinds

The binds Lucid ships  (SUPER + / shows them all, and Settings → Keybinds changes any of them)
Key Does
SUPER (tap) Launcher
SUPER + P Commands
SUPER + T / B Theme / wallpaper picker
SUPER + SHIFT + V Clipboard history
SUPER + S Settings
SUPER + . Emoji picker
SUPER + K On-screen keyboard
SUPER + / Every keybind
SUPER + W Workspace overview (or a three-finger swipe)
SUPER + Esc Session screen
CTRL + ALT + TAB Window switcher, newest first (+SHIFT steps back)
Print / SUPER + D LucidShot
SUPER + Print Whole screen
SUPER + SHIFT + T / C Copy text / pick a colour
SUPER + E Lumen
SUPER + C Close the window
SUPER + V Float it at 1366×768, centred, or tile it again
SUPER + J Toggle the split
SUPER + 1–0 Workspace (+SHIFT moves the window there)
SUPER + arrows Move focus
SUPER + R Reload Hyprland
SUPER + M Exit Hyprland
F1–F6 Mute, volume, microphone, brightness
F8 / F9 / F10 / F12 Radios / terminal / lock / calculator

Everything is also reachable over IPC, so a config of your own can bind it:

hl.bind("SUPER + SPACE", hl.dsp.exec_cmd("qs ipc call -- launcher toggle"))
hl.bind("SUPER + L",     hl.dsp.exec_cmd("qs ipc call -- lock lock"))
hl.bind("SUPER + A",     hl.dsp.exec_cmd("qs ipc call -- controlcentre toggle"))

Keep the --: a call that takes an argument fails without it (qs ipc call -- settings show bar), and it does no harm elsewhere.

IPC reference

Every surface is scriptable: qs ipc call -- <target> <function> [arg]
Target Functions
launcher toggle open close wallpaper live theme power emoji clipboard blur command shuffle search <query> hide <id> unhide <id> hidden
controlcentre toggle open close
media toggle open close identify lyrics playPause next previous
clock open <tab> toggle close, tab being today, calendar, timer, stopwatch or world
timer start <seconds> stopwatch pomodoro pomodoroSkip pomodoroStop pomodoroAdd <minutes> status
alarm add <hour> <minute> <label> remove <id> list stop snooze status
workspaces toggle open close
settings toggle open close show <page> search <words> reset, and a function per page (bar, sound, displays…)
edit toggle on off bar dock open <module> close undo revert status
widgets panel openPanel <screen> closePanel add <type> <variant> remove <uid> preset <name> save <name> list catalogue toggle lock unlock…
desktop icons arrange selectAll undo refresh
snap toggle open close text color video
recorder toggle start stop pause status
screenshot full text
notifs toggle open close clear toggleDnd expandAll settings count
toast show <icon> <label> warn <icon> <label>
sounds play <name> list
lock lock unlock isLocked status (nothing here gets past the password)
session toggle open close
switcher next prev toggle open close status
keybinds toggle open close edit editBind <id>
moji toggle open close emoji kaomoji gif center
keyboard toggle open close letters fnkeys center bigger smaller
idle status keepawake awake normal on off restart
network status list rescan
bluetooth send <address> <path>
kdeconnect status list rescan ring <id> ping <id> clipboard <id> files <id> send <id> <path>
nightlight toggle on off status
displays list settings shell <where> bar <where> dock <where>
updates status check whatsnew update beta show
whatsnew open close status
polkit status demo <action-id> fail grant close
debug toggle on off (draws input and blur regions)

Lumen and Lens run as their own processes with launchers of their own: ~/.config/quickshell/lucidlumen/lumen [folder] and ~/.config/quickshell/lucidlens/lens <file>.

Requirements

What the installer pulls in

Required: hyprland · quickshell · qt6-5compat · qt6-declarative · qt6-multimedia · qt6-webengine (Qt's PDF module, which Lumen's window needs)

Per feature, where a missing one breaks only its own feature:

Packages Back
matugen jq python-pywal awww git Colours, themes, wallpapers, importing schemes
networkmanager qrencode Wi-Fi and sharing a network as a QR code
bluez bluez-utils bluez-obex python-gobject Bluetooth, and files both ways
kdeconnect sshfs The Phone page and browsing a phone's files
libpulse wireplumber pipewire-audio sound-theme-freedesktop Sound, its devices and its tests
gvfs gvfs-smb gvfs-nfs gvfs-dnssd gvfs-wsdd ffmpegthumbnailer Drives, network shares and thumbnails
qt6-imageformats kimageformats libjpeg-turbo exiv2 Lens and pictures in every format
grim wf-recorder ffmpeg imagemagick Screenshots and recording
tesseract tesseract-data-eng python-pillow python-numpy python-fonttools Reading text off the screen, emoji included
wl-clipboard wtype cliphist Pasting and clipboard history
cava songrec The visualiser and song identification
brightnessctl upower hypridle hyprsunset Brightness, battery, idle and night light
polkit accountsservice Administrator prompts and the Users page
librsvg python-cairo Lucid's pointer and the cursor shadow switch
xdg-desktop-portal-hyprland xdg-desktop-portal-gtk Screen sharing and portals
smartmontools udisks2 inotify-tools Drive health, mounting, the camera toast
curl libnotify xdg-utils noto-fonts-emoji Weather, lyrics, notifications, links, emoji

The Hyprland config and the look (unless --no-hypr / --no-look): kitty · fish · playerctl · gnome-calculator · starship · ttf-jetbrains-mono-nerd · adw-gtk-theme · papirus-icon-theme

The dock's default pins (unless --no-apps): zen-browser-bin · vscodium-bin · spotify · vesktop · steam · proton-vpn-gtk-app. An equivalent you already have counts, and Steam brings the Vulkan drivers for the graphics cards you have.

Fonts: Google Sans Flex ships with Lucid under the Open Font License, so nothing needs installing; any installed font can be picked in Settings.

Optional setup

GIF search needs a free Giphy key from developers.giphy.com (Tenor works too), in ~/.config/quickshell/lucidmoji/config.json:

{ "giphyKey": "your-key-here", "tenorKey": "", "gifDir": "" }

Wallpapers live in ~/Pictures/wallpapers, a folder per theme; the folder can be changed in Settings → General.

Troubleshooting

Nothing appears when I run qs

Check qs log for QML errors, and make sure you are on Hyprland: Lucid needs its Wayland protocols and will not run on other compositors.

Another app's notifications show instead of Lucid's

org.freedesktop.Notifications belongs to whoever takes it first, and an installed daemon (swaync, dunst, mako) is started by the first notification. Check who holds it, mask the other one and log back in (the installer offers to):

busctl --user status org.freedesktop.Notifications | grep PID
systemctl --user mask swaync.service   # or dunst.service, mako.service
Everything is grey, or the colours look wrong

The palette cache is missing. Set a wallpaper through Settings → General, or copy a bundled palette: cp ~/.config/lucid/themes/nord/quickshell.json ~/.cache/quickshell/matugen.json

GTK apps are light, or their icons are wrong

GTK reads ~/.config/gtk-{3,4}.0/settings.ini while GNOME apps and portals read gsettings; the installer writes both. Check they agree:

gsettings get org.gnome.desktop.interface gtk-theme    # adw-gtk3-dark
gsettings get org.gnome.desktop.interface icon-theme   # FairyWren_Dark
The media panel's visualiser never moves

cava is running without ~/.config/cava/quickshell.conf. Re-run the installer, or copy support/cava/quickshell.conf there.

Animations feel choppy on an NVIDIA card

Qt refuses threaded OpenGL on the NVIDIA driver, which pins animations to about 60 fps. Lucid starts through ~/.config/lucid/launch-shell.sh, which moves such machines to Qt's Vulkan backend; launch-shell.sh --explain says what it decided, and LUCID_RHI_BACKEND=vulkan or opengl overrides it.

A keybind with an argument does nothing

Put -- before the target: qs ipc call -- settings show bar.

Icons look blurry

A fractional monitor scale puts icons on fractional pixels. Use a whole-number scale, and size the shell with Interface size in Settings → General instead.

Contributing

Issues and pull requests are welcome. For a bug, qs log and your Hyprland version help a lot. A good part of Lucid is the work of its contributors, above all Ciro Rivera, Lucid's co-developer:

Contributors

Star history

The mark

The Lucida mark

The logo is Lucida, the astronomical name for the brightest star in a constellation, from the same Latin root (lux) as Lucid: a broken orbit ring, a four-point star at the centre and one companion outside the gap. Its colour is cyan #00F0FF; in the shell the ring and the companion follow your accent.


License

MIT, see LICENSE. Google Sans Flex and the Poster clock's figures are under the Open Font License (assets/fonts). Built on Quickshell, with colours by matugen, following Material 3 Expressive.