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

> Explore the Omarchy repository's key directories like bin shell default config and more. Understand the architecture of this Linux desktop configuration suite.

- Repository: [37signals/omarchy](https://github.com/basecamp/omarchy)
- Tags: architecture
- Published: 2026-08-27

---

**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.

```bash

# 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.

```bash

# 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`](https://github.com/basecamp/omarchy/blob/main/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.

```bash

# 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`](https://github.com/basecamp/omarchy/blob/main/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.

```bash

# 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`](https://github.com/basecamp/omarchy/blob/main/plans/server.md), [`plans/remote.md`](https://github.com/basecamp/omarchy/blob/main/plans/remote.md)) that outline feature roadmaps and architectural decisions for future development.

### [`AGENTS.md`](https://github.com/basecamp/omarchy/blob/main/AGENTS.md)

Located at the repository root, [`AGENTS.md`](https://github.com/basecamp/omarchy/blob/main/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`](https://github.com/basecamp/omarchy/blob/main/1787666837.sh) that automate configuration updates between versions.
- The **`docs/`**, **`plans/`**, and **[`AGENTS.md`](https://github.com/basecamp/omarchy/blob/main/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`](https://github.com/basecamp/omarchy/blob/main/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.