equisdots
Menu

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/wallpapers by 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, xturing in ~/.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

Next steps

Run the installer from Installation, verify it with dots doctor, then log out and pick Hyprland (or Niri) at the login screen.

Edit this page on GitHub