How the Omarchy Theming Pipeline Generates Configuration Files

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 file, the pipeline automatically generates one by parsing an existing 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. Existing hand-written files like shell.toml or 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. 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/.

# 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:

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 or 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 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:

# Activate the "catppuccin-mocha" theme

omarchy-theme-set catppuccin-mocha

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

# 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 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 by parsing an existing 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.

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