How the Omarchy Theming System Works: A Deep Dive Into Themes, Templates, and Color Pipelines

Omarchy's theming system uses a layered pipeline that transforms palette files (particularly colors.toml) into fully-rendered desktop themes through template rendering with custom color helpers and a secure staging process.

The Omarchy distribution provides a sophisticated theming engine for Linux desktop environments. This system enables users and theme authors to define color palettes once, then automatically generate consistent configurations across shells, window managers, terminals, and system tools. Understanding how the Omarchy theming system works is essential for anyone customizing their desktop or creating shareable themes.

How Theme Sources Are Organized

Themes in Omarchy follow a hierarchical structure with clear precedence rules.

Built-in and User Theme Locations

System themes reside in /usr/share/omarchy/themes/<name>/ corresponding to the repository's themes/<name>/ directory. Users can override or extend these by creating themes in ~/.config/omarchy/themes/<name>/【⁄cache/repos/github.com/omacom/omarchy/quattro/docs/theming.md#L3-L5】.

Every theme requires a colors.toml file defining the color palette. Optional files include:

• shell.toml — Shell appearance configuration
• hyprland.lua — Hyprland window manager settings
• icons.theme — Icon theme specification
• Background images and other assets

The Theme Activation Pipeline

Running omarchy-theme-set <name> executes a carefully sequenced activation flow. This command creates a clean staging area at ~/.local/state/omarchy/current/next-theme before committing changes【⁄cache/repos/github.com/omacom/omarchy/quattro/docs/theming.md#L20-L28】.

Step-by-Step Activation Process

1. Copy base theme — The built-in theme files are copied from themes/<name>/.

2. Apply user overrides — Files from ~/.config/omarchy/themes/<name>/ are overlaid, with security filtering applied for Git-installed themes (see Security section below).

3. Generate missing palette — If colors.toml is absent, Omarchy generates one from an alacritty.toml file if present.

4. Render templates — The omarchy-theme-set-templates command processes all *.tpl files, substituting color placeholders with actual values.

5. Commit and notify — The staged theme moves to ~/.local/state/omarchy/current/theme, the theme name is recorded, and running shells receive notification.

During activation, the system executes theme-set hooks from ~/.config/omarchy/hooks/theme-set* and dispatches post-theme commands to restart or retint applications【⁄cache/repos/github.com/omacom/omarchy/quattro/docs/theming.md#L40-L45】.

Template Rendering and Color Helpers

The heart of how the Omarchy theming system works lies in its template engine. All files ending in .tpl under default/themed/ are processed by omarchy-theme-set-templates, which performs placeholder substitution using values from colors.toml【⁄cache/repos/github.com/omacom/omarchy/quattro/docs/theming.md#L31-L45】.

Core Placeholder Syntax

• {{ accent }} — Direct color value insertion
• {{ accent_strip }} — Color without leading # (e.g., ff5555)
• {{ accent_rgb }} — RGB tuple format (e.g., 255, 85, 85)

Advanced Color Operations

Color mixing enables subtle variations:

{{ mix background foreground 15% }}

This blends background and foreground colors by 15%, useful for hover states or subtle borders.

Gradient generation provides environment-specific outputs:

• {{ hypr_gradient hyprland_active_border accent }} — Emits a Lua table for Hyprland configuration
• {{ shell_gradient ... }} — Produces shell-compatible gradient tokens【⁄cache/repos/github.com/omacom/omarchy/quattro/docs/theming.md#L58-L71】

Template Precedence Rules

Rendered templates populate concrete files like shell.toml, hyprland.lua, and btop.theme. However, hand-written files always win: if a theme includes a custom shell.toml or hyprland.lua, these replace the generated versions【⁄cache/repos/github.com/omacom/omarchy/quattro/docs/theming.md#L31-L35】.

