Open Source Project #198: Omarchy — DHH's Opinionated Linux Desktop, Arch + Hyprland, 30k Stars

Introduction

"Beautiful, Modern & Opinionated Linux"

This is article #198 in the "One Open Source Project a Day" series. Today's project is Omarchy — a fully opinionated Linux desktop distribution built by DHH (David Heinemeier Hansson, creator of Ruby on Rails and co-founder of Basecamp), 30,822 Stars, MIT license.

Omarchy solves a specific problem: how do you make a Linux desktop that's beautiful, modern, and productive out of the box — not by asking you to stitch together thirty config files from scratch, but by saying "here's everything I use daily, take it."

What You'll Learn

• Omarchy's tech stack: the roles of Arch Linux, Hyprland, and Quickshell
• The keyboard-first navigation philosophy and core hotkey system
• 22 complete themes with cross-application sync
• How AI coding agents are integrated as first-class citizens
• Dev environment support (Rails/Node/Python/Go, etc.) and Dotfiles customization
• The four update channels (stable/RC/edge/dev)

Prerequisites

• Basic Linux command-line experience
• Some familiarity with tiling window managers is helpful
• No Arch installation experience needed — Omarchy provides a complete ISO

Project Background

Overview

Omarchy is an "omakase" (Japanese: お任せ, meaning "leave it to the chef") style Linux distribution. DHH has always favored strong opinions and high integration in his products — Rails is that way, HEY email is that way, and Omarchy is too: rather than giving you endless choices, it hands you one polished, complete solution.

The foundation is Arch Linux (rolling updates). Window management is Hyprland (a modern Wayland tiling WM). The desktop UI component layer is Quickshell (responsible for the top bar, menus, notifications, and screen saver). Three layers, clearly separated, working together as one system.

Author / Team

• Author: DHH (David Heinemeier Hansson), Basecamp / 37signals
• Primary language: Shell
• License: MIT
• Website: omarchy.org
• Manual: learn.omacom.io

Project Stats

• ⭐ GitHub Stars: 30,822+
• 🍴 Forks: 3,131+
• 📄 License: MIT
• 📅 Created: 2025-06-01

Quick Start

Installation

# 1. Download the ISO from the official site
# https://omarchy.org/
 
# 2. Flash to a USB drive
# Mac/Windows: balenaEtcher
# Linux: caligula
 
# 3. Enter BIOS, disable Secure Boot / TPM, boot from USB
 
# 4. Answer the configuration questions, select a drive, wait for installation
#    (under 1 minute on modern hardware, no more than 5 minutes otherwise)

Note: Full-disk encryption is on by default. A full-disk install wipes the selected drive — back up first. For dual boot alongside Windows, choose the free-space install and disable BitLocker in Windows beforehand.

Supports installing for another user (personal setup is deferred to first boot) and unattended batch installs for VMs and fleet machines.

Core Design: Keyboard-First

Omarchy's most defining stance: the keyboard is the protagonist; the mouse is a supporting cast member.

When the system first starts, you literally cannot do anything with the mouse alone. But you can:

The logic behind this design comes from one of DHH's core beliefs: "a beautiful system is a motivating system, and productivity is downstream from motivation." Once you're fluent on the keyboard, you won't want to go back to clicking a dock.

Hyprland Tiling Window Management

Omarchy uses Hyprland as its Wayland compositor. The core idea of tiling WMs: windows don't overlap; they arrange themselves automatically.

Open one window — it fills the screen. Open a second — they split side by side. Open a third — automatic three-way split. No dragging windows to "left half" by hand.

The default layout is dwindle: all open windows are always visible, shrinking as needed to fit. There's also a scrolling layout: windows line up side by side, extending beyond the screen edge — scroll horizontally to reach them. Great for code with multiple files open at once.

# Toggle layouts
Super + L  →  switch current workspace between dwindle/scrolling
 
# Quick multi-window demo:
Super + Return           → open terminal (full screen)
Super + Shift + Return   → open browser (two-way split)
Super + Ctrl + T         → open activity monitor (floating)
Super + Shift + F        → open file manager (four-way split)

Advanced features include: scratchpad (pop-up scratch terminal), sticky windows (float across workspaces), and fixed square-aspect single-window mode.

22 Themes: Cross-Application Sync

This is one of the areas Omarchy puts the most engineering effort. Each theme covers everything at once:

• Desktop wallpaper
• Terminal (Foot/Alacritty/Ghostty/Kitty)
• Neovim
• btop (activity monitor)
• Chromium
• The entire Omarchy shell (top bar, menu, notifications, OSD, lock screen)

Built-in themes include Tokyo Night, Catppuccin, Gruvbox, Nord, Rose Pine, Hackerman, Matte Black, Vantablack, and 14 more — 22 total.

