# What Is the Purpose of the Omarchy Package in Omarchy? > Discover the Omarchy package, the core of the Omarchy Linux distribution. It unites scripts, QML components, and config files for an agentic desktop experience. - Repository: [Omacom/omarchy](https://github.com/omacom/omarchy) - Tags: deep-dive - Published: 2026-09-08 --- **The Omarchy package is a meta-package that serves as the core of the Omarchy Linux distribution, assembling scripts, QML components, and configuration files into a cohesive, agentic desktop environment.** The Omarchy package is not a single compiled binary but a curated collection of runtime components orchestrated to deliver a unified user experience. According to the omacom/omarchy repository, this package provides the CLI tools, graphical shell, and default configurations required to run the Omarchy environment. It acts as the central nervous system of the distribution, enabling both user-driven commands and automated system maintenance through an "agentic" architecture that monitors hardware state, network conditions, and update availability. ## Core Components of the Omarchy Package The package organizes its functionality into distinct directories, each serving a specific role in the desktop stack. ### CLI Command Layer in `bin/omarchy*` The `bin/` directory contains user-facing executable scripts that form the primary interface for system interaction. These entry points include `omarchy-toggle` for hardware features, `omarchy-theme-set` for appearance management, and `omarchy-update` for system maintenance. As implemented in `bin/omarchy-toggle`, these scripts translate high-level user commands into low-level system actions, providing consistent syntax across different hardware and software operations. ### Quickshell UI Layer in `shell/` The `shell/` directory houses the Quickshell configuration and QML UI components that render the top bar, panels, and desktop widgets. As documented in [`shell/README.md`](https://github.com/omacom/omarchy/blob/main/shell/README.md), this layer defines the visual layout, global hotkeys, and interactive elements users see. The QML-based architecture allows the Omarchy package to build a modern, composable interface separate from the underlying command logic while maintaining tight integration with the CLI tools. ### Default Configurations in `default/` The `default/` directory contains dotfiles, theme templates, and font configurations shipped with the distribution. During initial setup or when running `omarchy-refresh-config`, files from `default/fonts/omarchy/` and related paths are copied to the user's `$HOME/.config/` directory. This ensures first-time users receive a working, opinionated configuration while preserving the ability to customize through standard XDG paths. ### Application-Specific Configs in `config/` Package-specific configurations for bundled applications reside in `config/`, including settings for Xournal++ ([`config/xournalpp/settings.xml`](https://github.com/omacom/omarchy/blob/main/config/xournalpp/settings.xml)), MPV, and Imv. These presets ensure that applications integrate visually and functionally with the Omarchy desktop conventions without requiring manual user configuration. ### Documentation and Agents The `manual/` directory contains the authoritative user guide ([`manual/01-welcome-to-omarchy.md`](https://github.com/omacom/omarchy/blob/main/manual/01-welcome-to-omarchy.md)), serving as the primary reference for features from theme handling to hardware toggles. Complementing this, [`AGENTS.md`](https://github.com/omacom/omarchy/blob/main/AGENTS.md) catalogs the internal automation tooling that powers installation routines, update checks, and system maintenance tasks without manual intervention. ## How the Omarchy Package Delivers an Agentic Desktop Experience The package distinguishes itself through **agentic** characteristics—proactive automation combined with user override capabilities. The system continuously monitors states such as touchpad availability, network connectivity, and pending updates, then exposes these states through simple CLI commands. This architecture means the Omarchy package **orchestrates the entire desktop stack** from low-level hardware toggles (`bin/omarchy-toggle-touchpad`) to high-level theme management (`bin/omarchy-theme-set`). Users interact through a unified command set that remains consistent regardless of whether they are adjusting kernel-level settings or window manager preferences. ## Practical Examples of Omarchy CLI Commands The following examples demonstrate how the Omarchy package exposes system functionality through its `bin/` scripts. ### Hardware Toggles Control touchpad state directly from the terminal: ```bash omarchy-toggle-touchpad # flips the current state omarchy-toggle-touchpad on # forces it on omarchy-toggle-touchpad off # forces it off ``` Source: `bin/omarchy-toggle-touchpad` ### Theme Management Switch themes and refresh configurations: ```bash omarchy-theme-set white # apply the “white” theme omarchy-theme-list # list all installed themes omarchy-theme-refresh # copy default theme files to $HOME/.config ``` Source: `bin/omarchy-theme-set` ### System Maintenance Execute updates and apply configuration changes: ```bash omarchy-update # check for updates, download and install omarchy-refresh-config hypr/hyprland.lua # refresh Hyprland config after update ``` Source: `bin/omarchy-update` ### Terminal UI Utilities Launch interactive installers: ```bash omarchy-tui-install # open the TUI for installing optional packages ``` Source: `bin/omarchy-tui-install` ## Summary - The Omarchy package functions as a **meta-package** that aggregates scripts, UI definitions, and configurations rather than existing as a single compiled library. - The `bin/omarchy*` scripts provide a **unified CLI interface** for hardware toggles, theme management, and system updates. - The `shell/` directory contains **Quickshell QML components** that render the graphical desktop environment and handle user interactions. - Default configurations in `default/` are deployed to `$HOME/.config/` via `omarchy-refresh-config`, ensuring consistent initial setups. - The **agentic architecture** combines proactive monitoring with manual override capabilities, distinguishing Omarchy from static configuration-based distributions. ## Frequently Asked Questions ### Is the Omarchy package a single binary or a collection of scripts? The Omarchy package is a **collection of scripts and configuration files**, not a single binary. It functions as a meta-package that assembles runtime pieces from directories including `bin/`, `shell/`, and `default/` to create the complete desktop environment. This modular approach allows individual components to be updated or modified without recompiling core libraries. ### How does the Omarchy package handle user configurations? The package stores default configurations in the `default/` directory, which are copied to the user's `$HOME/.config/` directory on first run or when `omarchy-theme-refresh` is executed. This approach, managed by `omarchy-refresh-config`, separates upstream defaults from user modifications while ensuring new users receive working configurations for fonts, themes, and application settings. ### What is the role of Quickshell in the Omarchy package? Quickshell provides the **QML-based UI framework** used in the `shell/` directory to render the top bar, panels, and desktop widgets. According to [`shell/README.md`](https://github.com/omacom/omarchy/blob/main/shell/README.md), it defines the visual layout and hotkeys, creating the graphical interface layer that works alongside the CLI tools in `bin/`. This separation allows the graphical shell to be modified without affecting underlying system commands. ### Where can I find comprehensive documentation for Omarchy commands? The `manual/` directory contains the authoritative documentation, starting with [`manual/01-welcome-to-omarchy.md`](https://github.com/omacom/omarchy/blob/main/manual/01-welcome-to-omarchy.md), which describes every feature from theme handling to hardware toggles. Additionally, [`AGENTS.md`](https://github.com/omacom/omarchy/blob/main/AGENTS.md) documents the internal automation tooling, while individual scripts in `bin/` contain inline documentation for specific command usage and available flags.