Omarchy: a decided desktop described by 51 chapter titles

A 194-word README that is only a table of contents

The repository root carries 194 words, and most of them are links. The opening line calls Omarchy a beautiful, fun and agentic Linux distribution by DHH, and the next line sends you to https://omarchy.org. Everything after that is 51 numbered manual chapters grouped as The Basics, The Applications, Configuration and The Rest, preceded by the note that the manual in `manual/` is the authoritative source. The project is released under the MIT License, and Shell is the primary language, which fits a repository with an `install/` directory, a `shell/` directory and a `bin/` directory at the top level.

What the root gives you is not a description of how the system is assembled. Hotkeys, the top bar, themes, dotfiles, updates, security and troubleshooting are all present as chapter titles, none of them as content. Someone arriving from a search result learns that Omarchy exists and that its author has organised 51 topics, and stops there.

Nothing at the root tells you how to install it

There is no fenced command block anywhere in the root README, no package list, no script invocation and no reference to an image file. Installation lives in the manual, under chapters titled Getting Started, Coming From Mac or Windows, Dual Boot Install and Unattended Installs, and the README's only instruction is to read more at https://omarchy.org.

That leaves a real gap for anyone deciding whether to try this. You cannot run a dry check, you cannot see which disk the installer wants to write, and nothing in the README says whether running the installer twice is safe or what removes it afterwards. An `install/` directory exists in the tree, and the README does not say how it is invoked or what it assumes about the target disk. First real use starts as reading rather than typing, so budget for `manual/02-getting-started.md` before pointing any of this at a machine that holds data, since the root flags no point of no return.

The Applications block is a fixed set, not a menu

Under The Applications, the manual names Terminal, Neovim, AI, Development Tools, Shell Tools, Shell Functions, TUIs, GUIs, Browsers, Commercial apps/services, Web Apps, Gaming, Filling out PDFs, Windows VM and Other Packages. Read as a list of chapter titles, that is still a description of what a machine ends up holding, and it is the shape of the project: a decided desktop rather than a toolkit.

A person who wants a different terminal, a different editor or no AI layer at all has no slot in that list. The supported escape hatches are named too, a Dotfiles chapter, a Shell plugins chapter, a Making your own theme chapter, alongside Branding, Backgrounds and Fonts. Those move your own files, and the root README describes no supported way to remove something the layer installed, so a machine assembled by someone else is awkward to unpick. The same reaches hardware. Monitors, Keyboard, Mouse, Trackpad, Networking and System sleep each have a chapter, which is how a shell-focused project becomes responsible for the whole desktop.

quattro is a branch name, not a version

Three version signals sit side by side and only one of them is a number. The default branch is `quattro`. A file named `version` sits at the root. The releases carry versions: v4.5.0-rc1 on 2026-10-20, v4.5.0-rc2 on 2026-10-27 and v4.5.0-rc3 on 2026-11-02, roughly one a week. The repository is not archived, and the last push was on 2026-11-02.

A `migrations/` directory next to a chapter titled Updates tells you the running system changes as releases land, and that is the part worth knowing. The root names no rollback command and no snapshot trigger, and it does not say what a half-applied migration leaves on disk. The `quattro` name carries no number, so you also cannot tell which branch content corresponds to v4.5.0-rc3 without comparing tags yourself. The manual has a System snapshots chapter, which is a page to read before the first update rather than after one goes wrong.

The root mixes shipped configuration with the author's working files

Look at what sits beside `install/` and `config/`: `agents/`, `plans/`, `AGENTS.md`, `CLAUDE.md`, `docs/`, `test/` and a `.luarc.json` file. Omarchy is billed as agentic and the repository carries agent instruction files at the same level as the installer, yet the README does not separate contributor material from what ends up on a user's desktop.

`default/` and `config/` also sit next to each other with no stated relationship, so nothing at the root tells you which one the update process writes into. Two documentation trees exist, `manual/` and `docs/`, and only `manual/` is called authoritative. The consequence is narrow but annoying: reading the tree does not answer the question a new user has, which is what will be on my machine. The `.luarc.json` file is a smaller version of the same problem, since the primary language is Shell and the README connects that file to no named component.

Fifty-one chapters arranged by topic, not by symptom

Depth is not what is missing. The manual covers Unified Clipboard and History, Text Extraction and Dictation, Screenshots and Recording, Toggles, idle and screensaver, System snapshots, Hardware authentication and Security, alongside the practical Networking, Monitors and System sleep chapters. That is a wide surface covered deliberately.

What the root offers is no way to search any of it. Nothing answers the three questions worth settling before installing: which GPUs are supported, how much disk and memory the system wants, and what a given error message means. A Troubleshooting chapter exists, but there is no symptom table at the root and no hardware list to check a machine against. So hardware compatibility cannot be confirmed from the root README before you install, only investigated afterwards, through the Troubleshooting and System snapshots chapters. The manual is the thorough part. The root will not save you the reading.

Dual boot, unattended and Mac are chapters, not documented options

Three ways in get their own chapters: Dual Boot Install, Unattended Installs and Mac support, with a Windows VM chapter for running the other operating system inside Omarchy. That is the honest answer to whether you can try this without committing to it.

The root leaves all of it undocumented in detail. Partitioning, encryption, disk layout, and what happens to a dual-boot machine across an update are answered by manual pages and by omarchy.org, not by the root README. A reader who already keeps a hand-built Arch Linux machine will want to know what Omarchy replaces, and the README never names the base it builds on, which leaves that particular question to the Getting Started chapter or to someone running the system. Worth resolving before you install, not after.

Editorial conclusion

Adopt Omarchy if you want one person's desktop rather than a toolkit, and if you are willing to learn its hotkeys, its top bar and its fixed application set. Do not adopt it if you need a published hardware support list, a documented rollback command or a server role, because the root README answers none of those. Before touching a disk, read manual/02-getting-started.md and manual/50-dual-boot-install.md on omarchy.org and check the Monitors, Keyboard, System sleep and Hardware authentication chapters against the machine in front of you, since nothing in the root README will tell you whether that machine qualifies.

Frequently asked questions

Official sources

1. License: MIT
2. omacom/omarchy on GitHub
3. Project website
4. README
5. Releases