Where Are Omarchy Configuration Files Located? A Complete Directory Guide

Omarchy stores all user-editable configuration files in the config/ directory at the repository root, which during installation are copied to $HOME/.config/omarchy and application-specific locations such as ~/.config/hypr/ and ~/.config/kitty/.

Omarchy is an open-source desktop environment that maintains a flat, predictable hierarchy for its configuration assets. Understanding where Omarchy configuration files reside enables you to customize everything from the Hyprland compositor to terminal emulators and shell prompts using the omarchy-refresh-config command.

Repository Configuration Directory Structure

All default configuration templates live in the config/ directory at the repository root. This structure mirrors the runtime layout used after installation, making it straightforward to locate specific settings.

The Root config/ Folder

The config/ directory contains subdirectories for each integrated tool and service. During the installation process, files from this hierarchy are copied to the user's home configuration tree. The flat structure ensures that every Omarchy configuration file is discoverable without nested complexity.

User Configuration Locations

After installation, Omarchy populates two primary locations on your system:

• $HOME/.config/omarchy – Core Omarchy settings and hook scripts
• Application-specific directories – Tool configurations copied to standard XDG paths like ~/.config/hypr/, ~/.config/kitty/, and ~/.config/tmux/

When you run omarchy-refresh-config <path>, the system copies the corresponding file from $OMARCHY_PATH/config/<path> to your user configuration directory while preserving backups of existing files.

Core Configuration Directories Explained

config/omarchy (Core Settings)

The config/omarchy/ subdirectory contains the central Omarchy configuration, including shell.json which defines the application menu, launcher behavior, and global settings. The config/omarchy/hooks/ directory provides optional user-hooks that execute at specific lifecycle points, such as pre-refresh or post-update events. Example templates include post-update.d/show-update-notification.sample.

config/hypr (Window Compositor)

Hyprland configuration resides in config/hypr/, primarily within hyprland.lua. This file defines monitor layouts, keybindings, window rules, and compositor behavior. Refreshing this configuration directly updates your desktop environment's window management.

Terminal Emulator Configurations

Omarchy supports multiple terminal emulators through dedicated configuration directories:

• config/kitty/ – Contains kitty.conf for the Kitty terminal emulator
• config/foot/ – Contains foot.ini for the Foot terminal
• config/xdg-terminal-exec/ – Contains hyprland-xdg-terminals.list defining fallback terminal priorities

Tool-Specific Configurations

Additional tooling configurations include:

• config/tmux/ – tmux.conf session manager settings
• config/starship.toml – Starship prompt theme and formatting
• config/opencode/ – opencode.json for Opencode tooling integration
• config/obsidian/ – user-flags.conf for Obsidian markdown editor flags
• config/btop/ – btop.conf system monitor configuration

How to Refresh Configuration Changes

After editing any file in the repository's config/ directory, you must refresh it to apply changes to your active environment. The omarchy-refresh-config command handles this synchronization while backing up existing user configurations.

Refresh specific configuration files using these commands:

# Refresh the core Omarchy shell configuration

omarchy-refresh-config omarchy/shell.json

# Refresh the Hyprland compositor configuration

omarchy-refresh-config hypr/hyprland.lua

# Refresh the Kitty terminal configuration

omarchy-refresh-config kitty/kitty.conf

To list all available configuration templates and edit them before refreshing:

# List all available Omarchy config files

omarchy list-config

# Edit a specific config file in your editor and apply it

$EDITOR $OMARCHY_PATH/config/omarchy/shell.json
omarchy-refresh-config omarchy/shell.json

Key Configuration Files Reference

These critical files control major Omarchy subsystems:

• config/omarchy/shell.json – Defines the Omarchy menu, launcher, and global desktop settings
• config/omarchy/hooks/* – Executable scripts triggered before/after refreshes or updates
• config/hypr/hyprland.lua – Hyprland layout, keybindings, and monitor definitions
• config/starship.toml – Cross-shell prompt customization
• config/tmux/tmux.conf – Terminal session management and layout

Summary

• Omarchy configuration files reside in the config/ directory at the repository root
• User copies are stored in $HOME/.config/omarchy and tool-specific XDG directories
• Use omarchy-refresh-config <path> to apply changes from repository defaults to your live system
• The config/omarchy/ subdirectory contains core settings and hook scripts
• Window compositor settings are in config/hypr/hyprland.lua
• Terminal configurations are separated into config/kitty/, config/foot/, and related directories

Frequently Asked Questions

Where does Omarchy store configuration files after installation?

After installation, Omarchy copies configuration files from the repository's config/ directory to $HOME/.config/omarchy for core settings and to application-specific XDG directories (such as ~/.config/hypr/ and ~/.config/kitty/) for tool-specific configurations. The original repository files serve as templates that can be refreshed back into the user directories using the omarchy-refresh-config command.

How do I apply changes to Omarchy configuration files?

Run the omarchy-refresh-config <path> command where <path> is the relative path within the config/ directory. For example, omarchy-refresh-config omarchy/shell.json copies the updated shell configuration from the repository to your user directory while preserving a backup of your previous settings. This ensures that edits to repository templates safely propagate to your active desktop environment.

What is the difference between the repository config/ directory and ~/.config/omarchy?

The repository's config/ directory contains the default, version-controlled templates maintained by the Omarchy project. The ~/.config/omarchy/ directory contains your live, user-specific configurations that the system actually reads. The omarchy-refresh-config command bridges these two locations by copying from the repository defaults to your user directory, allowing you to customize settings while retaining the ability to reset to known good defaults.

Can I create custom hooks in Omarchy?

Yes, the config/omarchy/hooks/ directory supports user-defined scripts that execute at specific lifecycle points. Place executable scripts in subdirectories like post-update.d/ or pre-refresh.d/ within your user configuration. These hooks run automatically during the corresponding Omarchy operations, enabling custom notifications, backup routines, or environment adjustments whenever configurations are refreshed or the system is updated.

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