What is Omarchy? A Deep Dive into Basecamp's Linux Distribution

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-<group> or omarchy-<group>-<cmd>. 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 palette and a shell.toml layout file, applied dynamically through the applyTheme IPC call without requiring session restarts.

The theming workflow documentation in docs/theming.md and the runtime shell.json format specification in 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 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.

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:

omarchy update

Manage themes through the theme group commands:

omarchy theme list           # Display available themes

omarchy theme set dracula    # Apply the Dracula color scheme

Interact with the running Quickshell instance via IPC:

omarchy shell --help                    # Show IPC command help

omarchy shell toggleBarTransparency     # Toggle bar transparency

Install and enable third-party plugins:

omarchy plugin add https://github.com/acme/omarchy-weather.git
omarchy plugin enable community.weather-extra

Refresh default configuration files with backup:

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 and 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 <repository-url>, then enable them with omarchy plugin enable <plugin-name>. 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}