Overview
The equisdots desktop stack: what it is, which repositories it includes, and how its parts fit together.
equisdots is a complete Wayland desktop for Arch Linux built around Hyprland,
the Quickshell shell and the xwww wallpaper daemon. The same desktop also runs
on niri, the scrollable-tiling compositor: bar, panels, widgets, settings
editor, lock screen and the Nyx mascot are shared, and only the compositor layer
changes. Every piece is its own repository, and a single meta installer, dots,
clones, places and updates them together (dotsniri manages the niri stack).
A plugin standard adds self-contained features on top: 63 plugins ship with the
stack and the same hosts discover, toggle and update them without touching the
core.
What the stack provides
- A Lua-configured Hyprland session or an equivalent KDL-configured niri session: environment, keybinds, animations, window rules, workspaces and autostart.
- A Quickshell UI: bar, popups, panels, settings editor, desktop widgets, lock screen and the Nyx mascot island/notch with its control-center dock.
- A plugin system: a manifest standard, runtime SDK, discovery folders, live toggles, per-plugin settings pages, panels, bar modules and complete bars.
- A base16 palette system shared by the shell, window borders, terminals, editors and browsers.
- A wallpaper kernel with still images, videos, slideshow rotation and interactive JavaScript scenes.
- Engines and tools: timex (time and weather), xturing (terminal settings UI), theme-sync (cross-app theming) and a static SDDM login theme.
Repositories
| Repository | Provides | Installed to |
|---|---|---|
| hyprland | Compositor config (Lua), scripts, installer | ~/.config/hypr |
| niri | niri compositor config (KDL), session scripts, session/portal files | ~/.config/niri |
| niri-meta | Meta installer and updater for the niri stack | ~/.local/bin/dotsniri |
| niri-shell | Overlay making the shared shell compositor-neutral | merged into the shell |
| nyx-niri | Overlay making the Nyx island compositor-neutral | merged into the shell |
| niri-login | Wayland session entry so DMs list "Niri" | /usr/share/wayland-sessions |
| shell | Quickshell UI (bar, panels, editor, popups) | ~/.config/hypr/scripts/quickshell |
| nyx | Mascot island/notch plugin and control-center dock | .../quickshell/ui/plugins/nyx |
| palettes | Color palettes (JSON set and schema) | ~/.config/hypr/scripts/quickshell/dock/palettes |
| background | Curated wallpaper collection and scene catalog | released as background.zip |
| davinci | Wallpaper fetch/apply kernel | ~/.local/bin/davinci |
| theme-sync | Cross-app theme regeneration | ~/.local/bin/theme-sync |
| timex | Time and weather plugin: engine, calendar panel, bar island | .../quickshell/ui/plugins/timex |
| xturing | Terminal UI for the settings panel | ~/.local/bin/xturing |
| plugins | Plugin standard, 63-plugin hub and install registry | .../quickshell/ui/plugins/<id> |
| plugin-api | Manifest schema, host API version and compat evaluators | .../quickshell/plugin-api.json |
| plugin-sdk | Runtime SDK: PluginHost, Settings, surfaces, Lua mod | .../quickshell/core/sdk |
| transformpath | Plugin architecture, decisions and migration status | documentation only |
| login | Static minimal SDDM greeter | /usr/share/sddm/themes/x |
| dots | Meta installer and updater | ~/.local/bin/dots |
| web | Documentation site, previews and repository map | GitHub Pages |
Managed clones live under ~/.local/share/equisdots/<repo> (the niri stack uses
~/.local/share/equisdots-niri/<repo>). dots and dotsniri copy their
payload into place; they never delete a live config on their own.
How the pieces connect
settings.json (bar.palette, bar, widgets, timex, plugins, ...)
|
+--> shell (Colors.qml) ------> bar, widgets, lock screen
|
+--> colors.lua (hyprland) ---> window borders
|
+--> theme-sync --------------> kitty, starship, nvim, vscode,
| browsers, rofi, cava, qt, gtk, xfetch
|
+--> xwww scenes -------------> wallpaper follows the palette
davinci (kernel) --> xwww (stills/scenes) or mpvpaper (videos)
--> current_wallpaper.png for lock and SDDM
Where things live
- Settings:
~/.config/hypr/settings.json(single source of truth). - Shell state and caches:
~/.cache/quickshell,~/.local/state/quickshell. - Wallpapers:
~/.config/hypr/wallpapersby default. - Palette files:
~/.config/hypr/scripts/quickshell/dock/palettes. - Plugins: managed in
~/.config/hypr/plugins, user plugins in~/.config/hypr/plugins-user; UI under.../quickshell/ui/plugins. - Wrappers:
dots,dotsniri,davinci,theme-sync,timex,xturingin~/.local/bin.
Requirements
An Arch Linux derivative, Hyprland 0.55 or newer (the config is Lua) or
niri 26.04 or newer, git, rsync, jq, quickshell (qs), xwww-daemon,
mpvpaper and the Hack Nerd Font. dots doctor (and dotsniri doctor for the
niri stack) reports exactly what is missing. See
Installation for the full list.
Documentation map
- Installation - first setup and requirements.
- Updating and diagnosing -
dots updateanddots doctor. - Hyprland desktop - config modules, keybinds, monitors.
- niri compositor - the alternative compositor front end.
- Quickshell shell - bar, panels, widgets and IPC.
- Nyx mascot island - species, island/notch and the widget dock.
- Plugins and extensions - the standard, the 63-plugin hub and the CLI.
- Theming and palettes - base16 palettes and theme-sync.
- Wallpapers - davinci, xwww and the picker.
- Interactive scenes - authoring and running JS wallpapers.
- Tools: timex, xturing, login - the side tools.
- Architecture and repositories - contracts and data flow.
- Contributing and security - checks and reporting.
Next steps
Run the installer from Installation, verify it with
dots doctor, then log out and pick Hyprland (or Niri) at the login screen.