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

> Learn how Omarchy safely loads Kitty defaults and preserves user overrides using SHA-256 checks and backups, ensuring your customizations survive updates.

- Repository: [Omacom/omarchy](https://github.com/omacom/omarchy)
- Tags: internals
- Published: 2026-09-09

---

**Omarchy loads system-wide Kitty defaults from [`/etc/xdg/kitty/kitty.conf`](https://github.com/omacom/omarchy/blob/main//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`](https://github.com/omacom/omarchy/blob/main//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`](https://github.com/omacom/omarchy/blob/main/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:

```bash
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`](https://github.com/omacom/omarchy/blob/main/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`](https://github.com/omacom/omarchy/blob/main/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`](https://github.com/omacom/omarchy/blob/main/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`](https://github.com/omacom/omarchy/blob/main//etc/xdg/kitty/kitty.conf) remains strictly package-managed. This separation ensures that **user overrides safely preserved** remain isolated from system updates.

```bash

# 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`](https://github.com/omacom/omarchy/blob/main/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`](https://github.com/omacom/omarchy/blob/main//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`](https://github.com/omacom/omarchy/blob/main/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`](https://github.com/omacom/omarchy/blob/main/migrations/1784479832.sh) to maintain desktop integration.
- The test suite in [`test/shell.d/kitty-config-test.sh`](https://github.com/omacom/omarchy/blob/main/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`](https://github.com/omacom/omarchy/blob/main//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`](https://github.com/omacom/omarchy/blob/main/migrations/1784479832.sh) ensures this setting is present so that desktop environment shortcuts continue to function correctly across updates.