Opinionated Arch Linux desktop, configured as a product.
Opens with seven task guides and keeps most of its detail in other files.
├── ├── · imports AGENTS.md ├── agents │ └── skills │ ├── │ ├── │ ├── │ ├── │ ├── │ ├── │ └── ├── default │ └── agents │ └── skills │ └── omarchy │ └── └── docs ├── └──
The file, explained
The first section is a table of links, each naming a kind of work and the guide to read before starting it. Documentation is split into three trees by audience, and a section of helper commands replaces the equivalent raw shell tools.
Quoted passages are verbatim. Open one to see it in the source.
01 / Router files
Seven links open the file, covering command metadata, install scripts, the desktop shell, the icon font, acceptance tests, visual verification and migrations. Work that touches migrations loads the migrations guide; work that does not, does not pay for it.
02 / From this file
Task procedure, system reference and end-user documentation each have their own directory, with the audience stated for each. The user manual carries an explicit exclusion.
Source excerpt starting at line 20.- `manual/` - end-user documentation for using Omarchy, published; never codebase internals
03 / From this file
A list maps project commands onto the tools they replace: a package helper rather than pacman, a notification helper rather than notify-send. The wrappers handle cases the raw commands do not.
04 / Hard prohibitions
Commands from the default package set are stated to be runtime invariants, so presence checks around them are wrong. Presence helpers are reserved for genuinely optional dependencies and code that can run before the default set is installed, with a listed set of exceptions.
Source excerpt starting at line 88.Commands installed by Omarchy's default package set are runtime invariants. Invoke them directly; do not add defensive `omarchy-cmd-present` / `omarchy-cmd-missing` checks around them. Use command-presence helpers only for genuinely optional dependencies or code that can run before the default package set is installed.
05 / Pointing at the source of truth
The command prefix section gives common examples, then points at the array in the router as authoritative, with the stated reason that a second copy drifts.
Source excerpt starting at line 57.Do not maintain a second exhaustive prefix list here. Consult
06 / From this file
The config refresh helper interpolates its argument into two paths and checks only for existence, so a path containing a traversal resolves and writes outside the config directory. The file states the behavior rather than describing the helper as validating.
Put it to work
Omarchy's file tells an agent how the codebase works. It cannot tell it which bug three customers hit this week. Modem keeps that context current and attaches it to the work.
Try Modem