# Switch via hotkey
Super + Ctrl + Shift + Space  →  open theme picker directly
 
# Switch via CLI
omarchy theme set tokyo-night
omarchy theme list

The heart of every theme is colors.toml — a set of color variables from which all application configs are generated. To make your own theme, copy an existing one into ~/.config/omarchy/themes/, tweak colors.toml, and the system pushes the colors to all applications automatically.

There's also a GUI tool called Aether for adjusting colors and selecting backgrounds visually — much more intuitive than editing TOML by hand. Launch it from the apps menu with Super + Alt + Space.

AI Coding Agents: First-Class Citizens

Omarchy's position on AI coding agents is clear: support multiple major agents out of the box, but don't force a choice.

All agents exist as lazy-load stubs: the command is present in ~/.local/bin/ (managed by mise), but nothing is downloaded until the first time you actually run one.

ori is the interesting outlier: ori claude, ori codex, ori opencode run those agents against whatever model you point OpenRouter at.

Set your default agent:

omarchy default agent claude
# or via Super + Space → Setup > Defaults > Agent

Once set, Super + Shift + Ctrl + A launches the default agent in a dedicated terminal window. Terminal shortcuts:

a   # run default agent inline in current terminal
c   # start OpenCode (auto-approve mode)
cx  # start Claude Code (auto-approve mode)
cy  # start Codex (auto-approve mode)

When you switch themes, Claude Code, Pi, and OpenCode's color schemes update automatically to match — a direct consequence of the theme system's cross-application coverage.

Development Tools

Omarchy has built-in support for installing a wide range of dev environments via the Omarchy menu (Super + Space → Install > Development):

All language runtimes are managed by Mise:

# Install and set as global default
mise use -g ruby
 
# Project-level version (reads .ruby-version / .node-version, etc.)
mise i

The default editor is Neovim, pre-configured with LazyVim — LSP, fuzzy finder, and AI code completion all work out of the box. To switch editors, install via the menu, then set it as the default under Setup > Defaults > Editor. Themes sync automatically.

The Top Bar: Interactive Information Density

The top bar is rendered by Quickshell, which is part of the entire shell process — it also draws the menu, notifications, OSD, and lock screen. This is why themes apply instantly and there's no panel startup delay.

Three-panel layout:

• Left: Omarchy logo (menu launcher) + workspace indicators
• Center: status indicators, clock, keyboard layout, weather, update badge
• Right: system tray, AI agent icon, bluetooth, network, audio, display, power

Nearly every widget responds to left / right / middle click and scroll:

Configuration and Customization

Omarchy's configuration philosophy: /usr/share/omarchy/ belongs to the system; ~/.config/ belongs to you. To override a default, create the corresponding file in ~/.config/ — user config takes precedence.

Key config files:

Most configs can be edited directly from the menu (Super + Space → Setup). After saving and quitting Neovim (:wq), any processes that need restarting automatically will.

Update Channels

# Update Omarchy and all system packages
omarchy update
# or Super + Space → Update > Omarchy

When a new version is available, a circular arrow icon appears to the right of the clock. Click it to start the update.

Resources

• 🌟 GitHub: basecamp/omarchy
• 🌐 Website: omarchy.org
• 📖 Full manual: learn.omacom.io
• 🎨 Extra themes: omarchy.org/themes

Summary

Omarchy is a very typical DHH product: strong opinions, high integration, limited choices — but one polished, complete solution in return.

Three things worth noting:

"Opinionated" is an engineering decision, not a limitation. The problem with traditional Linux desktops is usually not a lack of features — it's configuration fragmentation. Window manager, theme, editor, terminal, notifications all go their own way. Omarchy's value is integrating them into a coherent, consistently breathing system. When you switch themes, the terminal, Neovim, Chromium, and the top bar all update together — that requires a significant amount of config pipeline work behind the scenes.

Keyboard-first is a productivity choice, not a geek preference. The core experience for tiling WM users is: windows are always where you expect them, you don't use your eyes to hunt for windows, and your hands leave the keyboard far less often. It has the same learning curve as vim — there's a threshold, but the long-term return is higher.

The AI agent integration is worth studying as a design pattern. Rather than hardcoding one specific agent into the system, it uses lazy-load stubs to support all major agents, a unified omarchy default agent to manage the default choice, and the theme system to keep agent UIs in sync with system colors. This is an example of thoughtful toolchain design.

If you're interested in Linux desktops and don't want to configure everything from scratch, Omarchy is one of the most integrated and visually polished options available in open source right now.

Explore PrimeSkills — a curated marketplace of AI agents and skills, each validated against real enterprise workflows. No hype, just what actually works.

Visit my personal site for more insights and interesting products.