# File layout How `omarchy/` is organized and where everything ends up on an installed system. ## Mental model Two Arch packages are built from this one repo (PKGBUILDs live in the separate `omarchy-pkgs` repository, under `pkgbuilds/`): - **`omarchy`** — runtime binaries (`bin/`, including `bin/omarchy-dev-*`), install/finalize scripts (`install/`), migrations, themes, and the Quickshell desktop (`shell/`). Depends on `omarchy-settings`. - **`omarchy-settings`** — everything that has to be on the target *before* the omarchy package installs (specifically before `useradd -m` and the limine bootloader install): all `/etc/skel/**`, `/etc/` drop-ins, package-owned system files under `/usr/share` and `/usr/lib`, fonts, plymouth theme, sddm theme, branding, plus the limine/snapper configs (mkinitcpio hooks, limine-entry-tool drop-ins, snapper template, the `default/limine/` and `default/snapper/` trees, and the boot/snapshot story end-to-end). Also ships the three debug binaries (`omarchy-debug`, `omarchy-debug-idle`, `omarchy-upload-log`) needed by the live ISO env. Two other packages live in `omarchy-pkgs` but stand alone: `omarchy-keyring` (GPG keys for pacman) and `omarchy-nvim` (the Neovim setup; independently seeds `/etc/skel`). Some trees ship in neither package and exist only in the repo: `manual/` (user manual chapters), `agents/skills/` (contributor task guides), `docs/`, `test/`, and `plans/`. Three layers populate `$HOME`: 1. **Seed** — `omarchy-settings` ships static defaults to `/etc/skel/`. Arch's `useradd -m` copies that tree into a new user's `$HOME` at user creation. This is the only mechanism that touches a brand-new user's home for these files. 2. **Finalize** — `omarchy-provision-user` (routed as `omarchy finalize user`) runs once per user and handles the things `/etc/skel` can't do because they need `$HOME` expansion, the live `$OMARCHY_PATH`, or runtime detection of system state. 3. **Resync** — `omarchy-reinstall-configs` is the explicit, destructive command for an existing user to clobber their configs back to shipped defaults. `/etc/skel` only fires at user creation. Existing users picking up new defaults must use the resync command. Deferred-provisioning installs (`omarchy-apply-system --defer-provisioning`) create no user at all: the ISO leaves `/var/lib/omarchy/provisioning/pending` behind, which arms `omarchy-provision-owner.service` (shipped from `install/provisioning/`, alongside the factory-reset finish unit and `setup-form.sh`). On first boot `bin/omarchy-provision-owner` creates the user on tty1 and runs the finalize step itself. Current generated theme state lives under `~/.local/state/omarchy/current/`. Keep `~/.config/omarchy/` for files a user may intentionally version in a dotfile manager, such as user themes, hooks, shell layout, plugins, and themed template overrides. ## Build-time map (repo → installed paths) ``` omarchy/ built into installed at ───────────────────────── ────────────── ──────────────────────────────────── bin/omarchy-* ──► omarchy /usr/bin/omarchy-* (and symlinks in /usr/share/omarchy/bin/) bin/omarchy-debug, bin/omarchy-debug-idle, bin/omarchy-upload-log ──► omarchy-settings /usr/bin/ (needed before omarchy is installed) default/libalpm/hooks/*.hook ──► omarchy /usr/share/libalpm/hooks/*.hook install/** ──► omarchy /usr/share/omarchy/install/ migrations/** ──► omarchy /usr/share/omarchy/migrations/ themes/** ──► omarchy /usr/share/omarchy/themes/ shell/** ──► omarchy /usr/share/omarchy/shell/ version ──► omarchy /usr/share/omarchy/version + /etc/skel/.local/state/omarchy/migrations/* config/** ──► omarchy-settings /etc/skel/.config/** (seeds new users) /usr/share/omarchy/config/** (resync source) etc/fastfetch/config.jsonc ──► omarchy-settings /etc/fastfetch/config.jsonc etc/xdg/kitty/kitty.conf ──► omarchy-settings /etc/xdg/kitty/kitty.conf applications/*.desktop ──► omarchy-settings /etc/skel/.local/share/applications/ /usr/share/omarchy/applications/ default/applications/battlenet.desktop ──► omarchy-settings /usr/share/omarchy/default/applications/ (installer-only launcher template) applications/icons/* ──► omarchy-settings /usr/share/icons/hicolor/{48,256,scalable}/apps/ etc/** ──► omarchy-settings /etc/** (drop-ins we own outright) ├─ mkinitcpio.conf.d/{omarchy_hooks,thunderbolt_module}.conf ├─ limine-entry-tool.d/{omarchy-defaults,omarchy-uki}.conf ├─ NetworkManager/, sudoers.d/, sysctl.d/, tmpfiles.d/, │ profile.d/omarchy.sh, … (a summary — `ls etc/` for the full ~17-entry tree) └─ security/faillock.conf, nsswitch.conf, cups/cups-browsed.conf, plymouth/plymouthd.conf /usr/share/omarchy/etc-overrides/ → /etc/* (post_install cp -f, see below) default/limine/limine.conf ──► omarchy-settings /usr/share/omarchy/default/limine/limine.conf default/limine/default.conf ──► omarchy-settings /usr/share/omarchy/default/limine/default.conf (template; ISO substitutes @@CMDLINE@@ → /etc/default/limine) default/snapper/root ──► omarchy-settings /etc/snapper/config-templates/omarchy (+ /usr/share/omarchy/default/snapper/root) default/** ──► omarchy-settings /usr/share/omarchy/default/ ├─ bash/env-bootstrap /usr/share/omarchy/default/bash/env-bootstrap │ (sourced by every shell/session entry point; see "Env bootstrap") ├─ bashrc /usr/share/omarchy/etc-overrides/dot.bashrc │ → /etc/skel/.bashrc (post_install cp -f) ├─ hypr/toggles/*.lua (flags, │ single-window-aspect-ratio, window-no-gaps) /etc/skel/.local/state/omarchy/toggles/hypr/ ├─ nautilus-python/extensions/*.py /etc/skel/.local/share/nautilus-python/extensions/ ├─ tensaku/state.toml /etc/skel/.local/state/tensaku/state.toml ├─ uwsm/env.d/10-omarchy /usr/share/uwsm/env.d/ ├─ environment.d/*.conf /usr/lib/environment.d/ ├─ fontconfig/conf.avail/50-omarchy.conf /usr/share/fontconfig/conf.avail/ │ + symlink /etc/fonts/conf.d/50-omarchy.conf ├─ xdg-terminal-exec/*.list /usr/share/xdg-terminal-exec/ ├─ applications/mimeapps.list /usr/share/applications/mimeapps.list ├─ systemd/user/*.service /usr/lib/systemd/user/ ├─ systemd/user/app.slice.d/10-oomd.conf /usr/lib/systemd/user/app.slice.d/ ├─ systemd/system-sleep/unmount-fuse /usr/lib/systemd/system-sleep/ ├─ systemd/zram-generator.conf.d/90-omarchy.conf /usr/lib/systemd/zram-generator.conf.d/ ├─ fonts/omarchy/omarchy.ttf /usr/share/fonts/omarchy/ ├─ sddm/omarchy/ /usr/share/sddm/themes/omarchy/ ├─ sddm/hyprland.lua /usr/share/sddm/hyprland.lua ├─ wayland-sessions/omarchy.desktop /usr/local/share/wayland-sessions/ └─ plymouth/ /usr/share/plymouth/themes/omarchy/ logo.{txt,svg}, icon.{txt,png} ──► omarchy-settings /usr/share/omarchy/ (resync source) /usr/share/pixmaps/omarchy.png /usr/share/icons/hicolor/256x256/apps/omarchy.png /etc/skel/.config/omarchy/branding/{about,screensaver}.txt ``` The hardware-conditional `force-igpu` and `keyboard-backlight` sources also live under `default/systemd/system-sleep/`, but their setup commands publish root-owned copies only on machines that need them; they are not installed by `omarchy-settings`. ### Why `etc-overrides/` exists Some files under `/etc/` (`.bashrc` in `/etc/skel`, `nsswitch.conf`, `security/faillock.conf`, `cups/cups-browsed.conf`, `plymouth/plymouthd.conf`) are owned by upstream Arch packages, so we can't install over them via pacman without a file conflict. Instead their sources (under `etc/` in the repo; `.bashrc` from `default/bashrc`) ship at `/usr/share/omarchy/etc-overrides/` and the `omarchy-settings` `post_install` / `post_upgrade` scriptlet `cp -f`'s them into place. Tradeoff: user edits to those files get clobbered on every `omarchy-settings` upgrade. This is documented in the PKGBUILD. ## Locate indexing `default/systemd/system/plocate-updatedb.service.d/10-omarchy.conf` ships through `omarchy-settings` to `/usr/lib/systemd/system/plocate-updatedb.service.d/10-omarchy.conf`. It replaces the existing service's `ExecStart` with `updatedb --prune-bind-mounts=no --add-prunepaths=/.snapshots`, keeping Btrfs subvolume mounts searchable and excluding Snapper snapshots. The upstream service retains its timer, resource limits, and sandbox; Omarchy's existing AC-power condition still applies. `/etc/updatedb.conf` remains owned by plocate and is never rewritten by Omarchy. The command-line options override bind-mount pruning and add to the administrator's existing path exclusions. Installer and AUR package refreshes pass the same options directly because installation may run without systemd and an explicitly requested refresh should work on battery. Arch's systemd package hook reloads units when the vendor drop-in is installed or upgraded. The settings package containing the drop-in must ship alongside the runtime package that removes the old configuration helper and migration. Pacman removes those retired files; no new state migration is needed. A running indexer finishes with its original options, and subsequent service starts use the drop-in. For an immediate local test after installing the packages, restart `plocate-updatedb.service` while connected to AC power. ## Env bootstrap (`default/bash/env-bootstrap`) Single source of truth for `OMARCHY_PATH` and dev-link-aware `PATH`. It: - Sources `/etc/omarchy.conf` (written by `omarchy-dev-link`, reset to the package path by `omarchy-dev-unlink`) if present; otherwise forces `OMARCHY_PATH=/usr/share/omarchy` so a stale inherited value can't survive an `omarchy-dev-unlink`. - Prepends `$OMARCHY_PATH/bin` to `PATH` **only when** `OMARCHY_PATH` is not `/usr/share/omarchy`. On a production install the binaries are already on `PATH` as `/usr/bin/omarchy-*` via the `omarchy` package. - Appends `~/.local/share/mise/shims` and `~/.local/bin` so login shells and the uwsm session find mise-managed tools — kept in sync with the PAM `PATH` line written by `install/config/ssh-command-path.sh`, which covers SSH commands that run no shell setup at all. Sourced by every entry point that needs the env set: ``` /etc/profile.d/omarchy.sh (system login shells) /etc/skel/.bashrc (interactive shells) /usr/share/uwsm/env.d/10-omarchy (Hyprland session via uwsm) /usr/share/omarchy/default/bash/envs (SSH / non-login bash) ``` Idempotent — safe to source more than once in the same shell. `PATH` covers everything the user runs, but not `sudo`, which resolves command names against `secure_path` from `/etc/sudoers`. So `omarchy-dev-link` also writes `/etc/sudoers.d/omarchy-dev-path`: ``` Defaults secure_path="/bin:/usr/local/sbin:/usr/local/bin:/usr/bin" ``` Without it, `sudo omarchy-*` fails for a command the package has not shipped yet and silently runs the packaged copy of one it has. The drop-in is validated with `visudo -c` before install and removed by `omarchy-dev-unlink`; unlike `/etc/omarchy.conf`, it takes effect without a reboot. ## Runtime finalization (`omarchy-provision-user`) Runs once per user. It does **not** copy `~/.config/**`, `~/.bashrc`, `flags.lua`, or the nautilus extensions — `/etc/skel` already seeded those. It only does the things `/etc/skel` can't: - Skill symlinks into `~/.agents/skills/`, `~/.claude/skills/`, `~/.codex/skills/`, `~/.pi/agent/skills/`, `~/.gemini/config/skills/` (Antigravity), `~/.hermes/skills/`, and each existing `~/.hermes/profiles/*/skills/` → `$OMARCHY_PATH/default/agents/skills/`, looping over every skill directory there (currently `omarchy` and `diagnose-crash`) so new skills need no edit. Symlinks (not copies) so `omarchy dev link` against a dev checkout repoints them correctly. Hermes profile dirs are only linked when they already exist — provision does not create Hermes profiles. - `xdg-user-dirs-update` (Templates/Public/Desktop folded back into `$HOME`) and `~/.config/gtk-3.0/bookmarks` (needs `$HOME` expansion). - Hyprland's package-owned default input reads `XKBLAYOUT` / `XKBVARIANT` from `/etc/vconsole.conf`; no per-user Hyprland config rewrite is needed. - `xdg-settings set default-web-browser chromium.desktop` and `xdg-mime default HEY.desktop x-scheme-handler/mailto` (XDG-aware paths). - `omarchy-refresh-applications` (composes generated `.desktop` launchers). - Sources `install/user/all.sh` — theme, chromium, git, xcompose, mise, keyring, per-user hardware quirks (asus mic/mixer, framework f13 audio, …). - On `--first-install`, marks every shipped user migration as already applied for the freshly-created user. Idempotency marker: `~/.local/state/omarchy/done/finalize-user`, managed by `omarchy-done`. The ISO calls it as `omarchy-provision-user --force --first-install` in the target chroot as the install user, after `omarchy-apply-system` has finished the root-side work. `omarchy-provision-owner` makes the same call (with `OMARCHY_SETUP_CONTEXT=provision-owner`) when it creates the user during deferred first-boot provisioning. ## Migrations (`omarchy-migrate`) See [`migrations.md`](../agents/skills/migrations.md) for the full migration model, authoring guidelines, and troubleshooting notes. Omarchy migrations live in `migrations/*.sh` and run per-user through `omarchy-migrate`. Completion state lives in `~/.local/state/omarchy/migrations/`, so every user gets a chance to run every migration. Migrations run as the user; privileged work should invoke the appropriate helper or privilege prompt. Migrations must be idempotent; machine-wide repairs should no-op when another user already applied them. Each graphical user has `omarchy-migrate-notify.service`, started once per login through `WantedBy=graphical-session.target` and ordered after that target so notification actions can safely launch through UWSM. The `omarchy-pkgs` PKGBUILD has shipped `omarchy-update-user-notify.service` as a symlink onto it, so users enabled under the old unit name keep working before they reach migration `1785095882`. It runs `omarchy-migrate-notify` as that user, which checks `omarchy-migrate --pending`. If this user has missing migration state, it shows a notification that opens a terminal for `omarchy-migrate`. The notifier never runs migrations in the background. Login is the only trigger. Nothing watches the packaged migration directory: a watcher cannot tell a bypassed `pacman -Syu` from the package transaction inside a normal `omarchy update`, so it notified about migrations that `omarchy-migrate` was already applying in the visible update terminal. `omarchy-migrate` waits for any active pacman transaction to finish, then runs pending migrations. It does not need `--force`; migrations happen when state files are missing. `omarchy update` runs `omarchy-migrate` after the package transaction in the already-visible update terminal, then runs `omarchy-hook post-update`. ## First-run (`omarchy-provision-first-run`) Runs once on first interactive login, after the user manager is live. It first runs `omarchy-provision-user || true` so finalize catches up if it never ran, then handles the steps that need a running graphical session and/or a working user systemd instance: - `omarchy-hook-install post-update` for the three shipped hooks (`install-voxtype.hook`, `setup-fingerprint.hook`, `setup-agent.hook`). - `install/user/first-run/enable-user-units.sh` — daemon-reload, then `systemctl --user enable --now` the shipped user units (`bt-agent`, `omarchy-sleep-lock`, `omarchy-recover-internal-monitor`, `omarchy-migrate-notify.service`, `omarchy-fcitx5.service`, `omarchy-crash-watch.service`) so they run in the first session too. Done here, not at finalize, because the user manager isn't reachable from the ISO chroot; `ConditionPath*` in the unit files keeps services inert when they don't apply. - `install/user/first-run/gnome-theme.sh`, `install/user/first-run/gtk-primary-paste.sh` — GNOME/GTK settings that need the dconf daemon. - `install/user/first-run/audio-tuning.sh` — apply speaker tuning. - `install/user/first-run/welcome.sh` — keybindings toast that greets the first login and opens the cheatsheet when clicked. The caller runs `omarchy-notification-wait` once before this and the Wi-Fi step, so both toasts land on a live notification server. - `install/user/first-run/wifi.sh` — Wi-Fi/update toasts (waits detached on `nm-online` so the update prompt only lands once there is a connection). The entire sequence has one idempotency marker: `~/.local/state/omarchy/done/first-run-user`, managed by `omarchy-done`. Completed users exit before any first-run step. On failure the marker is not written and the sequence retries next login. Completion markers live under `~/.local/state/omarchy/done/`. Use `omarchy-done check ` to check one and `omarchy-done mark ` to record it. Use `omarchy-done ensure ` as a conditional when the guarded work should run only once; it records completion before returning success. The Quattro upgrade completes graphical first-run for upgraded users and moves the legacy finalization marker from `~/.local/state/omarchy/` into `done/`. ## Root-side install orchestration `omarchy-apply-system` (root, in chroot) runs target-side setup at ISO finalization. It sources: - `install/config/all.sh` — theme links, lockout limits, lockscreen PAM, powerprofilesctl shebang fix, SSH command path and keepalive, docker setup, Snapper retention, locate index tuning, service enablement, firewall. - `install/hardware/all.sh` via `omarchy-apply-hardware` — vendor- and device-specific kernel modules, udev rules, microcode, wireless regdom, ASUS / Framework / Intel / Apple / Lenovo quirks. - `install/login/all.sh` — SDDM theme/session config. - `install/post-install/all.sh` — final pacman/udev/localdb passes. Logging goes to `/var/log/omarchy-install.log` via `install/helpers/logging.sh`. The package lists the ISO pacstraps live at `install/omarchy-base.packages` and `install/omarchy-other.packages`; the ISO builder also reads them when constructing its offline mirror. ## Explicit resync (`omarchy-reinstall-configs`) When an existing user wants to reset to shipped defaults: ``` ~/ ← cp -af /etc/skel/. ``` Replaying `/etc/skel` over `$HOME` is exactly what `useradd -m` does for a brand-new user, so this one copy resyncs `.bashrc`, `.config/**`, `.local/share/applications/`, the nautilus-python extensions, hypr toggles, branding files, and the shipped migration markers in a single pass. Then it runs `omarchy-refresh-limine`, `omarchy-refresh-plymouth`, and the nvim refresh. Destructive: existing user files copied from `/etc/skel` are clobbered without backup. Fastfetch is package-owned at `/etc/fastfetch/config.jsonc`; delete `~/.config/fastfetch/config.jsonc` to return to the packaged default. ## Quick reference: where does X live? | Goal | Touch | | --- | --- | | Default file at `~/.config/foo/` | `config/foo/` | | `/etc/` drop-in we own outright | `etc/` | | `/etc/` file owned by an upstream package | `etc/` (see `etc/security/faillock.conf`), then add to `etc-overrides` in `omarchy-settings` PKGBUILD + scriptlet | | Package-owned system file (e.g. systemd user service in `/usr/lib`) | `default/`, then add the `install -Dm644` line in `omarchy-settings` PKGBUILD | | Per-user file that's static but lives outside `~/.config` | `default/`, then add `install -Dm644 ... $pkgdir/etc/skel/...` in `omarchy-settings` PKGBUILD | | Runtime tweak that needs `$HOME` or live system state | extend `omarchy-provision-user`, or add a per-user leaf under `install/user/` and wire into `install/user/all.sh` | | One-time root-side setup step | `install/config/*.sh` or `install/hardware/*.sh`, wire into `install/config/all.sh` or `install/hardware/all.sh` | | One-time fix for existing installs | `migrations/.sh` | | Package-owned path something else may already write | Prefer a path nothing else writes, such as a vendor drop-in under `/usr/lib`. Otherwise the `--overwrite` entry in `bin/omarchy-update-system-pkgs` has to ship a release before the file | | User-facing `omarchy-*` command | `bin/omarchy--` — see `GROUP_DESCRIPTIONS` in `bin/omarchy` | | New stock theme | `themes//` (+ matching templates under `default/themed/` if they need theme colors) | | User-installed theme | `~/.config/omarchy/themes//` | | Generated current theme/background state | `~/.local/state/omarchy/current/` | ## Kitty defaults and user overrides Kitty loads `/etc/xdg/kitty/kitty.conf` before `~/.config/kitty/kitty.conf`. The `omarchy-settings` package owns the system file; the user template contains only the active theme include and commented examples for personal overrides. Keeping the theme include in the user file lets users remove it without changing the packaged defaults. Individual inherited keybindings can be unmapped with an empty `map ` directive, or all inherited bindings can be cleared with `clear_all_shortcuts yes`. The system default uses `allow_remote_control socket-only` so Omarchy can query the active terminal directory over its Unix socket while Kitty rejects remote-control requests arriving through terminal output. Changing this setting requires restarting Kitty. The migration refreshes the exact previous stock config with a backup; customized configs retain their settings and ordering, with only explicit unrestricted `yes`, `y`, or `true` remote-control settings commented out.