Users can apply system-wide customizations through ~/.config/omarchy/themed/*.tpl — these process before built-in templates, allowing per-user tweaks without modifying core files【⁄cache/repos/github.com/omacom/omarchy/quattro/docs/theming.md#L36-L38】.

Security and File Filtering

When themes install from Git repositories, Omarchy applies strict security filtering. The bin/omarchy-theme-set script contains an INSTALLED_THEME_DENIED constant listing forbidden file patterns【⁄cache/repos/github.com/omacom/omarchy/quattro/docs/theming.md#L60-L62】.

Blocked file types include:

• *.lua files (executable code)
• Terminal configuration files
• VS Code extensions

This filtering prevents untrusted themes from executing arbitrary code while still allowing visual customization【⁄cache/repos/github.com/omacom/omarchy/quattro/docs/theming.md#L48-L58】.

Key Implementation Files

Component	Path	Purpose
Theme activator	bin/omarchy-theme-set	Staging flow, filtering, hook dispatch
Template renderer	bin/omarchy-theme-set-templates	Processes .tpl files with palette substitution
Default templates	default/themed/*.tpl	Blueprint configurations for all themed applications
Required palette	themes/<name>/colors.toml	Central color definitions
Example theme	themes/solitude/colors.toml	Reference implementation
User templates	~/.config/omarchy/themed/*.tpl	Personal template overrides
Post-theme hooks	~/.config/omarchy/hooks/theme-set*	Custom scripts executed after theme application

Practical Examples

Activating a Theme

omarchy theme set solitude

This executes bin/omarchy-theme-set solitude, complete with staging, template rendering, and state updates under ~/.local/state/omarchy/current/.

Creating a Custom Palette

# ~/.config/omarchy/themes/my-theme/colors.toml

mode = "dark"
accent = "#ff5555"
background = "#282a36"
foreground = "#f8f8f2"

Run omarchy theme set my-theme to apply these colors across your desktop.

Overriding Generated Configuration

# ~/.config/omarchy/themes/my-theme/shell.toml

[notifications]
border = "#ff5555"
border-alpha = 0.7

This hand-written file supersedes the template-generated version, enabling surgical customization.

Template Placeholder Usage

Inside default/themed/shell.toml.tpl:

[notifications]
border = "{{ accent }}"
border-alpha = 0.85

With accent = "#ff5555" in colors.toml, the rendered shell.toml receives the resolved color value directly.

Summary

• Theme locations: System themes live in /usr/share/omarchy/themes/, user overrides in ~/.config/omarchy/themes/
• Activation command: omarchy-theme-set <name> stages, filters, renders, and commits themes atomically
• Template engine: .tpl files transform into configs via omarchy-theme-set-templates using colors.toml values
• Color helpers: Advanced functions support RGB conversion, hex stripping, mixing, and gradient generation
• Security model: Git-installed themes undergo file filtering to block executable content
• Override precedence: User templates → theme hand-written files → generated templates

Frequently Asked Questions

What files are required to create a working Omarchy theme?

A minimal theme requires only colors.toml with valid color definitions. Optional files like shell.toml, hyprland.lua, or background images extend functionality but aren't mandatory. If colors.toml is missing, Omarchy can generate one from an existing alacritty.toml file during activation.

How do I customize a theme without losing changes on updates?

Place overrides in ~/.config/omarchy/themes/<name>/ rather than modifying system files. For template-level changes, add *.tpl files to ~/.config/omarchy/themed/ — these process before built-in templates. Hand-written configuration files in your user theme directory always supersede generated versions.

Why are some files missing after installing a theme from Git?

Omarchy's security filter removes potentially dangerous files from Git-installed themes. The INSTALLED_THEME_DENIED list in bin/omarchy-theme-set blocks *.lua files, terminal configs, and VS Code extensions. This prevents malicious themes from executing code while preserving visual customization capabilities.

What hooks are available during theme activation?

The theme-set hook fires during activation — place executable scripts matching ~/.config/omarchy/hooks/theme-set* to run custom code. The system also dispatches post-theme commands that handle application restarts and retinting automatically, no manual configuration needed for supported applications.

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