What Are the Key Directories in the Omarchy Repository? A Complete Architecture Guide

The Omarchy repository organizes its Linux desktop configuration suite into eight primary top-level directories: bin/ for executable commands, shell/ for the Quickshell UI, default/ and config/ for configuration templates, test/ for automated validation, and migrations/, docs/, and plans/ for maintenance and documentation.

Omarchy is a modular, self-contained configuration suite for Linux desktops developed by Basecamp. Understanding the key directories in the Omarchy repository is essential for contributors and power users who need to customize the desktop environment or extend its functionality. The codebase separates executable utilities, UI components, test harnesses, and configuration templates into a predictable structure that supports automated migrations and comprehensive testing.

The bin/ Directory: Executable Commands

The bin/ directory contains the omarchy-* commands that expose all user-facing actions. These scripts are thin wrappers that invoke the core runtime using the $OMARCHY_PATH environment variable. Key utilities include omarchy-update for system upgrades and omarchy-theme-set for appearance changes, all located at the repository root under bin/.

According to the basecamp/omarchy source code, the bin/omarchy-update script serves as the central upgrade command. It pulls new releases and synchronizes system packages. Other scripts like omarchy-refresh-config copy files from the default/ directory into the user’s ~/.config/ tree.

# Update Omarchy and its system packages

omarchy-update

# Refresh the user's hyprland config from defaults

omarchy-refresh-config hypr/hyprland.lua

The shell/ Directory: Quickshell UI Implementation

The shell/ directory houses the Quickshell UI—the graphical layer that drives the desktop panel, bar, and menus. This directory contains QML files, shared UI components, and plugin manifests. The entry point for the entire interface is shell/shell.qml, which instantiates the desktop environment and loads all UI plugins.

When you launch the Omarchy desktop, the wrapper script loads $OMARCHY_PATH/shell/shell.qml to render the interface. Individual components like the menu system reference configuration files such as default/omarchy-menu.jsonc to define their structure.

# Launch the Quickshell UI entrypoint

$OMARCHY_PATH/shell/shell.qml &

The default/ and config/ Directories: Configuration Templates

Default user settings are stored in default/ and config/. The default/ directory contains baseline configuration files for applications like Hyprland, Kitty, and Zsh. These files are copied into the user’s home directory via the omarchy-refresh-config helper. The config/ directory contains templates used during this refresh process, mirroring the structure under default/.

The file default/omarchy-menu.jsonc defines the default menu structure used by the Omarchy bar. When you run omarchy-refresh-config, the system populates ~/.config/ using these templates, ensuring consistent defaults across installations.

The test/ Directory: Automated Validation

The test/ directory contains the full automated test suite that guarantees correctness across releases. The subdirectory test/shell.d/ holds shell-integration tests, while test/cli validates command-line interfaces. The master test runner is the test/all script, which exercises the entire stack including CLI, shell, and migration tests.

A representative validation script is test/shell.d/menu-test.sh, which validates the menu plugin contract. Running this suite ensures that changes to bin/ or shell/ do not break existing functionality.

# Navigate to the test directory and run the full suite

cd "$OMARCHY_PATH/test"
./all          # runs CLI, shell, and migration tests

Maintenance and Documentation Directories

migrations/

This directory stores incremental migration scripts that evolve the Omarchy configuration across releases. Each script is timestamped, such as migrations/1787666837.sh, and handles automated changes like moving files or updating default values. When upgrading, the system executes these scripts in sequence to transition user data safely.

# Run the latest migration script manually

bash "$OMARCHY_PATH/migrations/$(ls -1 $OMARCHY_PATH/migrations | tail -n 1)"

docs/ and plans/

The docs/ directory contains human-readable reference documentation describing the architecture, configuration schema, and theming system. The plans/ directory holds high-level design documents (e.g., plans/server.md, plans/remote.md) that outline feature roadmaps and architectural decisions for future development.

AGENTS.md

Located at the repository root, AGENTS.md serves as a meta-document listing the agent-skill system—the contributor guides that document how to extend and interact with the Omarchy codebase.

Summary

• The bin/ directory provides executable commands like omarchy-update and omarchy-refresh-config that form the primary user interface.
• The shell/ directory implements the Quickshell-based desktop UI, with shell/shell.qml serving as the main entry point.
• The default/ and config/ directories supply baseline configurations for applications, copied to user homes during refresh operations.
• The test/ directory validates the entire system through automated suites run via ./test/all.
• The migrations/ directory contains timestamped scripts like 1787666837.sh that automate configuration updates between versions.
• The docs/, plans/, and AGENTS.md files maintain project documentation, roadmaps, and contributor guidelines.

Frequently Asked Questions

What is stored in the Omarchy bin/ directory?

The bin/ directory stores executable shell scripts that provide the Omarchy command-line interface. These include omarchy-update for system upgrades, omarchy-theme-set for appearance changes, and omarchy-toggle-* utilities for feature control. Each script acts as a wrapper that references $OMARCHY_PATH to locate other repository resources.

How does the shell/ directory implement the Omarchy UI?

The shell/ directory contains QML files and plugin manifests for the Quickshell-based user interface. The file shell/shell.qml serves as the main entry point that loads the desktop panel, bar, and menu components. This directory works in conjunction with default/omarchy-menu.jsonc to define the visual layout and interactive elements.

Where does Omarchy store its default configuration files?

Omarchy stores default configurations in the default/ and config/ directories. The default/ directory contains baseline settings for applications like Hyprland and Kitty, while config/ holds templates used by the omarchy-refresh-config command. These files are copied to ~/.config/ during installation or refresh operations.

How does Omarchy handle version upgrades and data migration?

Omarchy uses the migrations/ directory to manage upgrades. This directory contains timestamped shell scripts (e.g., 1787666837.sh) that automatically modify user configurations when updating between versions. The omarchy-update command typically executes these migrations to ensure settings remain compatible with new releases.

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