# What is Omarchy? A Deep Dive into Basecamp's Linux Distribution > Discover Omarchy, Basecamp's opinionated Linux distribution. Explore its Bash CLI router, QML Quickshell desktop, and Hyprland for a cohesive, extensible experience. - Repository: [37signals/omarchy](https://github.com/basecamp/omarchy) - Tags: deep-dive - Published: 2026-08-19 --- **Omarchy is a modern, opinionated Linux distribution created by Basecamp that combines a Bash-driven CLI router, a QML-based Quickshell desktop environment, and Hyprland window management into a cohesive, extensible desktop experience.** Developed by David Heinemeier Hansson and the team at Basecamp, Omarchy delivers a complete desktop Linux experience through a single entry-point command. The system integrates a sophisticated command-line interface with a declarative shell architecture, enabling users to manage themes, plugins, and window configurations through hundreds of sub-commands dispatched from the central `omarchy` binary. ## Core Architecture of Omarchy The Omarchy architecture consists of three tightly integrated layers that bridge user commands with the graphical environment. ### CLI Router and Command Dispatch At the heart of Omarchy lies a Bash-based command router located in `bin/omarchy`. This script parses user arguments and resolves them to specific binaries following the pattern `omarchy-` or `omarchy--`. The router extracts metadata from embedded comment lines (e.g., `# omarchy:group=theme`) within each binary to dynamically build routing tables, generate help documentation, and provide JSON output for command listings. When you execute an Omarchy command, the router either displays help text or execs the target binary directly, ensuring minimal overhead while maintaining a unified command namespace. ### Quickshell Desktop Environment Omarchy builds its visual layer on **Quickshell**, a long-running QML-based compositor that hosts the status bar, panels, overlays, and background services. Rather than traditional desktop environment components, Quickshell runs as a single process managed through the `omarchy-shell` IPC interface. The shell discovers plugins under `~/.config/omarchy/plugins/` and loads them on demand based on manifest declarations. It exposes a JSON-RPC-like API that the CLI uses to invoke actions such as `summon`, `toggle`, or `reloadConfig` at runtime. ### Configuration and Theming System Default configurations reside in the `config/` directory and deploy to `~/.config/` via the `omarchy-refresh-config` helper. Omarchy themes consist of a [`colors.toml`](https://github.com/basecamp/omarchy/blob/main/colors.toml) palette and a [`shell.toml`](https://github.com/basecamp/omarchy/blob/main/shell.toml) layout file, applied dynamically through the `applyTheme` IPC call without requiring session restarts. The theming workflow documentation in [`docs/theming.md`](https://github.com/basecamp/omarchy/blob/main/docs/theming.md) and the runtime [`shell.json`](https://github.com/basecamp/omarchy/blob/main/shell.json) format specification in [`docs/omarchy-shell.md`](https://github.com/basecamp/omarchy/blob/main/docs/omarchy-shell.md) define how visual changes propagate through the system. ## Key Features and Components ### Plugin System and Manifest Omarchy supports third-party extensions through a declarative plugin manifest system. Each plugin includes a JSON manifest declaring its `kinds` (such as `bar-widget` or `overlay`) and entry points. Plugins install via git clone into `~/.config/omarchy/plugins/` and support hot-reloading when source files change, enabling rapid development cycles without desktop restarts. ### Inter-Process Communication (IPC) The `omarchy-shell` command provides the bridge between CLI tools and the running Quickshell instance. This IPC layer handles runtime state changes like toggling bar transparency or summoning overlays. The shell API is documented in [`docs/omarchy-shell.md`](https://github.com/basecamp/omarchy/blob/main/docs/omarchy-shell.md) and supports both direct commands and configuration reloads. ### Runtime Environment Variables All Omarchy components rely on the `OMARCHY_PATH` environment variable, which points to the repository root and is set by the session manager at login. This variable enables scripts and QML code to locate resources consistently across the system, as referenced in [`AGENTS.md`](https://github.com/basecamp/omarchy/blob/main/AGENTS.md). ## Working with Omarchy Commands Omarchy exposes hundreds of sub-commands through its unified CLI. Here are practical examples for common operations: Update the system and Omarchy packages: ```bash omarchy update ``` Manage themes through the theme group commands: ```bash omarchy theme list # Display available themes omarchy theme set dracula # Apply the Dracula color scheme ``` Interact with the running Quickshell instance via IPC: ```bash omarchy shell --help # Show IPC command help omarchy shell toggleBarTransparency # Toggle bar transparency ``` Install and enable third-party plugins: ```bash omarchy plugin add https://github.com/acme/omarchy-weather.git omarchy plugin enable community.weather-extra ``` Refresh default configuration files with backup: ```bash omarchy-refresh-config hypr/hyprland.lua ``` This command copies `$OMARCHY_PATH/config/hypr/hyprland.lua` to `~/.config/hypr/hyprland.lua` while preserving existing settings. ## Summary - **Omarchy** is Basecamp's opinionated Linux distribution combining Hyprland window management with a custom QML shell. - The **CLI router** in `bin/omarchy` dispatches commands to specialized binaries using embedded metadata for dynamic routing. - **Quickshell** provides the desktop environment through a single QML process controlled via the `omarchy-shell` IPC interface. - **Themes** use [`colors.toml`](https://github.com/basecamp/omarchy/blob/main/colors.toml) and [`shell.toml`](https://github.com/basecamp/omarchy/blob/main/shell.toml) files applied at runtime through the `applyTheme` command. - **Plugins** declare capabilities via JSON manifests in `~/.config/omarchy/plugins/` and support hot-reloading. - The **`OMARCHY_PATH`** environment variable anchors all resource lookups to the repository root. ## Frequently Asked Questions ### What window manager does Omarchy use? Omarchy uses **Hyprland** as its window manager while building the desktop shell experience on top of **Quickshell**. This combination provides Wayland-based compositing with dynamic tiling capabilities, managed through the `omarchy` CLI and configured via files in `~/.config/hypr/`. ### How do I install plugins in Omarchy? Install plugins by cloning git repositories into the plugins directory using `omarchy plugin add `, then enable them with `omarchy plugin enable `. Plugins must include a JSON manifest declaring their kinds and entry points, and they hot-reload automatically when you modify their source files. ### Where are Omarchy configuration files stored? Default configurations live in the `config/` directory of the Omarchy repository, while active user configurations reside in `~/.config/omarchy/`. The `omarchy-refresh-config` helper copies default files from `$OMARCHY_PATH/config/` to your home directory with automatic backups, allowing you to restore or update settings safely. ### Is Omarchy based on a specific Linux distribution? Omarchy is a complete Linux distribution created by Basecamp rather than a desktop environment layered on top of another distro. It manages system packages through its own update mechanism (`omarchy update`) and maintains a cohesive environment where the CLI, shell, and window manager are designed to work together as a unified stack.