How the Omarchy Theme System Generates Configuration Files: Staging, Rendering, and Activation

Omarchy generates configuration files by staging themes into a temporary directory, overlaying user customizations, and rendering *.tpl template files using color values from colors.toml, then atomically activating the result.

The Omarchy dotfiles repository (basecamp/omarchy) implements a sophisticated theming pipeline that deterministically produces configuration files from palettes and templates. This system ensures that every active theme combines a base color scheme with safe, generated configuration files while preserving user overrides and protecting against untrusted code.

The Three-Phase Configuration Generation Process

The Omarchy theme system generates configuration files through a strictly ordered pipeline involving three distinct phases: staging, rendering, and activation. According to the implementation in bin/omarchy-theme-set, this process isolates theme building from the active environment until the final atomic move.

Staging and Overlay

The process begins when you run omarchy-theme-set <name>. First, the system creates a clean staging directory at ~/.local/state/omarchy/current/next-theme. It then copies the first-party theme files from themes/<name>/ into this staging area.

If you have defined custom overrides under ~/.config/omarchy/themes/<name>/, the system overlays these files onto the staging directory. For hand-written themes, this performs a full copy; for cloned themes from remote repositories, it applies a filtered copy that respects security constraints. If the theme lacks a colors.toml file, the system automatically generates one by parsing alacritty.toml via the omarchy-theme-colors-from-alacritty helper.

Template Rendering with Color Palettes

Once staging is complete, the omarchy-theme-set-templates command processes every *.tpl file found in default/themed/ and user-wide templates in ~/.config/omarchy/themed/. These templates contain placeholders like {{ accent }} that the renderer replaces with values from the theme's colors.toml.

The template engine supports advanced color manipulation through helper functions including {{ mix … }} for color blending and {{ hypr_gradient … }} for generating Lua-compatible gradient expressions. Existing hand-written configuration files are never overwritten by this process, ensuring your manual edits persist across theme changes.

Activation and Safety Measures

In the final phase, omarchy-theme-set moves the completed staging directory to ~/.local/state/omarchy/current/theme, saves the active theme name, and notifies the running shell to reload configurations. Simultaneously, it dispatches the post_theme_commands list to retint running applications.

For themes installed from remote git repositories, the system enforces a deny-list defined in the INSTALLED_THEME_DENIED constant within bin/omarchy-theme-set. This security filter removes potentially executable files such as *.lua scripts and terminal configurations, replacing them with safe, generated equivalents from the built-in templates.

Template Syntax and File Locations

Templates in Omarchy are plain text files ending in the .tpl extension. The system differentiates between built-in templates shipped with the repository and user-wide custom templates stored in ~/.config/omarchy/themed/.

Here is a minimal example from default/themed/shell.toml.tpl:

[bar]
background = "{{ background }}"
foreground = "{{ foreground }}"

[[notifications]]
border = "{{ hypr_gradient hyprland_active_border accent }}"

Given a colors.toml containing background = "#1a1b26" and accent = "#7aa2f7", the rendered shell.toml will contain these concrete hexadecimal values and a properly formatted gradient expression for Hyprland.

The complete template rendering order prioritizes user templates in ~/.config/omarchy/themed/ before falling back to the default templates, allowing you to override specific configuration file generation without modifying core theme files.

Working with the Theme System

To activate a theme and trigger the full configuration generation pipeline:

# Activate the "catppuccin" theme

omarchy-theme-set catppuccin

After manually editing colors.toml or template files, regenerate the configuration files without switching themes:

# Rerender templates for the current theme

omarchy-theme-set-templates

To preview how the color ramp from colors.toml will render across the system:

# Preview color definitions

omarchy dev theme-preview catppuccin

Key source files driving this behavior include docs/theming.md (the canonical workflow documentation), bin/omarchy-theme-set (orchestration and deny-list logic), and bin/omarchy-theme-set-templates (the template rendering engine).

Summary

• Omarchy uses a staging directory (~/.local/state/omarchy/current/next-theme) to build themes before atomic activation, preventing partial configuration states.
• Templates use *.tpl files processed through a rendering engine that substitutes placeholders with values from colors.toml, supporting color mixing and gradient generation.
• User overrides take precedence: Files in ~/.config/omarchy/themes/<name>/ overlay base themes, and templates in ~/.config/omarchy/themed/ override built-in defaults.
• Security filtering protects against remote themes: The INSTALLED_THEME_DENIED deny-list in bin/omarchy-theme-set strips executable files from cloned themes.
• Existing files are preserved: The template renderer never overwrites hand-written configuration files, ensuring your customizations survive theme switches.

Frequently Asked Questions

How do I activate a new theme in Omarchy?

Run the command omarchy-theme-set <theme-name> where <theme-name> corresponds to a directory in themes/ or ~/.config/omarchy/themes/. This executes the complete pipeline: staging the theme, overlaying your customizations, rendering templates from colors.toml, and atomically moving the result to the active theme directory at ~/.local/state/omarchy/current/theme.

What files can I safely customize in an Omarchy theme?

You can customize any file in your user theme directory at ~/.config/omarchy/themes/<name>/, which overlays the base theme during staging. Additionally, you can create custom templates in ~/.config/omarchy/themed/*.tpl to override how specific configuration files are generated. Hand-written configuration files in the active theme directory are never overwritten by the template renderer.

How does Omarchy protect against malicious themes installed from git repositories?

When you install a theme from a remote repository, bin/omarchy-theme-set applies the INSTALLED_THEME_DENIED deny-list to filter the copied files. This list removes potentially dangerous files such as *.lua scripts and terminal emulator configurations, replacing them with safe versions generated from the built-in templates. Only color assets and non-executable theme data are retained from untrusted sources.

Can I modify the color palette without changing the entire theme?

Yes. Edit the colors.toml file in your active theme directory (located at ~/.local/state/omarchy/current/theme/colors.toml or in your user override at ~/.config/omarchy/themes/<name>/colors.toml), then run omarchy-theme-set-templates to regenerate all configuration files from the updated palette without triggering a full theme switch or reloading the shell environment.

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