How Omarchy System Defaults Are Managed for New Users

Omarchy provisions system defaults for new users by copying version-controlled configuration files from $OMARCHY_PATH/config to ~/.config via the omarchy-refresh-config utility, automatically preserving existing customizations through backups before overwriting.

The omacom/omarchy repository implements a deterministic provisioning pipeline that eliminates manual configuration for first-time users. This approach delivers a complete, tested desktop environment—including Hyprland window manager settings, tmux configurations, and shell integration—while maintaining safety mechanisms that protect user modifications.

The Configuration Provisioning Pipeline

The default management system relies on a reference-and-refresh architecture that separates pristine defaults from active user configurations.

Reference Defaults Storage

All shipped defaults reside in $OMARCHY_PATH/config, organized by subsystem to facilitate modular provisioning:

• config/hypr/ – Contains Hyprland window manager configurations including hyprland.lua and bindings.lua
• config/tmux/tmux.conf – Provides the default terminal multiplexer setup
• config/omarchy/shell.json – Defines core shell behavior and Omarchy-specific settings
• config/omarchy/hooks/ – Stores optional post-refresh automation scripts

The Core Refresh Mechanism

The bin/omarchy-refresh-config script functions as the low-level provisioning engine. When invoked with a relative path, it executes a strict three-phase operation:

1. Validation – Verifies the requested file exists in $OMARCHY_PATH/config, aborting immediately if the source is missing to prevent typos or missing dependencies
2. Backup – Detects existing files at the destination ($HOME/.config/<relative-path>) and creates preservation copies in ~/.config/.backup/ before any modifications
3. Provisioning – Copies the default from the repository to the user's active configuration directory

# Refresh a specific Hyprland keybinding configuration

omarchy-refresh-config hypr/bindings.lua

# Refresh the Omarchy shell settings file

omarchy-refresh-config omarchy/shell.json

Wrapper Commands for Bulk Provisioning

While omarchy-refresh-config handles individual files, convenience wrappers in bin/ orchestrate complete subsystem refreshes for common use cases:

• omarchy-refresh-hyprland – Provisions the entire Hyprland stack from config/hypr/, synchronizing all window manager defaults simultaneously
• omarchy-refresh-tmux – Refreshes the terminal multiplexer configuration specifically via config/tmux/tmux.conf
• omarchy-refresh-shell – Updates the Omarchy shell JSON configuration and related integration components

# Refresh the complete Hyprland configuration suite

omarchy-refresh-hyprland

# Update tmux defaults independently

omarchy-refresh-tmux

# Synchronize shell integration settings

omarchy-refresh-shell

Safety Mechanisms and Backup Strategy

The provisioning system implements defensive safeguards to prevent configuration loss. Before overwriting any existing user file, bin/omarchy-refresh-config automatically archives the current version to ~/.config/.backup/, enabling rollback if the new defaults conflict with established workflows.

The command also enforces strict source validation. Attempting to refresh a non-existent default path causes immediate termination with an error status, protecting against the creation of empty or corrupted configuration files due to path typos.

Post-Refresh Hooks and Customization

Following successful file provisioning, the system executes optional hook scripts located in config/omarchy/hooks/. These hooks enable automation such as displaying desktop notifications when themes change, triggering battery-low warnings, or restarting dependent services. Users extend default behavior by adding executable scripts to this directory, which run automatically after any refresh operation completes.

Testing and Reliability

The test/shell.d/refresh-config-test.sh test suite validates the entire provisioning pipeline across release cycles. These automated checks confirm that:

• Files copy correctly from repository defaults to user directories
• Backup creation triggers properly when destination files pre-exist
• Missing source files cause graceful, noisy failures rather than silent corruption

This coverage ensures that new users receive reliable, predictable configuration states regardless of installation environment.

Summary

• Omarchy stores pristine defaults in $OMARCHY_PATH/config, with discrete subdirectories for Hyprland (config/hypr/), tmux (config/tmux/), and shell settings (config/omarchy/)
• The bin/omarchy-refresh-config script copies individual files while validating sources exist and backing up existing user configs to ~/.config/.backup/
• Wrapper commands (omarchy-refresh-hyprland, omarchy-refresh-tmux, omarchy-refresh-shell) simplify bulk provisioning of related configuration sets
• Post-refresh hooks in config/omarchy/hooks/ enable custom automation triggered by default updates
• Automated tests in test/shell.d/refresh-config-test.sh ensure the provisioning system remains reliable across different system environments

Frequently Asked Questions

What happens to my existing configuration when I run omarchy-refresh-config?

The command automatically detects existing files in your ~/.config/ directory and archives them to ~/.config/.backup/ before applying new defaults. Your previous settings remain recoverable, making the refresh process safe to execute repeatedly without risking permanent loss of customizations.

Where are the default configuration files stored in the Omarchy repository?

All default configurations live in the config/ directory at the repository root, referenced via the $OMARCHY_PATH/config environment variable. This includes config/hypr/ for window manager settings, config/tmux/tmux.conf for terminal multiplexer defaults, and config/omarchy/shell.json for shell integration parameters.

Can I customize what happens after a config refresh?

Yes. Place executable scripts in config/omarchy/hooks/ to trigger custom actions following any refresh operation. These hooks can display system notifications, restart services, or perform other post-provisioning tasks automatically when the system updates its defaults.

How do I refresh only the Hyprland configuration without affecting other settings?

Run omarchy-refresh-hyprland to update exclusively the Hyprland-related defaults, or use omarchy-refresh-config hypr/<filename> to refresh specific individual files such as hypr/bindings.lua. This targeted approach leaves your tmux, shell, and other subsystem configurations completely untouched.

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