# How the Omarchy Theming Pipeline Generates Configuration Files

> Learn how the Omarchy theming pipeline generates configuration files by staging themes, overlaying customizations, and rendering TOML templates with atomic activation.

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

---

**The Omarchy theming pipeline generates configuration files by staging themes in a temporary directory, overlaying user customizations, rendering TOML templates with color placeholders, and atomically activating the result while preventing race conditions through file locking.**

The **omarchy theming pipeline** in the `omacom/omarchy` repository transforms color definitions and template files into the live configuration consumed by the Quickshell desktop environment. This deterministic process ensures that both built-in themes and user customizations are merged safely before applications are retinted. Understanding how the pipeline generates configs allows developers to extend themes without breaking the active shell.

## The Seven-Stage Configuration Generation Process

The pipeline is orchestrated by the `omarchy-theme-set` command and follows a strict sequence defined in `bin/omarchy-theme-set`.

### 1. Creating the Staging Area

The pipeline begins by creating a clean working directory at `~/.local/state/omarchy/current/next-theme`. This temporary staging area ensures that incomplete or broken configurations never reach the live environment.

### 2. Copying the Base Theme

First-party themes located in `themes/<name>/` within the repository are copied into the staging directory. These files provide the foundational color definitions and structure required by the shell.

### 3. Overlaying User Customizations

Files placed in `~/.config/omarchy/themes/<name>/` are overlaid on top of the base theme. When a theme originates from a Git clone, the pipeline filters the copy operation to allow only a safe subset of color-related files, preventing arbitrary code execution from untrusted theme sources.

### 4. Generating Color Definitions

If the staged theme lacks a [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) file, the pipeline automatically generates one by parsing an existing [`alacritty.toml`](https://github.com/omacom/omarchy/blob/main/alacritty.toml). This ensures that every theme provides the standardized color definitions required for template rendering.

### 5. Rendering Templates

The `omarchy-theme-set-templates` command processes every `*.tpl` file found in `default/themed/` and `~/.config/omarchy/themed/`. It substitutes placeholders—such as `{{ accent }}`, `{{ mix ... }}`, and gradient helpers like `{{ hypr_gradient ... }}`—with actual hex values from [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml). Existing hand-written files like [`shell.toml`](https://github.com/omacom/omarchy/blob/main/shell.toml) or [`hyprland.lua`](https://github.com/omacom/omarchy/blob/main/hyprland.lua) take precedence over generated counterparts and are never overwritten.

### 6. Atomic Activation

Once rendering completes, the fully staged theme is moved atomically to `~/.local/state/omarchy/current/theme`. The theme name is written to `~/.local/state/omarchy/current/theme.name`, and the `theme-set` hook is fired. A serialized **flock** guarantees that concurrent theme changes queue sequentially rather than racing, ensuring configuration consistency.

### 7. Retinting Running Applications

After activation, the pipeline executes a list of post-theme commands defined in `bin/omarchy-theme-set` to restart or retint terminals, Hyprland, btop, browsers, and editors. This ensures that all applications immediately adopt the new color scheme without requiring a full session restart.

## Template Syntax and User Overrides

Templates use Mustache-style placeholders that resolve against the theme’s [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml). Users can extend or override built-in templates by placing custom `*.tpl` files in `~/.config/omarchy/themed/`, which the pipeline discovers alongside the defaults in `default/themed/`.

```bash

# Example of a template placeholder substitution

# In default/themed/shell.toml.tpl:

#   background = "{{ background }}"

# After rendering → background = "#1a1b26"

```

To manually render templates for debugging or custom directories:

```bash
omarchy-theme-set-templates \
  ~/.local/state/omarchy/current/next-theme \
  ~/.config/omarchy/themed/*.tpl

```

## Concurrency Safety and File Precedence

The pipeline enforces strict safety rules to prevent configuration corruption. **File precedence** dictates that existing files in the theme directory always win over generated ones, protecting manual edits to [`shell.toml`](https://github.com/omacom/omarchy/blob/main/shell.toml) or [`hyprland.lua`](https://github.com/omacom/omarchy/blob/main/hyprland.lua). For themes installed via Git clone, only color-related assets are copied, isolating the system from potentially malicious scripts. The use of **flock** serialization ensures that rapid successive calls to `omarchy-theme-set` execute in order rather than interleaving file operations.

## Key Files and Activation Commands

All logic is documented in [`docs/theming.md`](https://github.com/omacom/omarchy/blob/main/docs/theming.md) and implemented across these critical paths:

- **`bin/omarchy-theme-set`** – Main orchestration script handling staging, overlay, and activation.
- **`bin/omarchy-theme-set-templates`** – Template engine responsible for placeholder substitution.
- **`default/themed/*.tpl`** – Built-in template files shipped with Omarchy.
- **`~/.config/omarchy/themed/*.tpl`** – User-level template overrides.

To activate a theme and trigger the full pipeline:

```bash

# Activate the "catppuccin-mocha" theme

omarchy-theme-set catppuccin-mocha

```

To preview a theme's color ramp without applying it:

```bash

# Inspect the colour ramp for a theme (useful for debugging)

omarchy dev theme-preview catppuccin-mocha

```

## Summary

- The **omarchy theming pipeline** uses a seven-stage process to build and activate desktop configurations atomically.
- Templates are rendered only when a [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) is present, with user files in `~/.config/omarchy/themed/` overriding defaults.
- The staging area at `~/.local/state/omarchy/current/next-theme` ensures that incomplete configurations never go live.
- **Flock** serialization prevents race conditions during concurrent theme switches.
- Git-cloned themes are filtered to prevent arbitrary code execution.

## Frequently Asked Questions

### How do I activate a custom theme in Omarchy?

Run `omarchy-theme-set <name>` where `<name>` corresponds to a directory in `themes/` or `~/.config/omarchy/themes/`. This command triggers the full pipeline, staging the theme, rendering templates, and retinting all running applications to match the new color scheme.

### What happens if a theme is missing colors.toml?

The pipeline automatically generates [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) by parsing an existing [`alacritty.toml`](https://github.com/omacom/omarchy/blob/main/alacritty.toml) file in the theme directory. This generated file then feeds the template engine, ensuring that placeholders like `{{ accent }}` resolve to valid hex values during the render phase.

### Where should I place custom templates to override Omarchy defaults?

Place your custom `*.tpl` files in `~/.config/omarchy/themed/`. The `omarchy-theme-set-templates` command processes these user templates alongside the built-in files in `default/themed/`, with your versions taking precedence if filenames collide.

### How does Omarchy prevent race conditions during theme switching?

The `omarchy-theme-set` script uses a serialized **flock** (file lock) mechanism. If multiple theme change requests occur simultaneously, they queue and execute sequentially rather than racing to write the `~/.local/state/omarchy/current/theme` directory, which guarantees configuration integrity.