How Kitty Defaults Are Loaded and User Overrides Safely Preserved in Omarchy

Omarchy loads system-wide Kitty defaults from /etc/xdg/kitty/kitty.conf first, then processes user overrides from ~/.config/kitty/kitty.conf, using SHA-256 hash checks and automated backups to ensure user customizations survive package updates.

The Omarchy distribution ships with a carefully tuned Kitty terminal emulator configuration that balances immediate usability with deep customization. Understanding how the system handles Kitty defaults loaded alongside user overrides safely preserved is essential for administrators who want to customize their terminal without fear of losing changes during system updates.

System-Wide Defaults and User Configuration Loading Order

Omarchy leverages Kitty's native XDG Base Directory specification support to establish a hierarchical configuration system. The terminal reads settings from two distinct locations, with later files overriding earlier ones.

• /etc/xdg/kitty/kitty.conf — The system-wide defaults owned by the omarchy-settings package. This file contains the base configuration shipped with the distribution.

• ~/.config/kitty/kitty.conf — The user-specific overrides where personal customizations reside.

Because Kitty processes the user configuration file after the system file, any settings defined in ~/.config/kitty/kitty.conf naturally override the Kitty defaults loaded from the system path. This two-file approach ensures that updates to the system package never directly overwrite user changes.

Safe Migration Strategy for Preserving User Overrides

To handle package updates without destroying user customizations, Omarchy implements a sophisticated migration system located in the migrations/ directory. The scripts use cryptographic hashing and defensive backups to determine when it is safe to refresh defaults.

Conditional Refresh Using SHA-256 Verification

In migrations/1788745941.sh, the system performs a stock-config refresh only when the user has not modified their configuration. The script computes the SHA-256 hash of the existing ~/.config/kitty/kitty.conf and compares it against the shipped default's hash.

If the hashes match, indicating the user file is pristine, the script executes:

omarchy-refresh-config kitty/kitty.conf

This command copies the fresh default while preserving the user's theme include line, ensuring the visual settings remain intact.

Backup and Sanitization of Modified Configs

When the user file differs from the default hash, the migration script takes a protective approach. As implemented in migrations/1788745941.sh lines 17-19, the system:

1. Creates a timestamped backup at $kitty_config.bak.* to preserve the exact state before migration.
2. Comments out disallowed lines (such as allow_remote_control true) that might conflict with system security policies.

This ensures that even if the user has extensively customized their terminal, their work is never lost—only temporarily disabled if it conflicts with essential defaults.

Essential Default Enforcement

Beyond the standard refresh mechanism, specific migrations ensure critical functionality remains available. The script migrations/1784479832.sh (lines 4-7) validates the presence of the listen_on directive, which enables Omarchy's global keybindings to communicate with the Kitty instance.

If this line is missing, the migration automatically appends it to the user configuration, guaranteeing that the desktop environment's keyboard shortcuts continue to function correctly after updates.

User Template Structure

The repository includes a user-side template at config/kitty/kitty.conf that serves as the initial content for new user configurations. This file contains only:

• The theme include directive
• Commented examples for personal overrides

Users are encouraged to edit this file directly, while the system file at /etc/xdg/kitty/kitty.conf remains strictly package-managed. This separation ensures that user overrides safely preserved remain isolated from system updates.

# Example: Adding custom font overrides to the user config

printf '\nfont_family "Fira Code"\nfont_size 13.0\n' >> ~/.config/kitty/kitty.conf

Verification via Test Suite

The behavior of this configuration system is validated by test/shell.d/kitty-config-test.sh. This test suite verifies that:

• Fresh stock configurations properly initialize the user template
• Backups are created during migrations
• File permissions remain at 600 (owner read/write only)
• Custom overrides survive the migration process intact

These automated checks ensure that the Kitty defaults loaded mechanism and preservation logic function correctly across system updates.

Summary

• Omarchy uses /etc/xdg/kitty/kitty.conf for system-wide defaults and ~/.config/kitty/kitty.conf for user overrides, with the user file taking precedence.
• The migration script migrations/1788745941.sh uses SHA-256 hashing to determine whether to refresh defaults or preserve existing user changes.
• When user modifications are detected, the system creates timestamped backups and sanitizes conflicting security settings rather than overwriting files.
• Critical settings like listen_on are enforced by migrations/1784479832.sh to maintain desktop integration.
• The test suite in test/shell.d/kitty-config-test.sh validates that user customizations survive package updates.

Frequently Asked Questions

Where does Omarchy store the system-wide Kitty configuration?

Omarchy ships the system-wide Kitty configuration at /etc/xdg/kitty/kitty.conf, which is owned and managed by the omarchy-settings package. This file serves as the foundation that Kitty reads first before processing any user-specific overrides.

What happens to my custom Kitty settings when Omarchy updates?

If you have modified ~/.config/kitty/kitty.conf, the migration script creates a timestamped backup (.bak.*) and comments out any lines that conflict with security requirements, but it does not delete or overwrite your file. If you have not modified the file, it receives the updated defaults automatically.

How can I manually refresh the default Kitty configuration?

You can force a refresh of the default configuration by running omarchy-refresh-config kitty/kitty.conf. However, this command only executes safely if your current user configuration matches the shipped default hash; otherwise, you must manually merge changes or reset your config file first.

Why does Omarchy require the listen_on setting in Kitty?

The listen_on setting enables Kitty to accept remote control commands via a Unix socket, which Omarchy's global keybindings use to manage terminal windows. The migration script migrations/1784479832.sh ensures this setting is present so that desktop environment shortcuts continue to function correctly across updates.

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