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

> Learn how Omarchy generates configuration files by staging, overlaying customizations, rendering templates, and atomically activating the result for your themes.

- Repository: [37signals/omarchy](https://github.com/basecamp/omarchy)
- Tags: internals
- Published: 2026-08-26

---

**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`](https://github.com/basecamp/omarchy/blob/main/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`](https://github.com/basecamp/omarchy/blob/main/colors.toml) file, the system automatically generates one by parsing [`alacritty.toml`](https://github.com/basecamp/omarchy/blob/main/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`](https://github.com/basecamp/omarchy/blob/main/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`:

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

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

```

Given a [`colors.toml`](https://github.com/basecamp/omarchy/blob/main/colors.toml) containing `background = "#1a1b26"` and `accent = "#7aa2f7"`, the rendered [`shell.toml`](https://github.com/basecamp/omarchy/blob/main/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:

```bash

# Activate the "catppuccin" theme

omarchy-theme-set catppuccin

```

After manually editing [`colors.toml`](https://github.com/basecamp/omarchy/blob/main/colors.toml) or template files, regenerate the configuration files without switching themes:

```bash

# Rerender templates for the current theme

omarchy-theme-set-templates

```

To preview how the color ramp from [`colors.toml`](https://github.com/basecamp/omarchy/blob/main/colors.toml) will render across the system:

```bash

# Preview color definitions

omarchy dev theme-preview catppuccin

```

Key source files driving this behavior include [`docs/theming.md`](https://github.com/basecamp/omarchy/blob/main/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`](https://github.com/basecamp/omarchy/blob/main/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`](https://github.com/basecamp/omarchy/blob/main/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`](https://github.com/basecamp/omarchy/blob/main/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.