What Does the Omarchy-Settings Package Include? A Complete Component Guide

The omarchy-settings package bundles default configuration files, theme definitions, menu schemas, Quickshell UI definitions, migration scripts, and CLI utilities that initialize and manage the Omarchy desktop environment.

The omarchy-settings package is the foundational configuration layer for Omarchy, the declarative desktop environment developed by Basecamp. It resides in the basecamp/omarchy repository and provides the static assets and runtime definitions that the shell, compositor, and user tooling consume at startup.

Core Configuration Components

Default Dotfiles and Compositor Configs

At the heart of the package are the baseline configuration templates stored in config/. These files define the out-of-the-box behavior for Hyprland, tmux, zsh, and other tools. When a user runs omarchy-refresh-config, the system copies files such as config/hypr/hyprland.lua into ~/.config, establishing the default window manager rules, keybindings, and startup applications.

Theme Definitions and Color Palettes

Visual consistency is enforced through themes/*/colors.toml, which defines color palettes, accent values, and theme-specific styling parameters. These TOML files feed into the theming engine, allowing the omarchy-theme-switcher command to apply global color changes across the desktop environment.

User Interface Definitions

Menu Schemas

The desktop menu structure is declared in default/omarchy/omarchy-menu.jsonc. This JSONC file specifies icons, application groups, and command shortcuts that populate the Omarchy launcher. The schema supports comments and is parsed at runtime to generate the navigable menu hierarchy.

Quickshell UI Layout

The visual shell itself is defined by shell/shell.qml, a QML file that renders panels, pop-ups, and on-screen displays (OSDs). This file interfaces with the settings package to load theme data and configuration state, presenting the unified desktop interface.

Operational Scripts and Utilities

Migration Scripts

Versioned upgrade paths live in migrations/*.sh. These shell scripts automate configuration transitions between Omarchy releases, ensuring that user customizations remain compatible with new defaults. Each migration is timestamped and executed sequentially during the update process.

CLI Convenience Tools

The bin/ directory contains executable helpers like omarchy-update-status and omarchy-theme-switcher. These binaries read settings from the package and expose them as command-line interfaces, bridging the gap between static configuration files and runtime user interaction.

Validation and Documentation

Test Suite

Configuration integrity is verified by test/shell.d/*-test.sh. These shell-test scripts validate that settings parse correctly, that migrations succeed without error, and that theme applications produce expected color values.

Human-Readable Guides

Documentation such as docs/file-layout.md explains the organization of the settings package, providing developers and advanced users with reference material for extending or debugging the configuration.

Code Examples

Refresh the user’s configuration with the defaults from the omarchy-settings package:

omarchy-refresh-config hypr/hyprland.lua

Switch to the "dark" theme defined in the package:

omarchy-theme-switcher dark

List all menu entries that originate from the settings package:

jq '.menu[] | select(.source=="omarchy-settings")' \
  "$OMARCHY_PATH/default/omarchy/omarchy-menu.jsonc"

Execute a specific migration script manually (rarely required):

bash "$OMARCHY_PATH/migrations/1787133200.sh"

Summary

• The omarchy-settings package supplies the baseline ~/.config files for Hyprland, tmux, and zsh via the config/ directory.
• Theme definitions in themes/*/colors.toml drive global visual styling accessible through omarchy-theme-switcher.
• The menu schema in default/omarchy/omarchy-menu.jsonc and the Quickshell UI in shell/shell.qml define the user interface layer.
• Migration scripts in migrations/*.sh ensure seamless upgrades between Omarchy versions.
• CLI utilities in bin/omarchy-* provide command-line access to configuration state.
• Comprehensive testing in test/shell.d/ and documentation in docs/ guarantee reliability and clarity.

Frequently Asked Questions

What is the primary function of the omarchy-settings package?

The package serves as the single source of truth for Omarchy's default configuration state. It bundles static files, schemas, and scripts that initialize the desktop environment, manage theming, and handle versioned configuration migrations.

Where are the default Hyprland configurations stored?

Default compositor settings reside in config/hypr/hyprland.lua within the package. The omarchy-refresh-config command copies this file into the user's home directory to establish baseline window management rules.

How does Omarchy handle configuration updates?

Versioned shell scripts located in migrations/*.sh execute sequentially during updates. These scripts transform existing user configurations to match new package defaults without overwriting customizations.

Can I run the migration scripts manually?

Yes. While the update process runs these automatically, you can execute a specific migration directly using bash "$OMARCHY_PATH/migrations/[timestamp].sh" for troubleshooting or forced re-application.

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