The Problem

Linux users who want a pre‑curated, visually cohesive desktop often spend hours stitching together themes, panel widgets, shortcuts, and hardware tweaks. The result is a fragmented experience that requires deep manual configuration each time a system is installed or a new machine is added.

What This Does

omarchy ships a full‑stack desktop environment built on top of Hyprland, with a battery of helper scripts (e.g. bin/omarchy-bar, bin/omarchy-capture-screenshot, bin/omarchy-hw-nvidia) that automate hardware detection, theme application, and common UI actions. The manual lives in manual/ and is the authoritative source for end‑user guidance; every UI element referenced there maps to a script in bin/.

The repository is organized around three functional zones:

  • Core binaries – all executable entry points under bin/ (≈1 500 scripts).
  • Configuration assets – config/ (JSON/TOML) and themes/ (theme definitions, icons).
  • Support material – test/ (unit‑style shell tests), agents/skills/ (metadata for the optional AI “agent” layer), and manual/ (Markdown docs).

Running bin/omarchy launches the distribution’s start‑up sequence, which reads the hardware profile (bin/omarchy-hw-*), applies the selected theme, and starts the panel (bin/omarchy-bar).

How It Is Wired

Entry point – bin/omarchy (a shell wrapper). It performs:

  1. Hardware detection – sources bin/omarchy-hw-*.sh (e.g., omarchy-hw-nvidia, omarchy-hw-intel). Each script probes /sys or lspci and writes a JSON blob to /run/omarchy/hw.json.
  2. Configuration loading – reads config/omarchy.json (global settings) and per‑theme files from themes/. The JSON parser is provided by the bundled Lua runtime (.luarc.json config) used by many scripts.
  3. Panel & services – invokes bin/omarchy-bar (draws the top bar) and spawns auxiliary daemons such as bin/omarchy-audio-output-switch, bin/omarchy-capture-screenrecording.

Control flow – most binaries follow a common pattern:

#!/usr/bin/env bash
source "$OMARCHY_ROOT/lib/common.sh"   # shared helpers
load_hw_profile                         # reads /run/omarchy/hw.json
case "$1" in
  start) start_service "$2" ;;
  stop)  stop_service  "$2" ;;
esac

lib/common.sh (implicit from the bin/ scripts) defines log, run, and notify functions used across the codebase. The most “blast‑radius” files are:

  • bin/omarchy – orchestrates the whole start‑up; a change here affects every downstream script.
  • bin/omarchy-hw-*.sh – determines what hardware‑specific scripts are later called; bugs propagate to power management, display configuration, and GPU selection.

The repository shows a hub‑and‑spoke topology: bin/omarchy → hardware detection → theme application → individual service scripts. No cyclic dependencies are visible; each script terminates after performing its task, keeping the call graph shallow (typically ≤3 hops).

External effects – scripts write to:

  • /run/omarchy/ (runtime state files).
  • $HOME/.config/omarchy/ (user‑level config).
  • System DBus (e.g., omarchy-audio-output-switch interacts with PipeWire).

No persistent database or network calls are present in the current code.

How To Use It

# Clone the repo
git clone https://github.com/moses-y/omarchy
cd omarchy

# Run the installer (installs themes, hardware profiles, and starts the session)
./bin/omarchy-install-and-launch

The installer reads install/ scripts (e.g., install/omarchy-install-browser) and populates $HOME/.local/bin with symlinks to the bin/ executables.

Configuration – edit config/omarchy.json for global toggles (e.g., auto_update, default_browser). Theme tweaks reside in themes/<name>/theme.json.

Running a specific helper – for instance, to capture a screenshot:

./bin/omarchy-capture-screenshot ~/Pictures/screen.png

All scripts are self‑documenting via --help flags; no additional environment variables are required beyond a standard Linux user environment.

Real‑World Use

A workstation that boots on mixed‑GPU hardware (Intel integrated + NVIDIA discrete) can be set up once by running the installer. After that, omarchy automatically selects the appropriate GPU (omarchy-hw-nvidia-gsp), applies the user’s theme, and provides a unified clipboard/history service (omarchy-clipboard-paste-text). Adding a new monitor triggers omarchy-hyprland-monitor-external-active, which reconfigures Hyprland without manual xrandr commands.

Code Health & Issues

  • Medium – Missing CI/CD pipeline – no .github/workflows/, Makefile, or other automation files.
  • Low – Sparse test coverage – 245 test files exist under test/, but they are shell‑script based and not integrated into a test runner.
  • Low – Mixed language consistency – majority of code is Bash; a few utilities use Lua or Python (5 Python files, 73 Lua files) without a unified build system.

No static analysis report is available, so the above observations are derived directly from the repository layout.

The Bottom Line

omarchy delivers a ready‑made, highly scripted desktop experience with thorough hardware detection and a rich set of UI helpers, suitable for power users who want a cohesive environment without hand‑picking each component. The codebase is large, Bash‑centric, and lacks CI automation, so onboarding new contributors will require care around the many entry‑point scripts. Ideal for teams that value a curated Linux stack and are comfortable maintaining a collection of shell utilities.