Omarchy

Omarchy uses a two-package system to manage the transition from system-level configuration to user-level runtime environments:

1. omarchy package: Contains runtime binaries (/usr/bin/omarchy-*), installation/finalization scripts, migrations, themes, and the Quickshell desktop. It depends on omarchy-settings.
2. omarchy-settings package: Contains everything required before the main package installs. This includes /etc/skel/ defaults, system-wide /etc/ drop-ins, fonts, branding, bootloader (limine) and snapshot (snapper) configurations, and debug binaries (omarchy-debug, omarchy-debug-idle, omarchy-upload-log).

User Home Directory ($HOME) Population Layers

• Seed: omarchy-settings provides static defaults via /etc/skel/. These are copied to $HOME only during user creation (via useradd -m).
• Finalize: omarchy-finalize-user runs once per user to handle tasks requiring $HOME expansion, runtime detection, or environment variables like $OMARCHY_PATH.
• Resync: omarchy-reinstall-configs is a destructive command used by existing users to reset their configurations back to the shipped defaults.

Omarchy uses a single source of truth for environment variables, specifically OMARCHY_PATH and a dev-link-aware PATH, located at /usr/share/omarchy/default/bash/env-bootstrap.

Key Behaviors

• OMARCHY_PATH: Defaults to /usr/share/omarchy. If a developer uses omarchy-dev-link, this value is updated via /etc/omarchy.conf to point to the development checkout.
• PATH: Prepends $OMARCHY_PATH/bin to the system PATH only if OMARCHY_PATH is not the production /usr/share/omarchy path. This allows developers to run local versions of omarchy binaries.
• sudo compatibility: To ensure sudo omarchy-* works for unreleased binaries in a dev environment, omarchy-dev-link writes a drop-in to /etc/sudoers.d/omarchy-dev-path which updates the secure_path.

Sourcing Points

The bootstrap script is sourced by:

• /etc/profile.d/omarchy.sh (system login shells)
• /etc/skel/.bashrc (interactive shells)
• /usr/share/uwsm/env.d/10-omarchy (Hyprland via uwsm)
• /usr/share/omarchy/default/bash/envs (SSH / non-login bash)

The omarchy-shell is a long-running Quickshell instance that hosts the Omarchy desktop environment. All desktop components—including the bar, panels, overlays, menus, and services—are implemented as plugins.

Plugins are categorized by kinds, which determine how the shell manages them:

• bar-widget: A component that the active bar drops into a specific section (left, center, or right).
• bar: A full bar option that can replace the built-in omarchy.bar. Only one full bar is active at a time.
• panel: A floating window (e.g., an On-Screen Display).
• overlay: A fullscreen overlay (e.g., a background picker).
• menu: A summoned menu surface.
• service: A headless singleton with no UI, typically loaded at startup.

Panels, overlays, and menus are loaded when summoned, but plugins can set keepLoaded: true to remain in memory between summons. First-party services are loaded automatically at startup.

{
  "schemaVersion": 1,
  "id": "my.org.cool-clock",
  "name": "Cool clock",
  "version": "1.0.0",
  "author": "You",
  "description": "A clock that does cool things",
  "kinds": ["bar-widget"],
  "entryPoints": { "barWidget": "Widget.qml" }
}

Omarchy uses a single user configuration file to manage all customizations, including layout, per-entry settings, and the list of enabled plugins.

Important Behavior:

• If ~/.config/omarchy/shell.json does not exist, the shell uses shipped defaults.
• Once you customize anything, shell.json becomes the authoritative source. The shell does not deep-merge defaults back into your custom file; it uses your file as-is.

File Locations:

• ~/.config/omarchy/shell.json: Stores full layout, per-entry settings, and enabled plugin list.
• ~/.config/omarchy/plugins/<id>/: Directory for user-provided third-party plugin source files.

{
  "version": 1,
  "idle": {
    "screensaver": 150,
    "lock": 300
  },
  "bar": {
    "id": "omarchy.bar",
    "position": "top",
    "transparent": false,
    "centerAnchor": "omarchy.clock",
    "layout": {
      "left":   [ { "id": "omarchy.menu" }, { "id": "omarchy.workspaces" } ],
      "center": [ { "id": "omarchy.clock", "format": "HH:mm" } ],
      "right": [ { "id": "omarchy.audio" } ]
    }
  },
  "plugins": []
}