GitHub

The whole desktop, laid out on one grid.

Groma is a desktop shell for Hyprland, written in QML on Quickshell. One process draws the bar, the launcher, notifications, the lock screen, files, a software store and settings, and an installer puts all of it on a bare Arch machine.

Install on Arch Read the source

The bar

Everything hangs from the bar.

Each card grows out of the icon that opened it, like a tab, in one dense slate glass. One process holds them all, so the bar's speaker and the Sound card read the same PipeWire object and can never disagree.

The clock's card: three notifications on the left, October's month on the right with today lit, and a Do Not Disturb switch

Calendar and notifications

The clock opens a month and every notification not yet dealt with. A toast going away does not end a notification: it waits here. Do Not Disturb keeps all but critical ones quiet.

The System card: processor, graphics, memory and disk, each with a figure and a meter

System

Processor, graphics, memory and disk. A row opens btop or nvtop for more.

The Battery card: charge on a green slider, the power adapter, battery health, and three power modes

Battery

Charge, the adapter, the battery's health, and a power mode kept for plugged in and for battery.

The Sound card: a volume slider with a glass knob, and the outputs listed below

Sound

Volume on a glass slider, and every output, with a dot on the one in use.

The Bluetooth card: the radio switch and a pair of earbuds under My Devices

Bluetooth

The radio, your devices and their batteries, earbuds down to each bud.

A notification toast under the bar: Groma Store says twelve packages can be updated

Toasts

A toast waits while you point at it, opens its app on a click and goes on a right-click. Gone from the corner, it stays in the centre under the clock until you deal with it.

The Power card: lock, suspend, log out, restart and power off, with the uptime

Power

Lock, suspend, log out, restart, power off. Nothing more.

Workspaces

Name it for what it holds.

A workspace can be "Design" or "Music" rather than 6, with a colour, as with a browser's tab groups. The names are Groma's: Hyprland still sees numbers.

  • Right-click a workspace, or press Super + N on the one you are in.
  • The colour shows as you pick it, on the pill behind the card; the name waits for Enter.
  • A named workspace keeps its place in the bar when it is empty, drawn as an outline until something opens there.
  • Point at one to see its windows, live, without going there.

The launcher

Type, pick, Enter.

One field for everything you reach for, opened with Super + R.

  • Applications, the ones you opened last waiting at the top.
  • Sums and units: type 2^16 / 3 and Enter copies the answer.
  • Files anywhere in your home, found as you type.
  • Commands, run quietly or in a terminal, and clipboard history after a colon.

Groma's own apps

Built in, in the same glass.

A file manager, a store for the official repositories and the AUR, a settings window and your snapshots, drawn by the same process and to the same rules as the bar.

Files in grid view: folders, a spreadsheet, a picture's thumbnail, PDFs and an archive, each with its own icon
FilesList and grid, copy and move with progress, drag in and out, Trash, drives, and Open with.
Groma Store's Featured page: Firefox, Signal, Visual Studio Code, Obsidian and others, each marked official or AUR
Groma StoreInstall, remove and update from the official repositories and the AUR, with the source marked on every row.
Settings, Keyboard and Touchpad: layouts, the Caps Lock key, key repeat and touchpad switches
SettingsKeyboard and touchpad, display scale and rate, idle and sleep, the clock, the wallpaper. Changes apply as you make them.
Snapshots: a list of pacman transactions, each undoable, with Snapshot now and Undo buttons
SnapshotsEvery pacman transaction is wrapped in a snapshot. Undo one from here, or boot an earlier system from Limine's menu.

Locking

Shut means shut.

The lock screen speaks ext-session-lock: if the shell ever dies while locked, the session stays closed rather than showing the desktop.

  • Locks before every sleep, and on idle: dim, lock, screen off, suspend.
  • A finger or the password, side by side, on any reader libfprint drives.
  • Its own polkit agent, so administrator prompts take a finger too.
The lock screen: a large clock and date over the wallpaper, a password field, and a prompt to touch the fingerprint reader

Screenshots

Print freezes the moment.

Every screen is frozen first, and the chooser lies over the frozen frame, so a menu closing does not change what you keep.

  • An area, a window or a screen, by mouse or keyboard.
  • Record with Alt + Print, with the computer's sound and the microphone if you ask.
  • Annotate in Satty, or drag the picture straight into another window.
The capture overlay: an area selected over the frozen desktop with its size shown, and Area, Window, Screen, Picture and Video choices below

Install

Two lines on a bare Arch install.

The installer detects the processor and graphics, sets up snapshots where the disk allows, starts Hyprland when you log in on the first console, and is safe to run again.

From a fresh Arch install

Logged in as a user in the wheel group:

Terminal
$ git clone https://github.com/sfrancavilla/groma.git ~/groma
$ ~/groma/install.sh

Then log out and back in on the first console. The desktop starts.

Booting a snapshot from Limine's menu is a separate step, since it changes the boot loader: system/setup-limine-snapshots.sh stops before rebooting so you can read what it did first.

  • NeedsArch Linux, made with the installation guide or archinstall. Everything else, Hyprland and Quickshell included, comes from the installer.
  • SnapshotsBtrfs with / on @, as archinstall lays it out. Without Btrfs, all but snapshots installs.
  • TestedHyprland 0.56 and Quickshell 0.3.2: daily on a Framework Laptop 13 Pro with AMD graphics, and from scratch in a virtual machine.
  • AlphaOne real machine so far. NVIDIA and disk encryption on a fresh install are untried. Issues welcome.

The book

How Groma was built, from an empty disk.

One real build on a Framework Laptop 13 Pro, written up as it happened: an encrypted Btrfs base system, then Hyprland, then this shell, one surface at a time. Every command was run on that machine and every output is what it printed, failures included.

Written by Claude and reviewed by the author, one section at a time. Chapter 1, Building the Base System, has begun.

Start reading Contents

The name

A groma is the Roman surveyor's instrument: a cross on a staff with a plumb line hanging from each arm. Sight along it and you get the cardo and the decumanus, the two axes a camp or a new city was laid out from, and every camp in the empire was laid out the same way with one.

That is the aim here: a desktop you can reproduce exactly, on any machine, from one repository.