Docs
How Lucid works.
The README, laid out to read. The search at the top of the rail finds any part of it, the way Settings finds an option.
Nothing here matches that. Try other words, or ask.
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.shIn 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
- Checks your system and refuses to start anything it cannot finish, rather than leaving you half-installed.
- Installs dependencies through
paruoryaywhen there is one,pacmanotherwise. 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-appsskips them). - 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+Eand every app's open and save dialog, and Lens opens pictures. - Sets up Hyprland:
hyprland.luaand 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-hyprkeeps 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. - Sets up theming: the palettes, the wallpaper hook and the matugen templates. An existing
matugen/config.tomlis appended to, never replaced. - 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-darkwith the FairyWren icons, ingsettingsand bothsettings.ini.--no-lookskips it. - Builds the tilting cursor, a Hyprland plugin compiled against your own Hyprland and rebuilt by itself after an update (
--no-pluginsskips it). - 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.shHow 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.shIt 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 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

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

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

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 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 reloadSettings → 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.
Questions
What do I need to run Lucid?
Arch Linux and Hyprland 0.55 or newer. Lucid uses Hyprland's own APIs for workspaces and windows, so it does not run on Sway, niri, GNOME or KDE, and the installer relies on pacman and the AUR. The installer brings Hyprland itself when it is missing; the shell needs quickshell, its Qt modules and qt6-webengine, and everything else backs one feature each.
Will the installer overwrite my own config?
Not without asking, and never without a backup. A Hyprland config of your own is backed up and you are asked first; an existing matugen/config.toml is appended to; your old ~/.config/quickshell moves aside with a timestamp. --no-hypr, --no-look and --no-theming keep each part entirely yours.
What does Lucid connect to?
The update check asks api.github.com/repos/Sn3akyy1/lucid/releases/latest once a day, a plain curl that carries nothing about you; Settings → About turns it off. The weather comes from Open-Meteo, lyrics from lrclib.net only while something shows them, and GIF search talks to Giphy or Tenor only if you gave it a key.
Nothing appears when I run qs
Check qs log for QML errors, and make sure you are on Hyprland. If the log names an error you can't place, it belongs in a bug report: it is the most useful thing to include.
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
The glass shows my windows, not the wallpaper
That is on purpose: the glass frosts whatever is really behind it. To frost only the wallpaper, uncomment the xray rule in ~/.config/hypr/modules/layerrules.lua and reload Hyprland. Settings → Glass sets how far anything shows through at all.
How do I add my own theme, or switch to light mode?
Settings → Palettes has a gallery of a few hundred base16 and base24 schemes, takes the link of any scheme repo or file, and has an editor; nothing from a repo is ever run. Light or dark on the Theme page switches every palette, and the theme can follow each new wallpaper into light or dark by itself.
Can each display have its own wallpaper, or its own bar?
Yes. A line per output in ~/.config/lucid/wallpaper-outputs.conf gives it its own picture, and Settings → Displays puts a bar on every display or sends the bar and the dock to the display you pick: qs ipc call -- displays shell next.
Do I need Google Sans installed?
No. Lucid ships Google Sans Flex itself, under the Open Font License. Any installed font can be picked in Settings → General instead.
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.
Another app's notifications show instead of Lucid's
Only one program can own org.freedesktop.Notifications, and an installed daemon (swaync, dunst, mako) is started by the first notification. Check with busctl --user status org.freedesktop.Notifications | grep PID, then mask the other daemon (systemctl --user mask swaync.service) and log back in. The installer offers to.
A keybind with an argument does nothing
Put -- before the target: qs ipc call -- settings show bar. Without it qs reads the argument as its own.
Where is the full list of shortcuts?
Super + / lays every keybind over the screen, and Settings → Keybinds lists, searches, edits, adds and switches them off. They live in ~/.config/lucid/keybinds.json.
Which password unlocks the lock screen, and what is “Too many attempts”?
Your account password, checked through PAM; nothing in the lock IPC target gets past it. “Too many attempts” is faillock's real count: with Arch's defaults three failures in 15 minutes lock the account for 10, and the screen counts down. Cancelled administrator prompts count too.
How do I use the Lucid login screen?
Turn on Login screen in the installer window, or run ./install.sh --login-screen. It sets Current=lucid in /etc/sddm.conf (backed up first), and offers to make SDDM the login screen when another one is in use.